Claude Code. Any Model. The most powerful AI coding agent now speaks every language.
/**
* The response seam over synthetic Claude SSE streams (§5.3, §5.4, §11.3
* "Seam"): the closed modes `intercept` and `buffer`, block re-indexing,
* keepalive pings, the hold cap, upstream errors, client cancel, fail-open, the
* observe tap and its inbox `stop`/`end` lines, `responseEnd`, and the
* non-streaming JSON branch.
*/
import { afterEach, describe, expect, it } from "bun:test";
import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { HookEngine } from "./engine.js";
import { InboxFileSink, type InjectionSink, UnavailableSink } from "./injection/sinks.js";
import type { JournalEntry } from "./journal.js";
import { type HookDefinition, type ResponseView, type Severity, act } from "./public.js";
import { HookRegistry, type UserHookInput } from "./registry.js";
import { RequestHooks } from "./request-stage.js";
import { applyResponseSeam, planSeam, withHooks } from "./response-seam.js";
import type { SeamHooks } from "./seam-hooks.js";
import { PING_FRAME, closedTransform } from "./seam-transform.js";
const SESSION = "5b0c8f7e-2f7a-4d55-9d7e-2f2a1c7e9a10";
/* ───────────── fixtures ───────────── */
const frame = (event: string, data: object) => `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`;
const messageStart = () =>
frame("message_start", {
type: "message_start",
message: { id: "msg_1", type: "message", role: "assistant", content: [], model: "m" },
});
const start = (index: number, block: object) =>
frame("content_block_start", { type: "content_block_start", index, content_block: block });
const textDelta = (index: number, text: string) =>
frame("content_block_delta", {
type: "content_block_delta",
index,
delta: { type: "text_delta", text },
});
const jsonDelta = (index: number, partial_json: string) =>
frame("content_block_delta", {
type: "content_block_delta",
index,
delta: { type: "input_json_delta", partial_json },
});
const thinkingDelta = (index: number, thinking: string) =>
frame("content_block_delta", {
type: "content_block_delta",
index,
delta: { type: "thinking_delta", thinking },
});
const signatureDelta = (index: number, signature: string) =>
frame("content_block_delta", {
type: "content_block_delta",
index,
delta: { type: "signature_delta", signature },
});
const stop = (index: number) => frame("content_block_stop", { type: "content_block_stop", index });
const messageDelta = (stop_reason = "end_turn") =>
frame("message_delta", { type: "message_delta", delta: { stop_reason, stop_sequence: null } });
const messageStop = () => frame("message_stop", { type: "message_stop" });
const textBlock = (index: number, text: string) => [
start(index, { type: "text", text: "" }),
textDelta(index, text),
stop(index),
];
const toolBlock = (index: number, name: string, fragments: string[], id = `toolu_${index}`) => [
start(index, { type: "tool_use", id, name, input: {} }),
...fragments.map((f) => jsonDelta(index, f)),
stop(index),
];
const encoder = new TextEncoder();
/** A Claude SSE Response that yields `chunks` one per read, optionally waiting before some. */
function sse(
chunks: string[],
opts: { gates?: Map<number, Promise<void>>; onCancel?: () => void; errorAfter?: number } = {}
): Response {
let i = 0;
const body = new ReadableStream<Uint8Array>({
async pull(controller) {
if (opts.errorAfter !== undefined && i === opts.errorAfter) {
controller.error(new Error("upstream socket dropped"));
return;
}
if (i >= chunks.length) {
controller.close();
return;
}
await opts.gates?.get(i);
controller.enqueue(encoder.encode(chunks[i] as string));
i++;
},
cancel() {
opts.onCancel?.();
},
});
return new Response(body, { status: 200, headers: { "content-type": "text/event-stream" } });
}
let n = 0;
function userHook(def: Omit<HookDefinition, "apiVersion">): UserHookInput {
const full = { apiVersion: 1, ...def } as HookDefinition;
return { id: `hook:t/${def.id}`, module: "/t.ts", moduleIndex: 0, exportIndex: n++, def: full };
}
function engineWith(hooks: UserHookInput[], severity?: Record<string, Severity>) {
const journal: JournalEntry[] = [];
const engine = new HookEngine({
registry: new HookRegistry([], hooks, severity),
config: {},
hostMode: "pane-child",
journalSink: (e) => journal.push(e),
warn: () => {},
drainTelemetryOutbox: false,
});
return { engine, journal };
}
function fakeContext(): any {
const vars = new Map<string, unknown>();
return { get: (k: string) => vars.get(k), set: (k: string, v: unknown) => vars.set(k, v) };
}
async function scopeOf(engine: HookEngine, sink: InjectionSink = new UnavailableSink(() => {})) {
return new RequestHooks(engine, null, sink).beginAttempt(fakeContext(), {
claudeRequest: {
system: "base",
messages: [{ role: "user", content: "hi" }],
metadata: {
user_id: JSON.stringify({ device_id: "d", account_uuid: "", session_id: SESSION }),
},
},
route: { modelId: "glm-5", provider: "zai", native: false },
model: "glm-5",
stream: true,
});
}
async function readAll(res: Response): Promise<string> {
return await res.text();
}
/** Every `data:` payload, pings excluded. */
function payloads(wire: string): any[] {
return wire
.split("\n")
.filter((l) => l.startsWith("data: "))
.map((l) => JSON.parse(l.slice(6)))
.filter((p) => p.type !== "ping");
}
function indicesOf(wire: string, type: string): number[] {
return payloads(wire)
.filter((p) => p.type === type)
.map((p) => p.index);
}
function blockStarts(wire: string): Array<{ index: number; type: string }> {
return payloads(wire)
.filter((p) => p.type === "content_block_start")
.map((p) => ({ index: p.index, type: p.content_block.type }));
}
const tmpDirs: string[] = [];
function inboxPath(): string {
const dir = mkdtempSync(join(tmpdir(), "claudish-seam-"));
tmpDirs.push(dir);
return join(dir, "hook-inbox.jsonl");
}
function inboxLines(path: string): any[] {
if (!existsSync(path)) return [];
return readFileSync(path, "utf8")
.split("\n")
.filter(Boolean)
.map((l) => JSON.parse(l));
}
afterEach(() => {
for (const d of tmpDirs.splice(0)) rmSync(d, { recursive: true, force: true });
});
async function until(cond: () => boolean, ms = 2_000): Promise<void> {
const deadline = Date.now() + ms;
while (!cond()) {
if (Date.now() > deadline) throw new Error("condition not met in time");
await Bun.sleep(5);
}
}
const repairHook = (tool: string, args: Record<string, unknown>) =>
userHook({
id: `repair-${tool}`,
on: { toolCall: { tools: [tool], handle: () => [act.repairToolArgs(args, "test")] } },
});
const rewriteHook = (id: string, handle: (view: ResponseView) => unknown) =>
userHook({
id,
on: { responseRewrite: { handle: (ctx) => handle(ctx.response) as never } },
});
/* ───────────── plan and identity ───────────── */
describe("seam plan", () => {
it("is mode none with no tap when nothing claims the request, and returns the same object", async () => {
const { engine } = engineWith([]);
const scope = await scopeOf(engine);
expect(planSeam(scope)).toEqual({ mode: "none", raw: 0, tap: false });
const res = sse([messageStart()]);
expect(await applyResponseSeam(res, scope)).toBe(res);
});
it("picks the strictest closed mode: buffer over intercept over none", async () => {
const tool = repairHook("Write", {});
const rewrite = rewriteHook("rw", () => []);
expect(planSeam(await scopeOf(engineWith([tool]).engine)).mode).toBe("intercept");
expect(planSeam(await scopeOf(engineWith([tool, rewrite]).engine)).mode).toBe("buffer");
});
it("a warn-severity toolCall or rewrite hook never holds: it goes to the tap", async () => {
const tool = repairHook("Write", {});
const rewrite = rewriteHook("rw", () => []);
const { engine } = engineWith([tool, rewrite], { "hook:t/*": "warn" });
expect(planSeam(await scopeOf(engine))).toEqual({ mode: "none", raw: 0, tap: true });
});
it("an unarmed toolCall hook and a declining rewrite hook leave the identity case", async () => {
const tool = userHook({
id: "unarmed",
on: { toolCall: { tools: ["Write"], armed: () => false, handle: () => [] } },
});
const rewrite = userHook({
id: "declines",
on: { responseRewrite: { claims: () => false, handle: () => [] } },
});
const { engine } = engineWith([tool, rewrite]);
const scope = await scopeOf(engine);
expect(planSeam(scope)).toEqual({ mode: "none", raw: 0, tap: false });
});
});
/* ───────────── intercept ───────────── */
describe("intercept mode", () => {
it("repairs one named tool and leaves another tool and all text byte-identical", async () => {
const { engine, journal } = engineWith([repairHook("Write", { file_path: "/fixed" })]);
const scope = await scopeOf(engine);
const before = [
messageStart(),
PING_FRAME,
...textBlock(0, "héllo wörld"),
...toolBlock(1, "Read", ['{"file_path":', '"/a"}']),
...toolBlock(2, "Write", ['{"file_path":"/wr', 'ong"}']),
messageDelta("tool_use"),
messageStop(),
];
const out = await readAll(await applyResponseSeam(sse(before), scope));
const expected = [
...before.slice(0, 9),
start(2, { type: "tool_use", id: "toolu_2", name: "Write", input: {} }),
jsonDelta(2, '{"file_path":"/fixed"}'),
stop(2),
messageDelta("tool_use"),
messageStop(),
].join("");
expect(out).toBe(expected);
expect(
journal.some(
(e) => e.event === "toolCall" && e.decision === "repaired" && e.toolName === "Write"
)
).toBe(true);
});
it("the hold cap counts one tool block, not every block of the response", async () => {
const { engine, journal } = engineWith([repairHook("Write", { file_path: "/fixed" })]);
const args = ['{"file_path":"/wr', `ong","pad":"${"x".repeat(60)}"}`];
const blocks = [0, 1, 2, 3].flatMap((i) => toolBlock(i, "Write", args));
const perBlock = new TextEncoder().encode(toolBlock(0, "Write", args).slice(1).join("")).length;
const out = await readAll(
await applyResponseSeam(
sse([messageStart(), ...blocks, messageDelta("tool_use"), messageStop()]),
await scopeOf(engine),
// room for one block's held events, not for four
{ holdCapBytes: perBlock + 50 }
)
);
expect(out.split('{\\"file_path\\":\\"/fixed\\"}').length - 1).toBe(4);
expect(journal.some((e) => e.detail === "buffer_cap")).toBe(false);
});
it("a hook that changes nothing still finishes the block with one delta of the model's arguments", async () => {
const hook = userHook({ id: "noop", on: { toolCall: { tools: ["Write"], handle: () => [] } } });
const { engine, journal } = engineWith([hook]);
const out = await readAll(
await applyResponseSeam(
sse([...toolBlock(0, "Write", ['{"a":', "1}"]), messageStop()]),
await scopeOf(engine)
)
);
expect(payloads(out).filter((p) => p.type === "content_block_delta")).toEqual([
{
type: "content_block_delta",
index: 0,
delta: { type: "input_json_delta", partial_json: '{"a":1}' },
},
]);
expect(journal.some((e) => e.hookId === "hook:t/noop" && e.decision === "ignored")).toBe(true);
});
it("does not call the hook for malformed arguments, and forwards them unchanged", async () => {
let called = 0;
const hook = userHook({
id: "count",
on: {
toolCall: {
tools: ["Write"],
handle: () => {
called++;
return [];
},
},
},
});
const { engine } = engineWith([hook]);
const out = await readAll(
await applyResponseSeam(sse(toolBlock(0, "Write", ['{"a":'])), await scopeOf(engine))
);
expect(called).toBe(0);
expect(payloads(out)[1].delta.partial_json).toBe('{"a":');
});
it("a throwing hook fails open: the model's arguments go out", async () => {
const hook = userHook({
id: "boom",
on: {
toolCall: {
tools: ["Write"],
handle: () => {
throw new Error("boom");
},
},
},
});
const { engine, journal } = engineWith([hook]);
const out = await readAll(
await applyResponseSeam(sse(toolBlock(0, "Write", ['{"a":1}'])), await scopeOf(engine))
);
expect(payloads(out)[1].delta.partial_json).toBe('{"a":1}');
expect(journal.some((e) => e.hookId === "hook:t/boom" && e.decision === "error")).toBe(true);
});
it('"*" holds every tool', async () => {
const hook = userHook({
id: "all",
on: { toolCall: { tools: ["*"], handle: () => [act.repairToolArgs({ x: 1 }, "all")] } },
});
const { engine } = engineWith([hook]);
const out = await readAll(
await applyResponseSeam(sse(toolBlock(0, "Anything", ['{"y":2}'])), await scopeOf(engine))
);
expect(payloads(out)[1].delta.partial_json).toBe('{"x":1}');
});
it("forwards upstream pings while a hook is awaited", async () => {
let release!: () => void;
const gate = new Promise<void>((r) => {
release = r;
});
const hook = userHook({
id: "slow",
on: {
toolCall: {
tools: ["Write"],
handle: async () => {
await gate;
return [];
},
},
},
});
const { engine } = engineWith([hook]);
const res = await applyResponseSeam(
sse([...toolBlock(0, "Write", ['{"a":1}']), PING_FRAME, messageStop()]),
await scopeOf(engine),
{ pingIntervalMs: 10_000 }
);
const reader = res.body!.getReader();
const decoder = new TextDecoder();
let seen = "";
while (!seen.includes(PING_FRAME)) seen += decoder.decode((await reader.read()).value);
// The ping arrived while the Write block was still held.
expect(seen).not.toContain("content_block_stop");
release();
for (;;) {
const r = await reader.read();
if (r.done) break;
seen += decoder.decode(r.value);
}
expect(seen.indexOf(PING_FRAME)).toBeLessThan(seen.indexOf("content_block_stop"));
});
});
/* ───────────── buffer ───────────── */
describe("buffer mode", () => {
it("appendText on a tool-only response yields a text block BEFORE the tool_use", async () => {
const { engine } = engineWith([rewriteHook("add", () => [act.appendText("ADDED")])]);
const out = await readAll(
await applyResponseSeam(
sse([
messageStart(),
...toolBlock(0, "Read", ['{"a":1}']),
messageDelta("tool_use"),
messageStop(),
]),
await scopeOf(engine)
)
);
expect(blockStarts(out)).toEqual([
{ index: 0, type: "text" },
{ index: 1, type: "tool_use" },
]);
expect(payloads(out).find((p) => p.delta?.type === "text_delta")?.delta.text).toBe("ADDED");
});
it("re-index: appendText on [thinking, tool_use, tool_use] emits 0,1,2,3 with the text at 1", async () => {
const { engine } = engineWith([rewriteHook("add", () => [act.appendText("T")])]);
const out = await readAll(
await applyResponseSeam(
sse([
messageStart(),
start(0, { type: "thinking", thinking: "" }),
thinkingDelta(0, "hmm"),
signatureDelta(0, "SIG+/=="),
stop(0),
...toolBlock(1, "A", ['{"q":"\\"x\\""}']),
...toolBlock(2, "B", ["{}"]),
messageDelta("tool_use"),
messageStop(),
]),
await scopeOf(engine)
)
);
expect(blockStarts(out)).toEqual([
{ index: 0, type: "thinking" },
{ index: 1, type: "text" },
{ index: 2, type: "tool_use" },
{ index: 3, type: "tool_use" },
]);
expect(indicesOf(out, "content_block_stop")).toEqual([0, 1, 2, 3]);
// Every other field is carried unchanged.
const deltas = payloads(out).filter((p) => p.type === "content_block_delta");
expect(deltas.find((d) => d.delta.type === "signature_delta")?.delta.signature).toBe("SIG+/==");
expect(deltas.find((d) => d.index === 2)?.delta.partial_json).toBe('{"q":"\\"x\\""}');
});
it("re-index: removeText emptying block 0 of [text, tool_use] emits the tool at index 0", async () => {
const { engine } = engineWith([rewriteHook("rm", () => [act.removeText("DROP")])]);
const out = await readAll(
await applyResponseSeam(
sse([
messageStart(),
...textBlock(0, "DROP"),
...toolBlock(1, "A", ['{"k":"v"}']),
messageDelta(),
messageStop(),
]),
await scopeOf(engine)
)
);
expect(blockStarts(out)).toEqual([{ index: 0, type: "tool_use" }]);
expect(indicesOf(out, "content_block_delta")).toEqual([0]);
expect(indicesOf(out, "content_block_stop")).toEqual([0]);
expect(payloads(out).find((p) => p.type === "content_block_delta").delta.partial_json).toBe(
'{"k":"v"}'
);
});
it("replaceText and prependText rewrite the text, chunked into deltas of at most 1,024 units", async () => {
const long = "a".repeat(3000);
const { engine } = engineWith([
rewriteHook("rw", () => [act.prependText("P:"), act.replaceText("KEEP REMOVE-ME", "KEEP")]),
]);
const out = await readAll(
await applyResponseSeam(
sse([
messageStart(),
...textBlock(0, `KEEP REMOVE-ME KEEP${long}`),
messageDelta(),
messageStop(),
]),
await scopeOf(engine)
)
);
const texts = payloads(out)
.filter((p) => p.delta?.type === "text_delta")
.map((p) => p.delta.text);
expect(texts.join("")).toBe(`P:KEEP KEEP${long}`);
expect(Math.max(...texts.map((t) => t.length))).toBeLessThanOrEqual(1024);
});
it("a leading thinking block streams live, before the rewrite hook has run", async () => {
let release!: () => void;
const gate = new Promise<void>((r) => {
release = r;
});
const { engine } = engineWith([
rewriteHook("slow", async () => {
await gate;
return [act.appendText("!")];
}),
]);
const res = await applyResponseSeam(
sse([
messageStart(),
start(0, { type: "thinking", thinking: "" }),
thinkingDelta(0, "think"),
stop(0),
...textBlock(1, "answer"),
messageDelta(),
messageStop(),
]),
await scopeOf(engine)
);
const reader = res.body!.getReader();
const decoder = new TextDecoder();
let seen = "";
while (!seen.includes('"type":"content_block_stop","index":0')) {
seen += decoder.decode((await reader.read()).value);
}
expect(seen).not.toContain("answer");
release();
for (;;) {
const r = await reader.read();
if (r.done) break;
seen += decoder.decode(r.value);
}
expect(seen).toContain('"text":"answer!"');
});
it("forwards upstream pings during the hold, ahead of the held events", async () => {
const { engine } = engineWith([rewriteHook("rw", () => [act.appendText("!")])]);
const out = await readAll(
await applyResponseSeam(
sse([
messageStart(),
start(0, { type: "text", text: "" }),
PING_FRAME,
textDelta(0, "x"),
stop(0),
messageDelta(),
messageStop(),
]),
await scopeOf(engine)
)
);
expect(out.indexOf(PING_FRAME)).toBeLessThan(out.indexOf("content_block_start"));
});
it("emits its own ping each interval while awaiting responseRewrite after upstream close", async () => {
const { engine } = engineWith([
rewriteHook("slow", async () => {
await Bun.sleep(260);
return [];
}),
]);
const out = await readAll(
await applyResponseSeam(
sse([messageStart(), ...textBlock(0, "x"), messageDelta(), messageStop()]),
await scopeOf(engine),
{ pingIntervalMs: 50 }
)
);
const pings = out.split(PING_FRAME).length - 1;
expect(pings).toBeGreaterThanOrEqual(2);
expect(out.indexOf(PING_FRAME)).toBeLessThan(out.indexOf("content_block_start"));
});
it("repairs a held tool block's arguments before the rewrite hooks see the response", async () => {
let seen: ResponseView | undefined;
const { engine } = engineWith([
repairHook("Write", { file_path: "/fixed" }),
rewriteHook("look", (view) => {
seen = view;
return [];
}),
]);
const out = await readAll(
await applyResponseSeam(
sse([
messageStart(),
...toolBlock(0, "Write", ['{"file_path":"/x"}']),
messageDelta("tool_use"),
messageStop(),
]),
await scopeOf(engine)
)
);
expect(payloads(out).find((p) => p.type === "content_block_delta").delta.partial_json).toBe(
'{"file_path":"/fixed"}'
);
expect(seen?.blocks).toEqual([
{ type: "tool_use", id: "toolu_0", name: "Write", input: { file_path: "/fixed" } },
]);
expect(seen?.stopReason).toBe("tool_use");
});
it("past the hold cap it flushes everything unchanged and stops holding", async () => {
const { engine, journal } = engineWith([rewriteHook("rw", () => [act.appendText("!")])]);
const input = [messageStart(), ...textBlock(0, "x".repeat(500)), messageDelta(), messageStop()];
const out = await readAll(
await applyResponseSeam(sse(input), await scopeOf(engine), { holdCapBytes: 200 })
);
expect(out).toBe(input.join(""));
expect(journal.some((e) => e.decision === "invalid" && e.detail === "buffer_cap")).toBe(true);
});
it("an upstream error event while holding flushes the held events unchanged, then the error", async () => {
const { engine } = engineWith([rewriteHook("rw", () => [act.appendText("!")])]);
const error = frame("error", {
type: "error",
error: { type: "overloaded_error", message: "x" },
});
const input = [
messageStart(),
start(0, { type: "text", text: "" }),
textDelta(0, "partial"),
error,
];
const out = await readAll(await applyResponseSeam(sse(input), await scopeOf(engine)));
expect(out).toBe(input.join(""));
});
it("a stream that ends while holding forwards what it held", async () => {
const { engine } = engineWith([rewriteHook("rw", () => [act.appendText("!")])]);
const input = [messageStart(), start(0, { type: "text", text: "" }), textDelta(0, "partial")];
const out = await readAll(await applyResponseSeam(sse(input), await scopeOf(engine)));
expect(out).toBe(input.join(""));
});
it("a citations text block is never rewritten, and the skip is journaled", async () => {
const { engine, journal } = engineWith([
rewriteHook("rw", () => [act.replaceText("cite", "X")]),
]);
const input = [
messageStart(),
start(0, { type: "text", text: "" }),
textDelta(0, "cite me"),
frame("content_block_delta", {
type: "content_block_delta",
index: 0,
delta: { type: "citations_delta", citation: { cited_text: "c" } },
}),
stop(0),
messageDelta(),
messageStop(),
];
const out = await readAll(await applyResponseSeam(sse(input), await scopeOf(engine)));
expect(out).toBe(input.join(""));
expect(journal.some((e) => e.decision === "invalid" && e.detail === "citations")).toBe(true);
});
it("splits a multi-byte character across chunks without corrupting it", async () => {
const { engine } = engineWith([rewriteHook("rw", () => [act.appendText("!")])]);
const whole = [
messageStart(),
...textBlock(0, "snow ☃ man"),
messageDelta(),
messageStop(),
].join("");
const bytes = encoder.encode(whole);
const cut = bytes.indexOf(0xe2) + 1; // inside the 3-byte snowman
const body = new ReadableStream<Uint8Array>({
start(c) {
c.enqueue(bytes.slice(0, cut));
c.enqueue(bytes.slice(cut));
c.close();
},
});
const res = new Response(body, { headers: { "content-type": "text/event-stream" } });
const out = await readAll(await applyResponseSeam(res, await scopeOf(engine)));
expect(payloads(out).find((p) => p.delta?.type === "text_delta").delta.text).toBe(
"snow ☃ man!"
);
});
});
/* ───────────── fail open ───────────── */
describe("fail open", () => {
it("a throw inside the transform forwards what it held, and the rest, unchanged", async () => {
const throwing = {
intercepts: () => false,
rewrite: () => {
throw new Error("seam bug");
},
noteRewriteInvalid: () => {},
recordRewrite: () => {},
} as unknown as SeamHooks;
const input = [messageStart(), ...textBlock(0, "keep"), messageDelta(), messageStop()];
const out = await readAll(
new Response(closedTransform(sse(input).body!, { mode: "buffer", hooks: throwing }))
);
expect(out).toBe(input.join(""));
});
it("an upstream read error forwards what was held, then errors the stream", async () => {
const { engine } = engineWith([rewriteHook("rw", () => [])]);
const res = await applyResponseSeam(
sse([messageStart(), start(0, { type: "text", text: "" }), textDelta(0, "partial")], {
errorAfter: 3,
}),
await scopeOf(engine)
);
const reader = res.body!.getReader();
const decoder = new TextDecoder();
let seen = "";
let error: unknown;
try {
for (;;) {
const r = await reader.read();
if (r.done) break;
seen += decoder.decode(r.value);
}
} catch (err) {
error = err;
}
expect(String(error)).toContain("upstream socket dropped");
expect(seen).toContain('"text":"partial"');
});
});
/* ───────────── tap, inbox and responseEnd ───────────── */
describe("observe tap", () => {
const endHook = (onEnd: (view: ResponseView) => unknown = () => []) =>
userHook({ id: "end", on: { responseEnd: (ctx) => onEnd(ctx.response) as never } });
it("passes every chunk through unchanged and delivers chunk 1 before chunk 2 exists", async () => {
const { engine } = engineWith([endHook()]);
let release!: () => void;
const gate = new Promise<void>((r) => {
release = r;
});
const chunks = [messageStart(), ...textBlock(0, "x"), messageDelta(), messageStop()];
const res = await applyResponseSeam(
sse(chunks, { gates: new Map([[1, gate]]) }),
await scopeOf(engine)
);
const reader = res.body!.getReader();
const first = await Promise.race([
reader.read(),
Bun.sleep(500).then(() => "timeout" as const),
]);
expect(first).not.toBe("timeout");
expect(new TextDecoder().decode((first as ReadableStreamReadResult<Uint8Array>).value)).toBe(
chunks[0]
);
release();
const rest: string[] = [];
for (;;) {
const r = await reader.read();
if (r.done) break;
rest.push(new TextDecoder().decode(r.value));
}
// Same bytes, same chunking.
expect(rest).toEqual(chunks.slice(1));
});
for (const mode of ["none", "intercept", "buffer"] as const) {
it(`inbox stop is on disk when the client reads the message_stop chunk (mode ${mode})`, async () => {
const path = inboxPath();
const hooks = [endHook()];
if (mode === "intercept") hooks.push(repairHook("Write", { a: 1 }));
if (mode === "buffer") hooks.push(rewriteHook("rw", () => [act.appendText("!")]));
const { engine } = engineWith(hooks);
const scope = await scopeOf(engine);
expect(planSeam(scope).mode).toBe(mode);
const res = await applyResponseSeam(
sse([
messageStart(),
...textBlock(0, "x"),
...toolBlock(1, "Write", ["{}"]),
messageDelta(),
messageStop(),
]),
scope,
{ sink: new InboxFileSink(path), req: "r1" }
);
const reader = res.body!.getReader();
const decoder = new TextDecoder();
let atStop: any[] | null = null;
for (;;) {
const r = await reader.read();
if (r.done) break;
if (decoder.decode(r.value).includes('"type":"message_stop"')) {
atStop = inboxLines(path);
}
}
expect(atStop).toEqual([{ v: 1, kind: "stop", req: "r1" }]);
await until(() => inboxLines(path).length === 2);
expect(inboxLines(path)[1]).toEqual({ v: 1, kind: "end", req: "r1" });
});
}
it("responseEnd sees the bytes the client received (the rewrite included)", async () => {
let seen: ResponseView | undefined;
const { engine } = engineWith([
rewriteHook("rw", () => [act.appendText(" HOOK-ADDED")]),
endHook((view) => {
seen = view;
return [];
}),
]);
await readAll(
await applyResponseSeam(
sse([messageStart(), ...textBlock(0, "answer"), messageDelta(), messageStop()]),
await scopeOf(engine)
)
);
await until(() => seen !== undefined);
expect(seen?.text).toBe("answer HOOK-ADDED");
expect(seen?.stopReason).toBe("end_turn");
});
it("routes responseEnd actions: inject and annotate to the inbox, a system note to the next request", async () => {
const path = inboxPath();
const { engine, journal } = engineWith([
endHook(() => [
act.injectUserTurn("HOOK-PING"),
act.annotateTurn("k", { n: 1 }),
act.injectSystemNote("NEXT"),
]),
]);
await readAll(
await applyResponseSeam(
sse([messageStart(), ...textBlock(0, "x"), messageDelta(), messageStop()]),
await scopeOf(engine),
{ sink: new InboxFileSink(path, undefined, () => new Date(0)), req: "r9" }
)
);
await until(() => inboxLines(path).some((l) => l.kind === "end"));
expect(inboxLines(path)).toEqual([
{ v: 1, kind: "stop", req: "r9" },
{
v: 1,
kind: "inject",
req: "r9",
hookId: "hook:t/end",
text: "HOOK-PING",
at: "1970-01-01T00:00:00.000Z",
},
{
v: 1,
kind: "annotate",
req: "r9",
hookId: "hook:t/end",
key: "k",
value: { n: 1 },
at: "1970-01-01T00:00:00.000Z",
},
{ v: 1, kind: "end", req: "r9" },
]);
expect(engine.peekNotes(SESSION).map((n) => n.text)).toEqual(["NEXT"]);
expect(
journal.filter((e) => e.event === "responseEnd" && e.decision === "queued")
).toHaveLength(3);
});
it("with no session driver an injection is dropped `unavailable`, with one stderr line per process", async () => {
const lines: string[] = [];
const { engine, journal } = engineWith([endHook(() => [act.injectUserTurn("X")])]);
const { resetUnavailableSinkReportForTests } = await import("./injection/sinks.js");
resetUnavailableSinkReportForTests();
for (let i = 0; i < 2; i++) {
await readAll(
await applyResponseSeam(
sse([messageStart(), ...textBlock(0, "x"), messageDelta(), messageStop()]),
await scopeOf(engine),
{ sink: new UnavailableSink((l) => lines.push(l)) }
)
);
}
await until(() => journal.filter((e) => e.decision === "dropped").length === 2);
expect(journal.filter((e) => e.detail === "unavailable")).toHaveLength(2);
expect(lines).toHaveLength(1);
});
it("a warn-severity responseEnd hook writes nothing but stop/end, and journals warned", async () => {
const path = inboxPath();
const { engine, journal } = engineWith([endHook(() => [act.injectUserTurn("X")])], {
"hook:t/end": "warn",
});
await readAll(
await applyResponseSeam(
sse([messageStart(), ...textBlock(0, "x"), messageDelta(), messageStop()]),
await scopeOf(engine),
{ sink: new InboxFileSink(path), req: "w" }
)
);
await until(() => inboxLines(path).some((l) => l.kind === "end"));
expect(inboxLines(path).map((l) => l.kind)).toEqual(["stop", "end"]);
expect(journal.some((e) => e.event === "responseEnd" && e.decision === "warned")).toBe(true);
});
it("a client cancel writes end with aborted at once, and cancels the upstream", async () => {
const path = inboxPath();
let cancelled = false;
const { engine } = engineWith([endHook()]);
const res = await applyResponseSeam(
sse([messageStart(), ...textBlock(0, "x"), messageDelta(), messageStop()], {
gates: new Map([[2, new Promise<void>(() => {})]]),
onCancel: () => {
cancelled = true;
},
}),
await scopeOf(engine),
{ sink: new InboxFileSink(path), req: "c" }
);
const reader = res.body!.getReader();
await reader.read();
await reader.cancel("client went away");
expect(inboxLines(path)).toEqual([{ v: 1, kind: "end", req: "c", aborted: true }]);
expect(cancelled).toBe(true);
});
it("a slow warn-mode rewrite never delays responseEnd or its end line", async () => {
const path = inboxPath();
const slowRewrite = userHook({
id: "slowrw",
timeoutMs: 5_000,
on: {
responseRewrite: {
handle: () => Bun.sleep(1_500).then(() => [act.appendText("!")]) as never,
},
},
});
const { engine } = engineWith([slowRewrite, endHook(() => [act.injectUserTurn("ON-TIME")])], {
"hook:t/slowrw": "warn",
});
await readAll(
await applyResponseSeam(
sse([messageStart(), ...textBlock(0, "x"), messageDelta(), messageStop()]),
await scopeOf(engine),
{ sink: new InboxFileSink(path), req: "r4" }
)
);
const readAt = Date.now();
await until(() => inboxLines(path).some((l) => l.kind === "end"), 5_000);
// responseEnd's own time only: the 1.5 s warn rewrite is not in front of it
expect(Date.now() - readAt).toBeLessThan(700);
expect(inboxLines(path).map((l) => l.kind)).toEqual(["stop", "inject", "end"]);
});
it("a client cancel after message_stop leaves end to responseEnd, after its payload", async () => {
const path = inboxPath();
const { engine } = engineWith([
endHook(() => Bun.sleep(200).then(() => [act.injectUserTurn("LATE-BUT-KEPT")])),
]);
const res = await applyResponseSeam(
sse([messageStart(), ...textBlock(0, "x"), messageDelta(), messageStop()], {
gates: new Map([[6, new Promise<void>(() => {})]]),
}),
await scopeOf(engine),
{ sink: new InboxFileSink(path), req: "c8" }
);
const reader = res.body!.getReader();
const decoder = new TextDecoder();
for (;;) {
const r = await reader.read();
if (r.done || decoder.decode(r.value).includes('"type":"message_stop"')) break;
}
await reader.cancel("client closed after message_stop");
await until(() => inboxLines(path).some((l) => l.kind === "end"), 3_000);
await Bun.sleep(300);
expect(inboxLines(path)).toEqual([
{ v: 1, kind: "stop", req: "c8" },
expect.objectContaining({ kind: "inject", req: "c8", text: "LATE-BUT-KEPT" }),
{ v: 1, kind: "end", req: "c8" },
]);
});
it("an upstream read error after message_stop leaves end to responseEnd, after its payload", async () => {
const path = inboxPath();
const { engine } = engineWith([
endHook(() => Bun.sleep(200).then(() => [act.injectUserTurn("LATE-BUT-KEPT")])),
]);
const chunks = [messageStart(), ...textBlock(0, "x"), messageDelta(), messageStop()];
const res = await applyResponseSeam(
sse(chunks, { errorAfter: chunks.length }),
await scopeOf(engine),
{ sink: new InboxFileSink(path), req: "e8" }
);
await expect(readAll(res)).rejects.toThrow("upstream socket dropped");
await until(() => inboxLines(path).some((l) => l.kind === "end"), 3_000);
await Bun.sleep(300);
expect(inboxLines(path)).toEqual([
{ v: 1, kind: "stop", req: "e8" },
expect.objectContaining({ kind: "inject", req: "e8", text: "LATE-BUT-KEPT" }),
{ v: 1, kind: "end", req: "e8" },
]);
});
it("a response that ends before message_stop writes only its end", async () => {
const path = inboxPath();
const { engine } = engineWith([endHook()]);
await readAll(
await applyResponseSeam(sse([messageStart(), ...textBlock(0, "x")]), await scopeOf(engine), {
sink: new InboxFileSink(path),
req: "t",
})
);
expect(inboxLines(path)).toEqual([{ v: 1, kind: "end", req: "t", aborted: true }]);
});
it("observe-mode and warn-severity toolCall hooks see the delivered call and hold nothing", async () => {
const seen: string[] = [];
const observe = userHook({
id: "obs",
on: {
toolCall: {
tools: ["Write"],
observe: true,
handle: (ctx) => {
seen.push(`obs:${JSON.stringify(ctx.tool.args)}`);
return [act.warn("seen")];
},
},
},
});
const warnRepair = userHook({
id: "warned",
on: {
toolCall: {
tools: ["Write"],
handle: (ctx) => {
seen.push(`warn:${ctx.tool.rawArgs}`);
return [act.repairToolArgs({ changed: true }, "would repair")];
},
},
},
});
const { engine, journal } = engineWith([observe, warnRepair], { "hook:t/warned": "warn" });
const scope = await scopeOf(engine);
expect(planSeam(scope)).toEqual({ mode: "none", raw: 0, tap: true });
const input = [
messageStart(),
...toolBlock(0, "Write", ['{"a":', "1}"]),
messageDelta(),
messageStop(),
];
const out = await readAll(await applyResponseSeam(sse(input), scope));
expect(out).toBe(input.join(""));
await until(() => seen.length === 2);
expect(seen.sort()).toEqual(['obs:{"a":1}', 'warn:{"a":1}']);
await until(() => journal.some((e) => e.hookId === "hook:t/warned" && e.decision === "warned"));
});
});
/* ───────────── JSON branch ───────────── */
describe("non-streaming JSON branch", () => {
const jsonResponse = (message: object) =>
new Response(JSON.stringify(message), {
status: 200,
headers: { "content-type": "application/json", "x-upstream": "kept" },
});
it("repairs tool_use.input, rewrites text, keeps status and headers, and writes stop before returning", async () => {
const path = inboxPath();
let seen: ResponseView | undefined;
const { engine } = engineWith([
repairHook("Write", { file_path: "/fixed" }),
rewriteHook("rm", () => [act.removeText("\\s*REMOVE-ME", { regex: true })]),
userHook({
id: "end",
on: {
responseEnd: (ctx) => {
seen = ctx.response;
},
},
}),
]);
const res = await applyResponseSeam(
jsonResponse({
id: "msg_1",
type: "message",
role: "assistant",
content: [
{ type: "text", text: "KEEP REMOVE-ME KEEP" },
{ type: "tool_use", id: "t1", name: "Write", input: { file_path: "/wrong" } },
],
stop_reason: "tool_use",
}),
await scopeOf(engine),
{ sink: new InboxFileSink(path), req: "j" }
);
expect(inboxLines(path)).toEqual([{ v: 1, kind: "stop", req: "j" }]);
expect(res.status).toBe(200);
expect(res.headers.get("x-upstream")).toBe("kept");
const body = await res.json();
expect(body.content).toEqual([
{ type: "text", text: "KEEP KEEP" },
{ type: "tool_use", id: "t1", name: "Write", input: { file_path: "/fixed" } },
]);
await until(() => inboxLines(path).length === 2);
expect(seen?.text).toBe("KEEP KEEP");
});
it("inserts a text block before the first tool_use when the message has no text", async () => {
const { engine } = engineWith([rewriteHook("add", () => [act.appendText("A")])]);
const res = await applyResponseSeam(
jsonResponse({
content: [
{ type: "thinking", thinking: "t", signature: "s" },
{ type: "tool_use", id: "t1", name: "R", input: {} },
],
}),
await scopeOf(engine)
);
expect((await res.json()).content.map((b: any) => b.type)).toEqual([
"thinking",
"text",
"tool_use",
]);
});
it("a body that errors on read fails open: the seam returns, the error reaches the reader", async () => {
const { engine } = engineWith([rewriteHook("rw", () => [act.appendText("!")])]);
let sent = false;
const broken = new Response(
new ReadableStream<Uint8Array>({
pull(c) {
if (!sent) {
sent = true;
c.enqueue(encoder.encode('{"type":"message","content":['));
} else c.error(new Error("upstream body dropped"));
},
}),
{ status: 200, headers: { "content-type": "application/json" } }
);
const out = await applyResponseSeam(broken, await scopeOf(engine));
expect(out.status).toBe(200);
await expect(out.text()).rejects.toThrow("upstream body dropped");
});
it("passes a body that is not a message through unchanged", async () => {
const { engine } = engineWith([rewriteHook("add", () => [act.appendText("A")])]);
const res = await applyResponseSeam(
new Response("not json", { headers: { "content-type": "application/json" } }),
await scopeOf(engine)
);
expect(await res.text()).toBe("not json");
});
});
/* ───────────── through withHooks ───────────── */
describe("withHooks applies the seam", () => {
it("an accepted response with a claiming hook is rewritten; a non-2xx one is not", async () => {
const { engine } = engineWith([rewriteHook("add", () => [act.appendText("!")])]);
const terminal = (status: number) => ({
async handle(c: any, body: any) {
const hooks = (await import("./request-stage.js")).requestHooksOf(c);
await hooks?.beginAttempt(c, {
claudeRequest: structuredClone(body),
route: { modelId: "m", provider: "p", native: false },
model: "m",
stream: true,
});
return status === 200
? sse([messageStart(), ...textBlock(0, "hi"), messageDelta(), messageStop()])
: new Response("{}", { status });
},
shutdown: async () => {},
});
const ok = await withHooks(terminal(200), engine).handle(fakeContext(), {
messages: [{ role: "user", content: "x" }],
});
expect(await ok.text()).toContain('"text":"hi!"');
const failed = await withHooks(terminal(500), engine).handle(fakeContext(), {
messages: [{ role: "user", content: "x" }],
});
expect(await failed.text()).toBe("{}");
});
});