A local-first multi-agent app development platform, built on PenguinHarness
/**
* AgentClient against a scripted AMSP server (the package's one fetch fake).
*
* Runs and their streams
* - Iterating a run yields the server's events in order and stops at [DONE]: nothing after it is
* read, and the connection is closed.
* - A run POSTs its input, and the Session to continue, as JSON to the Agent's runs route, with
* the key as a Bearer token and the caller's extra headers; a keyless client sends no
* Authorization.
* - result() joins the main Session's assistant texts and keeps every complete item, on the order
* the server captured: user texts, a subagent's texts and compaction summaries stay out of the
* text; a summary the engine streamed has no summary.done and leaves no item (fragments are
* never rebuilt into one), one delivered whole is kept as its summary.done.
* - A run that ends fatal resolves with that status and error; it does not reject.
* - session resolves from run.started while the server still holds back the first content event.
* - Keep-alive comments, CRLF framing, chunks split mid-event and a data block spread over two
* lines leave the events intact.
* - An event type the client does not know reaches the iterator and the items.
* - Leaving the loop early stops the iteration, not the run: the connection stays open and
* result() still resolves.
* - Events are kept for an iteration that starts after the run ended, and a finished iteration
* keeps answering done.
* - A run's events can be iterated once.
*
* Failures
* - A refusal before the stream rejects the run, its session and its iteration with an
* AmspHttpError carrying the status and the envelope's code; a body that is not the envelope
* reads as `http_error` with the start of the body.
* - A stream that ends, says [DONE] or breaks before run.done is an AmspStreamError, raised by
* the iteration after the events that did arrive; one that ends or breaks after run.done still
* resolves.
* - A 200 answer that is not an event stream (saying what came instead), and a block that is not
* an AMSP event, are AmspStreamErrors.
*
* Approvals (on the captured order: the engine runs the tool while its Request is still open, so
* approval.requested, approval.decided and the first result fragment precede request.done, and
* the rest of the result follows it)
* - An approval request is answered by POST with the callback's decision, even when the caller
* only awaits the result; no callback, or a throwing one, answers deny.
* - The result of such a run carries the next Request's text and one tool_result.done for the
* call, whichever side of request.done its fragments fell on.
* - An approval someone else answered first does not fail the run, and an answer that fails after
* the run completed leaves it completed.
* - An approval the server refuses to take ends the run with that refusal and closes the
* connection, so the server aborts the run instead of waiting for good.
*
* Aborts
* - Aborting the signal mid-stream closes the connection and rejects with the signal's AbortError,
* whether the fetch errors the body itself or leaves it to the reader.
* - The iteration stops at once when the signal aborts, and events not yet read are dropped.
* - A signal that aborts between two events of one chunk rejects the run with the abort reason,
* even when the next event buffered behind it is `[DONE]`: a cancelled run is never reported as
* completed.
* - A signal that aborts as the response arrives rejects without waiting for the stream; one
* aborted before the run sends nothing.
* - run.abort() asks the server to abort and the stream ends with run.done aborted; on a run that
* is over, or was refused, it sends nothing.
*
* The rest of the surface
* - agent() and session() read the Agent and one of its Sessions; an unknown Session is an
* AmspHttpError.
* - abort(sessionId) says whether a run was interrupted; approve() posts a decision and reports
* one already taken as approval_not_found.
* - parseArguments returns the arguments object, {} for none, and null for anything malformed;
* a tool_call.done's arguments (the engine's serialization of the parsed call) and its
* fragments joined (the provider's text) parse to the same object although their text differs.
* - An agent reference that is not <projectId>/<agentId> is refused at construction.
* - A fetch handed to the client carries its requests instead of the global one.
*/
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import {
AgentClient,
AmspHttpError,
AmspStreamError,
parseArguments,
type AmspEvent,
type RunOptions,
} from "../src/index.js";
import {
BASE_URL,
DONE,
createFetchFake,
frame,
gate,
never,
type FetchFake,
type Step,
} from "./helpers/fetch-fake.js";
import { APPROVAL_ROUND_TRIP, MIXED_RUN, sessionOf } from "./helpers/streams.js";
const AT = "2026-10-07T10:00:00.000Z";
const SESSION = "session-2026-10-07-10-00-00-3f9a1c2e";
const KEY = "test-agent-key";
const RUNS = "/agents/demo/coder/runs";
const APPROVAL = `/sessions/${SESSION}/approvals/call_1`;
const USAGE = { cache_read: 0, cache_write: 0, output: 2, total: 412 };
/** The approval route of the captured round trip's Session. */
const ROUND_TRIP_SESSION = sessionOf(APPROVAL_ROUND_TRIP);
const ROUND_TRIP_APPROVAL = `/sessions/${ROUND_TRIP_SESSION}/approvals/call_1`;
const ROUND_TRIP_REQUESTED = APPROVAL_ROUND_TRIP.find((e) => e.type === "approval.requested")!;
function ev(type: string, fields: Record<string, unknown> = {}): AmspEvent {
return { type, at: AT, ...fields } as AmspEvent;
}
const started = ev("run.started", { session_id: SESSION, agent: "demo/coder" });
const runDone = (fields: Record<string, unknown> = {}) =>
ev("run.done", {
status: "completed",
requests: 1,
usage: USAGE,
session_usage: USAGE,
...fields,
});
/** A plain answer, as the protocol reference shows it. */
const PLAIN = [
started,
ev("request.started", { request: 1 }),
ev("text.delta", { role: "assistant", text: "" }),
ev("text.delta", { role: "assistant", text: "Hello" }),
ev("text.delta", { role: "assistant", text: "!" }),
ev("text.done", { role: "assistant", text: "Hello!", stop_reason: "completed" }),
ev("request.done", { request: 1, status: "completed", usage: USAGE }),
runDone(),
];
const APPROVAL_REQUESTED = ev("approval.requested", {
tool_call: { tool_call_id: "call_1", name: "exec_command", arguments: '{"command":"ls"}' },
});
/**
* The captured round trip: the server holds the stream at approval.requested until `answered`
* settles, then the tool runs — its decision and first result fragment before request.done, the
* rest of the result after it, then the second Request.
*/
function approvalScript(answered: Promise<unknown>): Step[] {
const asked = APPROVAL_ROUND_TRIP.indexOf(ROUND_TRIP_REQUESTED) + 1;
return [
...APPROVAL_ROUND_TRIP.slice(0, asked).map(frame),
answered,
...APPROVAL_ROUND_TRIP.slice(asked).map(frame),
DONE,
];
}
async function collect(run: AsyncIterable<AmspEvent>): Promise<AmspEvent[]> {
const events: AmspEvent[] = [];
for await (const event of run) events.push(event);
return events;
}
let fake: FetchFake;
let client: AgentClient;
beforeEach(() => {
fake = createFetchFake();
vi.stubGlobal("fetch", fake.fetch);
client = new AgentClient({ baseUrl: BASE_URL, agent: "demo/coder", apiKey: KEY });
});
afterEach(() => {
vi.unstubAllGlobals();
});
describe("a run's stream", () => {
it("yields the server's events in order and stops at [DONE]", async () => {
const served = fake.stream("POST", RUNS, [
...PLAIN.map(frame),
DONE,
frame(ev("text.done", { role: "assistant", text: "after the end" })),
]);
expect(await collect(client.run({ input: "hi" }))).toEqual(PLAIN);
expect(served.closed).toBe(true);
});
it("posts the input and the Session to continue to the Agent's runs route, with the key and the caller's headers", async () => {
client = new AgentClient({
baseUrl: `${BASE_URL}/`,
agent: "demo/coder",
apiKey: KEY,
headers: { "X-Request-Source": "nightly-report" },
});
fake.stream("POST", RUNS, [...PLAIN.map(frame), DONE]);
const input: RunOptions["input"] = [
{ type: "text", text: "What is in this picture?" },
{ type: "image_url", image_url: "data:image/png;base64,iVBORw0KGgo=" },
];
await client.ask({ sessionId: SESSION, input });
expect(fake.calls).toHaveLength(1);
const [call] = fake.calls;
expect(call).toMatchObject({
method: "POST",
path: RUNS,
body: { session_id: SESSION, input },
});
expect(call!.headers.get("authorization")).toBe(`Bearer ${KEY}`);
expect(call!.headers.get("content-type")).toBe("application/json");
expect(call!.headers.get("accept")).toBe("text/event-stream");
expect(call!.headers.get("x-request-source")).toBe("nightly-report");
});
it("sends no Authorization from a keyless client", async () => {
client = new AgentClient({ baseUrl: BASE_URL, agent: "demo/coder" });
fake.stream("POST", RUNS, [...PLAIN.map(frame), DONE]);
await client.ask({ input: "hi" });
expect(fake.calls[0]!.headers.has("authorization")).toBe(false);
expect(fake.calls[0]!.body).toEqual({ input: "hi" });
});
it("joins the main Session's assistant texts in result(), leaving deltas, user texts, a subagent's texts and a streamed summary out", async () => {
fake.stream("POST", RUNS, [...MIXED_RUN.map(frame), DONE]);
const result = await client.ask({ input: "Fix the build" });
expect(result).toMatchObject({
status: "completed",
sessionId: sessionOf(MIXED_RUN),
text: "Working on it.\n\nDone: the build is green.",
usage: { output: 18, total: 1100 },
sessionUsage: { output: 15, total: 900 },
requests: 3,
});
expect(result).not.toHaveProperty("error");
expect(result.items.map((item) => item.type)).toEqual([
"run.started",
"request.started",
"text.done",
"request.done",
"text.done", // the steering text, role user
"context.opened", // the subagent's Session
"request.started",
"text.done",
"request.done",
"compaction.started",
"compaction.done", // the summary was streamed: no summary.done, and none is rebuilt
"request.started",
"text.done",
"request.done",
"run.done",
]);
expect(result.items.find((item) => item.type === "context.opened")).toMatchObject({
origin: ["session-2026-10-07-10-00-01-c0000001"],
});
});
it("keeps a summary the engine delivered whole as its summary.done item, still out of the text", async () => {
const summary = ev("summary.done", { text: "The whole summary.", stop_reason: "completed" });
fake.stream("POST", RUNS, [
frame(started),
frame(ev("request.started", { request: 1 })),
frame(ev("text.done", { role: "assistant", text: "Before.", stop_reason: "completed" })),
frame(ev("request.done", { request: 1, status: "completed", usage: USAGE })),
frame(
ev("compaction.started", { reason: "manual", mode: "summarize", context: 10, turns: 1 }),
),
frame(summary),
frame(ev("compaction.done", { reason: "manual", mode: "summarize", status: "completed" })),
frame(runDone()),
DONE,
]);
const result = await client.ask({ input: "hi" });
expect(result.text).toBe("Before.");
expect(result.items.filter((item) => item.type.startsWith("summary."))).toEqual([summary]);
});
it("resolves a run that ended fatal with its status and error", async () => {
const error = { code: "auth", message: "401 invalid x-api-key" };
fake.stream("POST", RUNS, [
frame(started),
frame(ev("request.started", { request: 1 })),
frame(ev("request.done", { request: 1, status: "fatal", usage: null, error, attempt: 1 })),
frame(runDone({ status: "fatal", error })),
DONE,
]);
await expect(client.ask({ input: "hi" })).resolves.toMatchObject({
status: "fatal",
error,
text: "",
});
});
it("resolves the session from run.started while the server holds back the first content event", async () => {
const hold = gate();
fake.stream("POST", RUNS, [frame(started), hold.promise, ...PLAIN.slice(1).map(frame), DONE]);
const run = client.run({ input: "hi" });
await expect(run.session).resolves.toBe(SESSION);
hold.open();
await expect(run.result()).resolves.toMatchObject({ sessionId: SESSION, text: "Hello!" });
});
it("reads events through keep-alive comments, CRLF framing, split chunks and a two-line data block", async () => {
const twoLines =
'data: {"type":"text.done","at":"2026-10-07T10:00:00.000Z",\r\ndata: "role":"assistant","text":"Hello!","stop_reason":"completed"}\r\n\r\n';
const wire = [
frame(started),
": keep-alive\n\n",
frame(ev("request.started", { request: 1 })),
twoLines,
": keep-alive\n\n",
frame(runDone()),
DONE,
]
.join("")
.replaceAll(/(?<!\r)\n/g, "\r\n");
const chunks = wire.match(/[\s\S]{1,7}/g)!;
fake.stream("POST", RUNS, chunks);
const events = await collect(client.run({ input: "hi" }));
expect(events.map((event) => event.type)).toEqual([
"run.started",
"request.started",
"text.done",
"run.done",
]);
expect(events[2]).toMatchObject({ role: "assistant", text: "Hello!" });
});
it("passes an event type it does not know to the iterator and the items", async () => {
const unknown = ev("plan.updated", { steps: ["read", "summarize"] });
fake.stream("POST", RUNS, [frame(started), frame(unknown), frame(runDone()), DONE]);
const run = client.run({ input: "hi" });
expect(await collect(run)).toContainEqual(unknown);
expect((await run.result()).items).toContainEqual(unknown);
});
it("keeps the run going when the loop is left early, so result() still resolves", async () => {
const hold = gate();
const served = fake.stream("POST", RUNS, [
frame(started),
hold.promise,
...PLAIN.slice(1).map(frame),
DONE,
]);
const run = client.run({ input: "hi" });
for await (const event of run) {
expect(event.type).toBe("run.started");
break;
}
expect(served.closed).toBe(false);
hold.open();
await expect(run.result()).resolves.toMatchObject({ status: "completed", text: "Hello!" });
expect(fake.calls.map((call) => call.path)).toEqual([RUNS]);
});
it("keeps every event for an iteration that starts after the run ended", async () => {
fake.stream("POST", RUNS, [...PLAIN.map(frame), DONE]);
const run = client.run({ input: "hi" });
await run.result();
expect(await collect(run)).toEqual(PLAIN);
});
it("keeps answering done once the iteration has finished", async () => {
fake.stream("POST", RUNS, [...PLAIN.map(frame), DONE]);
const iterator = client.run({ input: "hi" })[Symbol.asyncIterator]();
while (!(await iterator.next()).done);
await expect(iterator.next()).resolves.toEqual({ value: undefined, done: true });
});
it("refuses to iterate a run's events twice", async () => {
fake.stream("POST", RUNS, [...PLAIN.map(frame), DONE]);
const run = client.run({ input: "hi" });
await collect(run);
expect(() => run[Symbol.asyncIterator]()).toThrow(TypeError);
});
});
describe("a run that fails", () => {
it.each([
{
answer: "the error envelope",
status: 401,
body: '{"error":{"code":"unauthorized","message":"This Agent requires an API key."}}',
expected: { status: 401, code: "unauthorized", message: "This Agent requires an API key." },
},
{
answer: "an envelope without a message",
status: 403,
body: '{"error":{"code":"agent_api_disabled"}}',
expected: { status: 403, code: "agent_api_disabled", message: "agent_api_disabled" },
},
{
answer: "a body that is not the envelope",
status: 502,
body: "<html>Bad Gateway</html>",
expected: { status: 502, code: "http_error", message: "HTTP 502: <html>Bad Gateway</html>" },
},
])(
"rejects the run, its session and its iteration with an AmspHttpError read from $answer",
async ({ status, body, expected }) => {
fake.text("POST", RUNS, status, body, "application/json");
const run = client.run({ input: "hi" });
for (const outcome of [run.result(), run.session, collect(run)]) {
const error = await outcome.then(
() => null,
(err: unknown) => err,
);
expect(error).toBeInstanceOf(AmspHttpError);
expect(error).toMatchObject(expected);
}
},
);
it.each([
{ how: "ends", tail: [] as Step[] },
{ how: "says [DONE]", tail: [DONE] as Step[] },
{ how: "breaks", tail: [{ fail: new TypeError("terminated") }] as Step[] },
])(
"is an AmspStreamError, after the events that did arrive, when the stream $how before run.done",
async ({ tail }) => {
fake.stream("POST", RUNS, [...PLAIN.slice(0, 4).map(frame), ...tail]);
const run = client.run({ input: "hi" });
await expect(run.result()).rejects.toBeInstanceOf(AmspStreamError);
const seen: AmspEvent[] = [];
const iteration = (async () => {
for await (const event of run) seen.push(event);
})();
await expect(iteration).rejects.toBeInstanceOf(AmspStreamError);
expect(seen).toEqual(PLAIN.slice(0, 4));
},
);
it.each([
{ how: "ends", tail: [] as Step[] },
{ how: "breaks", tail: [{ fail: new TypeError("terminated") }] as Step[] },
])("still resolves when the stream $how after run.done", async ({ tail }) => {
fake.stream("POST", RUNS, [...PLAIN.map(frame), ...tail]);
await expect(client.ask({ input: "hi" })).resolves.toMatchObject({ status: "completed" });
});
it.each([
{
answer: "an HTML page",
serve: (f: FetchFake) => f.text("POST", RUNS, 200, "<!doctype html>", "text/html"),
named: "text/html",
},
{
answer: "an empty answer",
serve: (f: FetchFake) => f.empty("POST", RUNS, 200),
named: "without a content type",
},
])(
"is an AmspStreamError saying what came instead when a 200 answer is $answer",
async ({ serve, named }) => {
serve(fake);
const error = await client.ask({ input: "hi" }).catch((err: unknown) => err);
expect(error).toBeInstanceOf(AmspStreamError);
expect((error as Error).message).toContain(named);
},
);
it.each([
{ block: "not JSON", data: "data: {not json\n\n" },
{ block: "JSON without a type", data: 'data: {"session_id":"x"}\n\n' },
])("is an AmspStreamError when a block is $block", async ({ data }) => {
const served = fake.stream("POST", RUNS, [frame(started), data, never()]);
await expect(client.ask({ input: "hi" })).rejects.toBeInstanceOf(AmspStreamError);
expect(served.closed).toBe(true);
});
});
describe("approvals", () => {
it.each([
{ callback: "no callback", onApproval: undefined, decision: "deny" },
{ callback: "a callback that allows", onApproval: () => "allow" as const, decision: "allow" },
{
callback: "an async callback that denies",
onApproval: async () => "deny" as const,
decision: "deny",
},
{
callback: "a callback that throws",
onApproval: () => {
throw new Error("no terminal to ask");
},
decision: "deny",
},
])(
"answers with $decision for $callback, while the caller only awaits the result",
async ({ onApproval, decision }) => {
fake.empty("POST", ROUND_TRIP_APPROVAL, 204);
fake.stream("POST", RUNS, approvalScript(fake.requested("POST", ROUND_TRIP_APPROVAL)));
await expect(client.ask({ input: "List the files", onApproval })).resolves.toMatchObject({
status: "completed",
});
const answer = fake.calls.find((call) => call.path === ROUND_TRIP_APPROVAL)!;
expect(answer.body).toEqual({ decision });
expect(answer.headers.get("authorization")).toBe(`Bearer ${KEY}`);
},
);
it("hands the callback the request and the Session it belongs to", async () => {
fake.empty("POST", ROUND_TRIP_APPROVAL, 204);
fake.stream("POST", RUNS, approvalScript(fake.requested("POST", ROUND_TRIP_APPROVAL)));
const asked: unknown[] = [];
await client.ask({
input: "List the files",
onApproval: (request, ctx) => {
asked.push({ request, ctx });
return parseArguments(request.tool_call)?.command === "ls" ? "allow" : "deny";
},
});
expect(asked).toEqual([
{ request: ROUND_TRIP_REQUESTED, ctx: { sessionId: ROUND_TRIP_SESSION } },
]);
expect(fake.calls.find((call) => call.path === ROUND_TRIP_APPROVAL)!.body).toEqual({
decision: "allow",
});
});
it("collects the next Request's text and one tool_result.done for a tool that ran inside its Request", async () => {
fake.empty("POST", ROUND_TRIP_APPROVAL, 204);
fake.stream("POST", RUNS, approvalScript(fake.requested("POST", ROUND_TRIP_APPROVAL)));
const result = await client.ask({ input: "List the files", onApproval: () => "allow" });
expect(result).toMatchObject({
status: "completed",
sessionId: ROUND_TRIP_SESSION,
text: "Two entries: README.md and src.",
requests: 2,
});
// The result's fragments fell on both sides of request.done; its one .done closes it.
expect(result.items.map((item) => item.type)).toEqual([
"run.started",
"request.started",
"tool_call.done",
"approval.requested",
"approval.decided",
"request.done",
"tool_result.done",
"request.started",
"text.done",
"request.done",
"run.done",
]);
expect(result.items.find((item) => item.type === "tool_result.done")).toMatchObject({
tool_call_id: "call_1",
output: "README.md\nsrc\n",
});
});
it("finishes the run when someone else answered the approval first", async () => {
fake.json("POST", ROUND_TRIP_APPROVAL, 404, {
error: { code: "approval_not_found", message: "This approval was already decided." },
});
fake.stream("POST", RUNS, approvalScript(fake.requested("POST", ROUND_TRIP_APPROVAL)));
await expect(
client.ask({ input: "List the files", onApproval: () => "allow" }),
).resolves.toMatchObject({
status: "completed",
});
});
it("leaves a completed run as it was when an answer fails after the run ended", async () => {
const late = gate();
fake.json(
"POST",
APPROVAL,
500,
{ error: { code: "internal", message: "boom" } },
late.promise,
);
fake.stream("POST", RUNS, [
frame(started),
frame(APPROVAL_REQUESTED),
fake.requested("POST", APPROVAL),
frame(ev("approval.decided", { tool_call_id: "call_1", decision: "deny" })),
frame(runDone()),
DONE,
]);
const run = client.run({ input: "list the files" });
await expect(run.result()).resolves.toMatchObject({ status: "completed" });
const answer = await fake.requested("POST", APPROVAL);
const failed = new Promise((resolve) => answer.signal!.addEventListener("abort", resolve));
late.open();
await failed;
expect((await collect(run)).map((event) => event.type)).toEqual([
"run.started",
"approval.requested",
"approval.decided",
"run.done",
]);
});
it("ends the run with the server's refusal to take an answer, and closes the connection", async () => {
fake.json("POST", ROUND_TRIP_APPROVAL, 401, {
error: { code: "unauthorized", message: "This Agent requires an API key." },
});
const served = fake.stream("POST", RUNS, approvalScript(never()));
await expect(client.ask({ input: "List the files" })).rejects.toMatchObject({
status: 401,
code: "unauthorized",
});
expect(served.closed).toBe(true);
});
});
describe("aborting", () => {
it.each([
{ fetch: "a fetch that errors the body on abort", abortErrorsBody: true },
{ fetch: "a fetch that leaves the body to its reader", abortErrorsBody: false },
])(
"closes the connection and rejects with the AbortError when the signal aborts mid-stream, through $fetch",
async ({ abortErrorsBody }) => {
const controller = new AbortController();
const served = fake.stream(
"POST",
RUNS,
[
...PLAIN.slice(0, 4).map(frame),
() => {
controller.abort();
return never();
},
],
{ abortErrorsBody },
);
const run = client.run({ input: "hi", signal: controller.signal });
const error = await run.result().catch((err: unknown) => err);
expect(error).toBe(controller.signal.reason);
expect(error).toMatchObject({ name: "AbortError" });
await expect(collect(run)).rejects.toBe(controller.signal.reason);
expect(served.closed).toBe(true);
},
);
it("stops the iteration at once when the loop aborts the signal", async () => {
fake.stream("POST", RUNS, [...PLAIN.map(frame), DONE]);
const controller = new AbortController();
const run = client.run({ input: "hi", signal: controller.signal });
const seen: string[] = [];
const iteration = (async () => {
for await (const event of run) {
seen.push(event.type);
if (event.type === "text.delta") controller.abort();
}
})();
const error = await iteration.catch((err: unknown) => err);
expect(error).toBe(controller.signal.reason);
expect(seen).toEqual(["run.started", "request.started", "text.delta"]);
});
// One chunk carries both the last event and `[DONE]`, and the caller aborts in between: the
// buffered `[DONE]` used to end the read quietly, so the run resolved `completed`.
it("rejects a run aborted before a buffered [DONE] instead of reporting it completed", async () => {
const served = fake.stream("POST", RUNS, [frame(started) + frame(runDone()) + DONE, never()]);
const controller = new AbortController();
const run = client.run({ input: "hi", signal: controller.signal });
const seen: string[] = [];
const iteration = (async () => {
for await (const event of run) {
seen.push(event.type);
if (event.type === "run.done") controller.abort();
}
})();
const error = await iteration.catch((err: unknown) => err);
expect(error).toBe(controller.signal.reason);
expect(seen).toEqual(["run.started", "run.done"]);
await expect(run.result()).rejects.toBe(controller.signal.reason);
expect(served.closed).toBe(true);
});
it("drops the events not yet read when the signal aborts while the reader lags behind", async () => {
fake.stream("POST", RUNS, [...PLAIN.slice(0, 4).map(frame), never()]);
const controller = new AbortController();
const run = client.run({ input: "hi", signal: controller.signal });
await run.session;
controller.abort();
await expect(run.result()).rejects.toBe(controller.signal.reason);
const seen: AmspEvent[] = [];
const iteration = (async () => {
for await (const event of run) seen.push(event);
})();
await expect(iteration).rejects.toBe(controller.signal.reason);
expect(seen).toEqual([]);
});
it("rejects without waiting for the stream when the signal aborts as the response arrives", async () => {
const served = fake.stream("POST", RUNS, [never()]);
const controller = new AbortController();
client = new AgentClient({
baseUrl: BASE_URL,
agent: "demo/coder",
apiKey: KEY,
fetch: async (input, init) => {
const response = await fake.fetch(input, init);
controller.abort();
return response;
},
});
const error = await client.ask({ input: "hi", signal: controller.signal }).catch((err) => err);
expect(error).toBe(controller.signal.reason);
expect(served.closed).toBe(true);
});
it("sends nothing for a signal aborted before the run", async () => {
const controller = new AbortController();
controller.abort();
await expect(client.ask({ input: "hi", signal: controller.signal })).rejects.toBe(
controller.signal.reason,
);
expect(fake.calls).toEqual([]);
});
it("asks the server to abort with run.abort(), and the stream ends with run.done aborted", async () => {
const abortPath = `/sessions/${SESSION}/abort`;
const userAbort = { code: "user_abort", message: "Aborted by the API caller." };
fake.empty("POST", abortPath, 202);
fake.stream("POST", RUNS, [
...PLAIN.slice(0, 4).map(frame),
fake.requested("POST", abortPath),
frame(ev("text.done", { role: "assistant", text: "Hello", stop_reason: "aborted" })),
frame(ev("request.done", { request: 1, status: "aborted", usage: null, attempt: 1 })),
frame(runDone({ status: "aborted", error: userAbort, session_usage: null })),
DONE,
]);
const run = client.run({ input: "hi" });
await run.session;
await run.abort();
await expect(run.result()).resolves.toMatchObject({
status: "aborted",
error: userAbort,
text: "Hello",
});
});
it.each([
{
run: "a run that is over",
script: (f: FetchFake) => f.stream("POST", RUNS, [...PLAIN.map(frame), DONE]),
},
{
run: "a refused run",
script: (f: FetchFake) =>
f.json("POST", RUNS, 429, { error: { code: "too_many_runs", message: "Busy." } }),
},
])("sends nothing when run.abort() is called on $run", async ({ script }) => {
script(fake);
const run = client.run({ input: "hi" });
await run.result().catch(() => {});
await run.abort();
expect(fake.calls.map((call) => call.path)).toEqual([RUNS]);
});
});
describe("the rest of the client", () => {
it("reads the Agent and one of its Sessions, and reports an unknown Session as an AmspHttpError", async () => {
const agent = { id: "demo/coder", name: "Coder", description: "Writes and reviews code." };
const session = {
id: SESSION,
agent: "demo/coder",
status: "idle",
provider: "deepseek",
model_id: "deepseek-chat",
created_at: AT,
last_active_at: AT,
};
fake.json("GET", "/agents/demo/coder", 200, { agent });
fake.json("GET", `/sessions/${SESSION}`, 200, { session });
fake.json("GET", "/sessions/session-unknown", 404, {
error: { code: "session_not_found", message: "No such API Session." },
});
await expect(client.agent()).resolves.toEqual(agent);
await expect(client.session(SESSION)).resolves.toEqual(session);
await expect(client.session("session-unknown")).rejects.toMatchObject({
status: 404,
code: "session_not_found",
});
});
it("says whether abort(sessionId) interrupted a run", async () => {
fake.empty("POST", `/sessions/${SESSION}/abort`, 202);
fake.empty("POST", "/sessions/session-idle/abort", 204);
await expect(client.abort(SESSION)).resolves.toBe(true);
await expect(client.abort("session-idle")).resolves.toBe(false);
});
it("posts a decision with approve(), and reports one already taken as approval_not_found", async () => {
fake.empty("POST", APPROVAL, 204);
fake.json("POST", `/sessions/${SESSION}/approvals/call_2`, 404, {
error: { code: "approval_not_found", message: "This approval was already decided." },
});
await client.approve(SESSION, "call_1", "allow");
await expect(client.approve(SESSION, "call_2", "deny")).rejects.toMatchObject({
status: 404,
code: "approval_not_found",
});
expect(fake.calls.map((call) => [call.path, call.body])).toEqual([
[APPROVAL, { decision: "allow" }],
[`/sessions/${SESSION}/approvals/call_2`, { decision: "deny" }],
]);
});
it.each([
{ args: '{"command":"ls","timeout_ms":5000}', parsed: { command: "ls", timeout_ms: 5000 } },
{ args: "", parsed: {} },
{ args: '{"command":"l', parsed: null },
{ args: '["ls"]', parsed: null },
{ args: '"ls"', parsed: null },
{ args: "null", parsed: null },
])("parseArguments reads $args as $parsed", ({ args, parsed }) => {
expect(
parseArguments({ tool_call_id: "call_1", name: "exec_command", arguments: args }),
).toEqual(parsed);
});
it("parseArguments reads the same object from a tool_call.done and from its fragments joined, although their text differs", () => {
// The fragments are the provider's text; the .done is the engine's serialization of the
// parsed call. Neither is rebuilt from the other, so a reader parses whichever it holds.
const streamed = ['{"command"', ': "echo hi"}'].join("");
const done = '{"command":"echo hi"}';
const call = (args: string) => ({
tool_call_id: "call_1",
name: "exec_command",
arguments: args,
});
expect(streamed).not.toBe(done);
expect(parseArguments(call(done))).toEqual({ command: "echo hi" });
expect(parseArguments(call(streamed))).toEqual(parseArguments(call(done)));
});
it.each(["coder", "demo/", "/coder", "demo/coder/extra"])(
"refuses the agent reference %j at construction",
(agent) => {
expect(() => new AgentClient({ baseUrl: BASE_URL, agent })).toThrow(TypeError);
},
);
it("sends every request through a fetch handed to it instead of the global one", async () => {
const own = createFetchFake();
own.stream("POST", RUNS, [...PLAIN.map(frame), DONE]);
client = new AgentClient({ baseUrl: BASE_URL, agent: "demo/coder", fetch: own.fetch });
await expect(client.ask({ input: "hi" })).resolves.toMatchObject({ text: "Hello!" });
expect(own.calls).toHaveLength(1);
expect(fake.calls).toEqual([]);
});
});