repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by admin

fix(klaus): make continuations quota-safe

7bb9e63ec6dff13f774547b4cfd82104c4f56a2b

Oliver Jan Krylow <oliver@bugabinga.net> ·

SSH signature · not checked

Browse filesCompare with HEAD

Changed files (9)

extensions/klaus/__e2e__/provider-scenarios.test.ts

Modified
8 8 type TestSession,
9 9 } from "@marcfargas/pi-test-harness";
10 10 import { Type } from "typebox";
11 -import { afterEach, describe, expect, it } from "vitest";
11 +import { afterEach, describe, expect, it, vi } from "vitest";
12 12 import klaus from "../index";
13 13 import { type KlausQueryHandle, startSdkQuery } from "../src/agent-sdk";
14 14 import type {
649 649 const { t, model } = await providerSession();
650 650 const sessionId = "pi-parallel-tools";
651 + const onPayload = vi.fn((payload: unknown) => payload);
651 652 const user = { role: "user" as const, content: "parallel", timestamp: 1 };
652 653 const tools = [
659 660 const first = await t.session.modelRuntime.completeSimple(
660 661 model,
661 662 { messages: [user], tools },
662 - { sessionId, timeoutMs: 5000 },
664 + sessionId,
665 + timeoutMs: 5000,
666 + onPayload,
667 + headers: { "x-first": "one", "x-second": "two" },
668 + },
664 670 expect(first.stopReason).toBe("toolUse");
671 + expect(first.usage).toMatchObject({ input: 11, output: 8 });
665 672 const calls = first.content.filter((item) => item.type === "toolCall");
666 673 expect(calls).toHaveLength(2);
667 674 const [firstCall, secondCall] = calls;
696 703 tools,
698 - { sessionId, timeoutMs: 5000 },
706 + sessionId,
707 + timeoutMs: 5000,
708 + onPayload,
709 + headers: { "x-second": "two", "x-first": "one" },
710 + },
701 713 expect(second).toMatchObject({
702 714 stopReason: "stop",
703 715 content: [{ type: "text", text: "Pi batch continued" }],
716 + usage: { input: 11, output: 3 },
718 + expect(onPayload).toHaveBeenCalledTimes(1);
705 719 const followup = JSON.stringify(server.messageRequests()[1]?.body);
706 720 expect(followup).toContain("one result");
707 721 expect(followup).toContain("two result");
708 722 expect(followup).not.toContain("must-not-pass");
723 + expect(followup).toContain('"tool_use_id":"toolu_pi_one"');
724 + expect(followup).not.toContain('\\"role\\":\\"toolResult\\"');
725 + }, 60_000);
727 + it("replays canonically when history changes across a parked tool boundary", async () => {
728 + const server = await useServer((_request, index, response) => {
729 + if (index === 1) {
730 + sse(response, [
731 + messageStart(index),
733 + type: "content_block_start",
734 + index: 0,
735 + content_block: {
736 + type: "tool_use",
737 + id: "toolu_edit",
738 + name: "mcp__klaus__echo",
739 + input: {},
740 + },
741 + },
743 + type: "content_block_delta",
744 + index: 0,
745 + delta: {
746 + type: "input_json_delta",
747 + partial_json: '{"value":"before"}',
748 + },
749 + },
750 + { type: "content_block_stop", index: 0 },
752 + type: "message_delta",
753 + delta: { stop_reason: "tool_use", stop_sequence: null },
754 + usage: { output_tokens: 4 },
755 + },
756 + { type: "message_stop" },
757 + ]);
758 + return;
760 + sse(response, textFrames(index, "edited history used"));
761 + });
762 + const { t, model } = await providerSession();
763 + const sessionId = "edited-tool-history";
764 + const tools = [
766 + name: "echo",
767 + description: "Echo.",
768 + parameters: Type.Object({ value: Type.String() }),
769 + },
770 + ];
771 + const original = {
772 + role: "user" as const,
773 + content: "original",
774 + timestamp: 1,
775 + };
776 + const first = await t.session.modelRuntime.completeSimple(
777 + model,
778 + { messages: [original], tools },
779 + { sessionId, timeoutMs: 5000 },
780 + );
781 + const call = first.content.find((item) => item.type === "toolCall");
782 + if (call?.type !== "toolCall") {
783 + throw new Error("Missing Klaus call.");
786 + const second = await t.session.modelRuntime.completeSimple(
787 + model,
789 + messages: [
790 + { ...original, content: "edited" },
791 + first,
793 + role: "toolResult",
794 + toolCallId: call.id,
795 + toolName: call.name,
796 + content: [{ type: "text", text: "tool result" }],
797 + isError: false,
798 + timestamp: 2,
799 + },
800 + ],
801 + tools,
802 + },
803 + { sessionId, timeoutMs: 5000 },
804 + );
806 + expect(second.content).toEqual([
807 + { type: "text", text: "edited history used" },
808 + ]);
809 + const replay = JSON.stringify(server.messageRequests().at(-1)?.body);
810 + expect(server.messageRequests()).toHaveLength(3);
811 + expect(replay).toContain("edited");
812 + expect(replay).toContain('\\"role\\":\\"toolResult\\"');
813 + expect(replay).not.toContain('"tool_use_id":"toolu_edit"');
709 814 }, 60_000);
711 816 it("fails unsupported image media before any Anthropic message request", async () => {
774 879 }, 60_000);
776 - it("maps max-token completion, all usage classes, and API-equivalent cost through Pi", async () => {
777 - await useServer((_request, index, response) =>
881 + it("caps max-token recovery and replays the next turn canonically", async () => {
882 + const server = await useServer((_request, index, response) =>
779 884 response,
780 - textFrames(index, "truncated", {
781 - stopReason: "max_tokens",
782 - input: 13,
783 - output: 17,
784 - cacheRead: 19,
785 - cacheWrite: 23,
786 - }),
885 + index === 1
886 + ? textFrames(index, "truncated", {
887 + stopReason: "max_tokens",
888 + input: 13,
889 + output: 17,
890 + cacheRead: 19,
891 + cacheWrite: 23,
892 + })
893 + : textFrames(index, "resumed after truncation"),
789 896 const { t, model } = await providerSession();
804 911 totalTokens: 72,
806 913 expect(result.usage.cost.total).toBeGreaterThan(0);
914 + expect(server.messageRequests()).toHaveLength(2);
916 + const resumed = await t.session.modelRuntime.completeSimple(
917 + model,
919 + messages: [
920 + { role: "user", content: "usage", timestamp: 1 },
921 + result,
922 + { role: "user", content: "continue", timestamp: 2 },
923 + ],
924 + },
925 + { sessionId: "usage-scenario" },
926 + );
927 + expect(resumed).toMatchObject({
928 + stopReason: "stop",
929 + content: [{ type: "text", text: "resumed after truncation" }],
930 + });
931 + expect(server.messageRequests()).toHaveLength(3);
932 + expect(JSON.stringify(server.messageRequests()[2]?.body)).toContain(
933 + "<klaus-history-json>",
934 + );
807 935 }, 60_000);
809 937 it("prices recognized fallbacks and ignores unknown returned models", async () => {
980 1108 ).toBe(false);
981 1109 }, 60_000);
1111 + it("reapplies payload redaction when a transformed resume becomes a cold replay", async () => {
1112 + const sentinel = "payload-redaction-sentinel";
1113 + const server = await useServer((_request, index, response) =>
1114 + sse(response, textFrames(index, `response-${index}`)),
1115 + );
1116 + const { t, model } = await providerSession();
1117 + const payloads: KlausRequest[] = [];
1118 + const onPayload = (payload: unknown) => {
1119 + const request = structuredClone(payload as KlausRequest);
1120 + payloads.push(request);
1121 + if (payloads.length === 1) return request;
1122 + return {
1123 + ...request,
1124 + systemPrompt: "redacted system",
1125 + prompt: request.prompt.replaceAll(sentinel, "[redacted]"),
1126 + };
1127 + };
1128 + const firstUser = {
1129 + role: "user" as const,
1130 + content: "first turn",
1131 + timestamp: 1,
1132 + };
1133 + const first = await t.session.modelRuntime.completeSimple(
1134 + model,
1135 + { systemPrompt: "original system", messages: [firstUser] },
1136 + { sessionId: "resume-redaction", onPayload },
1137 + );
1138 + const second = await t.session.modelRuntime.completeSimple(
1139 + model,
1141 + systemPrompt: "original system",
1142 + messages: [
1143 + firstUser,
1144 + first,
1145 + { role: "user", content: sentinel, timestamp: 2 },
1146 + ],
1147 + },
1148 + { sessionId: "resume-redaction", onPayload },
1149 + );
1151 + expect(second.content).toEqual([{ type: "text", text: "response-2" }]);
1152 + expect(payloads).toHaveLength(3);
1153 + expect(payloads[1]?.prompt).toBe(sentinel);
1154 + expect(payloads[2]?.prompt).toContain("<klaus-history-json>");
1155 + const outbound = JSON.stringify(server.messageRequests()[1]?.body);
1156 + expect(outbound).toContain("redacted system");
1157 + expect(outbound).toContain("[redacted]");
1158 + expect(outbound).not.toContain(sentinel);
1159 + expect(server.messageRequests()).toHaveLength(2);
1160 + }, 60_000);
983 1162 it("normalizes a fake provider context overflow for Pi compaction detection", async () => {
984 1163 await useServer((_request, _index, response) => {
985 1164 response.writeHead(400, { "content-type": "application/json" });

extensions/klaus/__tests__/cache.test.ts

Modified
12 12 import { afterEach, describe, expect, it } from "vitest";
13 13 import {
14 14 FileSessionStore,
15 + KlausCacheCorruptionError,
15 16 loadCheckpoint,
16 17 loadCheckpoints,
17 18 MemorySessionStore,
303 304 const root = join(await temporaryRoot("corrupt-transcript"), "sessions");
304 305 const store = new FileSessionStore(root);
305 306 await store.append(key, [{ type: "valid" }]);
306 - await writeFile(await onlyFile(root, ".ndjson"), text);
307 - await expect(store.load(key)).rejects.toThrow();
307 + const transcript = await onlyFile(root, ".ndjson");
308 + await writeFile(transcript, text);
309 + await expect(store.load(key)).rejects.toBeInstanceOf(
310 + KlausCacheCorruptionError,
311 + );
312 + expect(await readFile(transcript, "utf8")).toBe(text);

extensions/klaus/__tests__/coordinator.test.ts

Added
new file mode 100644
1 +import { describe, expect, it } from "vitest";
2 +import { KlausCacheCorruptionError } from "../src/cache";
3 +import { isReplayableResumeError } from "../src/coordinator";
5 +describe("Klaus resume recovery", () => {
6 + it("replays only when the SDK explicitly rejects the resume point", () => {
7 + expect(
8 + isReplayableResumeError(
9 + new Error(
10 + "Resume rejected by --resume-drops-turn: fork point is not attributable to the discarded turn",
11 + ),
12 + ),
13 + ).toBe(true);
14 + expect(
15 + isReplayableResumeError(
16 + new KlausCacheCorruptionError("invalid transcript JSON."),
17 + ),
18 + ).toBe(true);
19 + expect(
20 + isReplayableResumeError(
21 + new Error("Klaus cache corruption: invalid transcript JSON."),
22 + ),
23 + ).toBe(true);
24 + });
26 + it.each([
27 + "rate limit: Claude subscription limit rejected the request.",
28 + "authentication failed",
29 + "network connection reset",
30 + "Klaus session mirror failed: write failed",
31 + ])("does not replay a full context after %s", (message) => {
32 + expect(isReplayableResumeError(new Error(message))).toBe(false);
33 + });
34 +});

extensions/klaus/__tests__/runtime.test.ts

Modified
1 -import { access, stat } from "node:fs/promises";
1 +import {
2 + access,
3 + mkdtemp,
4 + readFile,
5 + rm,
6 + stat,
7 + writeFile,
8 +} from "node:fs/promises";
9 +import { tmpdir } from "node:os";
10 +import { dirname, join } from "node:path";
2 11 import { afterEach, describe, expect, it } from "vitest";
3 12 import { type ChildRuntime, createChildRuntime } from "../src/runtime/index";
5 14 const runtimes: ChildRuntime[] = [];
15 +const roots: string[] = [];
6 16 const originalEnvironment = { ...process.env };
8 18 afterEach(async () => {
9 19 await Promise.all(runtimes.splice(0).map((runtime) => runtime.cleanup()));
20 + await Promise.all(
21 + roots.splice(0).map((root) => rm(root, { recursive: true, force: true })),
22 + );
10 23 for (const key of Object.keys(process.env)) {
11 24 if (!(key in originalEnvironment)) delete process.env[key];
76 89 }, 60_000);
91 + it("does not depend on a shared predictable klaus directory", async () => {
92 + const root = await mkdtemp(join(tmpdir(), "klaus-runtime-test-"));
93 + roots.push(root);
94 + await writeFile(join(root, "klaus"), "foreign obstacle");
95 + process.env.TMPDIR = root;
96 + process.env.TMP = root;
97 + process.env.TEMP = root;
99 + const runtime = await createChildRuntime("token", {}, {});
100 + runtimes.push(runtime);
102 + expect(dirname(runtime.configDir)).toBe(root);
103 + expect(await readFile(join(root, "klaus"), "utf8")).toBe(
104 + "foreign obstacle",
105 + );
106 + }, 60_000);
78 108 it("creates unique config directories and removes only its own directory", async () => {
79 109 const first = await createChildRuntime("token-one", {}, {});
80 110 const second = await createChildRuntime("token-two", {}, {});

extensions/klaus/src/agent-sdk.ts

Modified
24 24 latestPosition?: string;
25 25 responseId?: string;
26 26 responseModel?: string;
27 + sdkSessionId?: string;
28 + deferredOutputLimit?: Parameters<KlausQueryCallbacks["onResult"]>[0];
27 29 usage: {
28 30 input: number;
29 31 output: number;
30 32 cacheRead: number;
31 33 cacheWrite: number;
35 + reportedUsage: {
36 + input: number;
37 + output: number;
38 + cacheRead: number;
39 + cacheWrite: number;
40 + };
35 43 export interface KlausQueryHandle {
86 +interface ProviderUsage {
87 + input_tokens: number;
88 + output_tokens: number;
89 + cache_read_input_tokens?: number;
90 + cache_creation_input_tokens?: number;
93 +function remainingUsage(
94 + usage: ProviderUsage,
95 + reported: MessageState["reportedUsage"],
96 +): MessageState["usage"] {
97 + return {
98 + input: Math.max(0, usage.input_tokens - reported.input),
99 + output: Math.max(0, usage.output_tokens - reported.output),
100 + cacheRead: Math.max(
101 + 0,
102 + (usage.cache_read_input_tokens ?? 0) - reported.cacheRead,
103 + ),
104 + cacheWrite: Math.max(
105 + 0,
106 + (usage.cache_creation_input_tokens ?? 0) - reported.cacheWrite,
107 + ),
108 + };
111 +function addUsage(
112 + target: MessageState["reportedUsage"],
113 + usage: MessageState["usage"],
114 +): void {
115 + target.input += usage.input;
116 + target.output += usage.output;
117 + target.cacheRead += usage.cacheRead;
118 + target.cacheWrite += usage.cacheWrite;
78 121 function originalToolName(name: string): string {
79 122 return name.startsWith("mcp__klaus__")
80 123 ? name.slice("mcp__klaus__".length)
169 212 let stderr = "";
170 213 const messageState: MessageState = {
171 214 usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
215 + reportedUsage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
174 218 const cleanup = (reason: string): Promise<void> => {
302 346 messageState.latestPosition = message.uuid;
304 - await handleMessage(message, blocks, callbacks, messageState);
348 + const terminal = await handleMessage(
349 + message,
350 + blocks,
351 + callbacks,
352 + messageState,
353 + () => {
354 + if (closed) return;
355 + closed = true;
356 + abortController.abort("Klaus stopped max-token recovery.");
357 + queryHandle?.close();
358 + },
359 + );
360 + if (terminal) {
361 + closed = true;
362 + abortController.abort("Klaus stopped max-token recovery.");
363 + queryHandle?.close();
364 + break;
306 367 } catch (error) {
307 368 if (!closed) {
316 377 dbg?.("sdk.pump.finally", { closed });
317 378 if (!closed) closed = true;
318 379 await cleanup("Klaus query finished.");
380 + if (messageState.deferredOutputLimit) {
381 + callbacks.onResult(messageState.deferredOutputLimit);
321 385 pumpPromise = pump();
328 392 blocks: Map<number, BlockState>,
329 393 callbacks: KlausQueryCallbacks,
330 394 state: MessageState,
331 -): Promise<void> {
395 + stopMaxRecovery: () => void,
396 +): Promise<boolean> {
332 397 dbg?.("sdk.handleMessage", {
333 398 type: message.type,
334 399 subtype: "subtype" in message ? message.subtype : undefined,
337 402 if (message.type === "system" && message.subtype === "init") {
338 403 dbg?.("sdk.message.init", { sessionId: message.session_id });
404 + state.sdkSessionId = message.session_id;
339 405 await callbacks.onReady({
340 406 "x-klaus-transport": "claude-agent-sdk",
341 407 "x-klaus-sdk-version": SDK_VERSION,
342 408 "x-klaus-claude-version": CLAUDE_VERSION,
343 409 "x-klaus-session-id": message.session_id,
345 - return;
411 + return false;
347 413 if (message.type === "assistant") {
348 414 dbg?.("sdk.message.assistant", {
349 415 uuid: message.uuid,
350 416 blockCount: message.message.content.length,
417 + error: message.error,
352 - return;
419 + return false;
354 421 if (message.type === "system" && message.subtype === "mirror_error") {
355 422 dbg?.("sdk.message.mirror_error", { error: message.error });
356 423 callbacks.onError(
357 424 new Error(`Klaus session mirror failed: ${message.error}`),
359 - return;
426 + return false;
362 429 message.type === "rate_limit_event" &&
368 435 callbacks.onError(
369 436 new Error("rate limit: Claude subscription limit rejected the request."),
371 - return;
438 + return false;
373 440 if (message.type === "result") {
374 441 dbg?.("sdk.message.result", {
384 451 dbg?.("sdk.message.resultError", { detail });
385 452 if (isOutputLimit(detail)) {
386 453 callbacks.onResult({
387 - usage: {
388 - input: message.usage.input_tokens,
389 - output: message.usage.output_tokens,
390 - cacheRead: message.usage.cache_read_input_tokens ?? 0,
391 - cacheWrite: message.usage.cache_creation_input_tokens ?? 0,
392 - },
454 + usage: remainingUsage(message.usage, state.reportedUsage),
393 455 responseId: message.uuid,
394 456 responseModel: state.responseModel,
395 457 position: state.latestPosition ?? message.uuid,
396 458 sdkSessionId: message.session_id,
397 459 stopReason: "length",
399 - return;
461 + return false;
401 463 callbacks.onError(
402 464 new Error(
408 - return;
470 + return false;
410 472 callbacks.onResult({
411 - usage: {
412 - input: message.usage.input_tokens,
413 - output: message.usage.output_tokens,
414 - cacheRead: message.usage.cache_read_input_tokens ?? 0,
415 - cacheWrite: message.usage.cache_creation_input_tokens ?? 0,
416 - },
473 + usage: remainingUsage(message.usage, state.reportedUsage),
417 474 responseId: message.uuid,
418 475 responseModel: state.responseModel,
419 476 position: state.latestPosition ?? message.uuid,
420 477 sdkSessionId: message.session_id,
421 478 stopReason: message.stop_reason === "max_tokens" ? "length" : "stop",
423 - return;
480 + return false;
425 - if (message.type !== "stream_event") return;
482 + if (message.type !== "stream_event") return false;
426 483 const event = message.event;
427 484 dbg?.("sdk.streamEvent", {
428 485 type: event.type,
442 499 state.usage.cacheRead = event.message.usage.cache_read_input_tokens ?? 0;
443 500 state.usage.cacheWrite =
444 501 event.message.usage.cache_creation_input_tokens ?? 0;
445 - return;
502 + return false;
447 504 if (event.type === "content_block_start") {
448 505 const block = event.content_block;
478 - return;
535 + return false;
480 537 if (event.type === "content_block_delta") {
481 538 const block = blocks.get(event.index);
482 - if (!block) return;
539 + if (!block) return false;
483 540 if (event.delta.type === "text_delta" && block.type === "text") {
484 541 block.text += event.delta.text;
485 542 callbacks.onContent({
513 570 delta: event.delta.partial_json,
516 - return;
573 + return false;
518 575 if (event.type === "content_block_stop") {
519 576 const block = blocks.get(event.index);
523 580 textLength: block?.text.length,
524 581 name: block?.name,
526 - if (!block) return;
583 + if (!block) return false;
527 584 blocks.delete(event.index);
528 585 if (block.type === "text") {
529 586 callbacks.onContent({
566 623 arguments: arguments_,
569 - return;
626 + return false;
571 628 if (event.type === "message_delta") {
572 629 dbg?.("sdk.messageDelta", {
576 633 state.usage.output = event.usage.output_tokens;
577 634 if (event.delta.stop_reason === "tool_use") {
578 - callbacks.onToolBoundary();
579 - } else if (event.delta.stop_reason === "max_tokens") {
580 - callbacks.onResult({
635 + callbacks.onToolBoundary({
581 636 usage: { ...state.usage },
582 637 responseId: state.responseId,
583 638 responseModel: state.responseModel,
584 - position: state.latestPosition,
585 - stopReason: "length",
640 + addUsage(state.reportedUsage, state.usage);
641 + } else if (event.delta.stop_reason === "max_tokens") {
642 + stopMaxRecovery();
643 + state.deferredOutputLimit = {
644 + usage: { ...state.usage },
645 + responseId: state.responseId,
646 + responseModel: state.responseModel,
647 + position: undefined,
648 + sdkSessionId: state.sdkSessionId,
649 + stopReason: "length",
650 + };
651 + return true;
654 + return false;

extensions/klaus/src/cache.ts

Modified
37 37 .update(`${key.projectKey}\0${key.sessionId}\0${key.subpath ?? ""}`)
38 38 .digest("hex");
40 +export class KlausCacheCorruptionError extends Error {
41 + constructor(message: string, options?: ErrorOptions) {
42 + super(`Klaus cache corruption: ${message}`, options);
43 + this.name = "KlausCacheCorruptionError";
44 + }
40 47 function validateEntry(value: unknown): OpaqueEntry {
41 48 dbg?.("cache.validateEntry", {
42 49 type: typeof value,
51 58 Array.isArray(value) ||
52 59 typeof (value as { type?: unknown }).type !== "string"
54 - throw new Error("Klaus cache contains an invalid opaque session entry.");
61 + throw new KlausCacheCorruptionError("invalid opaque session entry.");
56 63 return value as OpaqueEntry;
360 367 .map((line) => validateEntry(JSON.parse(line) as unknown));
361 368 } catch (error) {
362 369 if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
370 + if (error instanceof KlausCacheCorruptionError) throw error;
371 + if (error instanceof SyntaxError) {
372 + throw new KlausCacheCorruptionError("invalid transcript JSON.", {
373 + cause: error,
374 + });
363 376 throw error;

extensions/klaus/src/coordinator.ts

Modified
12 12 import { type KlausQueryHandle, startSdkQuery } from "./agent-sdk.js";
13 13 import {
14 14 FileSessionStore,
15 + KlausCacheCorruptionError,
15 16 type KlausSessionStore,
16 17 loadCheckpoints,
17 18 MemorySessionStore,
43 44 sink?: PiSink;
44 45 toolCallIds: Set<string>;
45 46 tools: KlausRequest["tools"];
47 + boundaryFingerprint?: string;
48 + boundaryMessageCount?: number;
46 49 closed: boolean;
47 50 closePromise?: Promise<void>;
48 51 timer?: ReturnType<typeof setTimeout>;
52 + timeoutMs?: number;
49 53 idleLease?: ReturnType<typeof setTimeout>;
50 54 abort?: () => void;
51 55 signal?: AbortSignal;
54 58 modelId: string;
55 59 cwd: string;
56 60 thinking: SimpleStreamOptions["reasoning"];
61 + thinkingBudget?: number;
62 + systemPrompt: string;
57 63 headers: SimpleStreamOptions["headers"];
64 + env: SimpleStreamOptions["env"];
58 65 metadata?: Record<string, string>;
59 66 emittedContent: boolean;
60 67 context: Context;
244 - toolUse(): void {
245 - dbg?.("coordinator.sink.toolUse", { finished: this.finished });
251 + toolUse(
252 + usage: {
253 + input: number;
254 + output: number;
255 + cacheRead: number;
256 + cacheWrite: number;
257 + },
258 + responseId?: string,
259 + responseModel?: string,
260 + ): void {
261 + dbg?.("coordinator.sink.toolUse", { finished: this.finished, usage });
246 262 if (this.finished) return;
247 263 this.finished = true;
264 + this.applyUsage(usage, responseId, responseModel);
248 265 this.output.stopReason = "toolUse";
249 266 this.stream.push({ type: "done", reason: "toolUse", message: this.output });
250 267 this.stream.end();
271 288 if (this.finished) return;
272 289 this.finished = true;
290 + this.applyUsage(usage, responseId, responseModel);
291 + this.output.stopReason = stopReason;
292 + this.stream.push({
293 + type: "done",
294 + reason: stopReason,
295 + message: this.output,
296 + });
297 + this.stream.end();
300 + private applyUsage(
301 + usage: {
302 + input: number;
303 + output: number;
304 + cacheRead: number;
305 + cacheWrite: number;
306 + },
307 + responseId?: string,
308 + responseModel?: string,
309 + ): void {
273 310 Object.assign(this.output.usage, usage);
274 311 this.output.usage.totalTokens =
275 312 usage.input + usage.output + usage.cacheRead + usage.cacheWrite;
292 329 this.output.responseId = responseId;
293 330 this.output.responseModel = responseModel;
294 - this.output.stopReason = stopReason;
295 - this.stream.push({
296 - type: "done",
297 - reason: stopReason,
298 - message: this.output,
299 - });
300 - this.stream.end();
303 333 error(error: unknown, aborted = false): void {
440 470 hasHandle: Boolean(continuation?.handle),
442 472 if (continuation?.handle) {
473 + const resultCount = batch.results.length;
474 + const boundaryMessageCount = context.messages.length - resultCount;
475 + const boundaryFingerprint = contextFingerprint(
477 + systemPrompt: context.systemPrompt,
478 + messages: context.messages.slice(0, boundaryMessageCount),
479 + tools: context.tools,
480 + },
481 + `${model.id}\0${this.currentCwd()}`,
482 + );
443 483 const incompatible =
444 484 batch.userAfter ||
445 - continuation.handle.bridge.hasSchemaChange(tools) ||
485 + continuation.boundaryMessageCount !== boundaryMessageCount ||
486 + continuation.boundaryFingerprint !== boundaryFingerprint ||
487 + JSON.stringify(continuation.tools) !== JSON.stringify(tools) ||
446 488 continuation.modelId !== model.id ||
489 + continuation.cwd !== this.currentCwd() ||
490 + continuation.systemPrompt !== (context.systemPrompt ?? "") ||
447 491 continuation.thinking !== options.reasoning ||
448 - JSON.stringify(continuation.headers ?? {}) !==
449 - JSON.stringify(options.headers ?? {}) ||
450 - options.onPayload !== undefined;
492 + continuation.thinkingBudget !== thinkingBudget(options) ||
493 + !sameStringRecord(continuation.headers, options.headers) ||
494 + !sameStringRecord(continuation.env, options.env);
451 495 dbg?.("coordinator.invoke.compatibility", { incompatible });
452 496 if (incompatible) {
453 497 await this.closeState(
460 504 if (continuation.idleLease) clearTimeout(continuation.idleLease);
461 505 continuation.idleLease = undefined;
462 506 this.replaceAbort(continuation, options.signal);
463 - this.armTimeout(continuation, options.timeoutMs);
507 + continuation.timeoutMs = options.timeoutMs;
508 + this.armTimeout(continuation, continuation.timeoutMs);
509 + if (options.signal?.aborted) {
510 + await this.closeState(
511 + continuation,
512 + "Pi aborted the Klaus query.",
513 + true,
514 + );
515 + return;
464 517 if (options.onResponse && continuation.metadata) {
465 518 await options.onResponse(
466 519 { status: 200, headers: continuation.metadata },
467 520 model,
523 + if (options.signal?.aborted) {
524 + await this.closeState(
525 + continuation,
526 + "Pi aborted the Klaus query.",
527 + true,
528 + );
529 + return;
470 531 for (const result of batch.results) {
471 532 await continuation.handle.bridge.waitForPending(
472 533 [result.id],
473 534 options.signal,
536 + if (options.signal?.aborted) {
537 + await this.closeState(
538 + continuation,
539 + "Pi aborted the Klaus query.",
540 + true,
541 + );
542 + return;
475 544 if (!continuation.handle.bridge.settle(result)) {
476 545 throw new Error(`Unknown Klaus tool result ${result.id}.`);
513 582 !forceCold && options.sessionId
514 583 ? this.completed.get(options.sessionId)
515 584 : undefined;
516 - if (memory) candidates.push(memory);
585 + if (memory?.position) candidates.push(memory);
517 586 dbg?.("coordinator.start.memoryCandidate", { found: Boolean(memory) });
518 587 const checkpointRoot = this.checkpointRoot(options.sessionId);
519 588 if (!forceCold && options.sessionId && checkpointRoot) {
522 591 checkpointRoot,
523 592 options.sessionId,
525 - if (
526 - !candidates.some(
527 - (item) => item.fingerprint === checkpoint.fingerprint,
529 - ) {
530 - candidates.push({ ...checkpoint, store });
594 + if (checkpoint.position) candidates.push({ ...checkpoint, store });
533 596 } catch (error) {
534 597 dbg?.("coordinator.start.checkpointLoadError", {
535 598 error: error instanceof Error ? error.message : String(error),
537 - candidates.length = memory ? 1 : 0;
600 + candidates.length = memory?.position ? 1 : 0;
540 603 dbg?.("coordinator.start.candidates", { count: candidates.length });
541 - const completed = candidates.toReversed().find(
542 - (checkpoint) =>
543 - checkpoint.messageCount < context.messages.length &&
544 - checkpoint.fingerprint ===
545 - contextFingerprint(
547 - systemPrompt: context.systemPrompt,
548 - messages: context.messages.slice(0, checkpoint.messageCount),
549 - tools: context.tools,
550 - },
551 - identity,
552 - ),
553 - );
604 + const prefixFingerprints = new Map<number, string>();
605 + let completed: CompletedQuery | undefined;
606 + for (const checkpoint of candidates) {
607 + if (checkpoint.messageCount >= context.messages.length) continue;
608 + let fingerprint = prefixFingerprints.get(checkpoint.messageCount);
609 + if (!fingerprint) {
610 + fingerprint = contextFingerprint(
612 + systemPrompt: context.systemPrompt,
613 + messages: context.messages.slice(0, checkpoint.messageCount),
614 + tools: context.tools,
615 + },
616 + identity,
617 + );
618 + prefixFingerprints.set(checkpoint.messageCount, fingerprint);
620 + if (
621 + checkpoint.fingerprint === fingerprint &&
622 + (!completed || checkpoint.messageCount > completed.messageCount)
623 + ) {
624 + completed = checkpoint;
554 627 dbg?.("coordinator.start.completed", {
555 628 found: Boolean(completed),
556 629 messageCount: completed?.messageCount,
591 664 timeoutMs: options.timeoutMs,
592 665 sessionStore: staging,
593 666 resume: canResume ? completed?.sdkSessionId : undefined,
594 - resumeAt: canResume && !linearResume ? completed?.position : undefined,
595 - forkSession: canResume && !linearResume,
667 + resumeAt: canResume ? completed?.position : undefined,
668 + forkSession: canResume,
597 670 dbg?.("coordinator.start.request", {
598 671 modelId: request.modelId,
644 717 transformed.cwd !== request.cwd ||
645 718 JSON.stringify(transformed.tools) !== JSON.stringify(request.tools))
647 - transformed.resume = undefined;
648 - transformed.resumeAt = undefined;
649 - transformed.forkSession = undefined;
650 - transformed.prompt = replayPrompt(context);
651 - transformed.images = replayImages(context);
720 + await this.start(sink, model, context, options, tools, true);
721 + return;
653 723 const scope = this.currentSession();
654 724 dbg?.("coordinator.start.scope", {
661 731 sessionId: options.sessionId,
663 733 toolCallIds: new Set(),
664 - tools: transformed.tools,
734 + tools,
665 735 closed: false,
736 + timeoutMs: transformed.timeoutMs,
666 737 secondary: Boolean(options.sessionId && options.sessionId !== scope?.id),
667 738 committable: true,
668 739 modelId: model.id,
670 741 thinking: options.reasoning,
742 + thinkingBudget: thinkingBudget(options),
743 + systemPrompt: context.systemPrompt ?? "",
671 744 headers: options.headers,
745 + env: options.env,
672 746 emittedContent: false,
673 747 context,
674 748 store: completed?.store ?? store,
696 770 onActivity: () => {
697 771 dbg?.("coordinator.callback.activity", { closed: state.closed });
698 - this.touchState(state, transformed.timeoutMs);
772 + this.touchState(state, state.timeoutMs);
700 774 onContent: (event) => {
701 775 dbg?.("coordinator.callback.content", {
708 782 if (event.type === "tool-start") state.toolCallIds.add(event.id);
709 783 state.sink?.content(event);
711 - onToolBoundary: () => {
785 + onToolBoundary: (result) => {
712 786 dbg?.("coordinator.callback.toolBoundary", {
713 787 closed: state.closed,
714 788 sessionId: state.sessionId,
728 802 if (state.timer) clearTimeout(state.timer);
729 803 state.timer = undefined;
730 - state.sink?.toolUse();
804 + state.sink?.toolUse(
805 + result.usage,
806 + result.responseId,
807 + result.responseModel,
808 + );
809 + if (state.sink) {
810 + state.boundaryMessageCount = state.context.messages.length + 1;
811 + state.boundaryFingerprint = contextFingerprint(
813 + systemPrompt: state.context.systemPrompt,
814 + messages: [...state.context.messages, state.sink.output],
815 + tools: state.context.tools,
816 + },
817 + `${state.modelId}\0${state.cwd}`,
818 + );
731 820 state.sink = undefined;
732 821 if (state.secondary) {
733 822 state.idleLease = setTimeout(
746 835 closed: state.closed,
748 837 if (state.closed) return;
749 - state.sink?.done(
750 - result.usage,
751 - result.responseId,
752 - result.responseModel,
753 - result.stopReason,
754 - );
838 + const resultSink = state.sink;
755 839 void (async () => {
757 841 state.committable &&
758 842 state.sessionId &&
759 843 result.sdkSessionId &&
760 - state.sink
844 + resultSink
762 - await state.staging.commit();
763 - const completed: CompletedQuery = {
764 - sdkSessionId: result.sdkSessionId,
765 - position: result.position,
766 - messageCount: state.context.messages.length + 1,
767 - protocol: 1,
768 - fingerprint: contextFingerprint(
770 - systemPrompt: state.context.systemPrompt,
771 - messages: [...state.context.messages, state.sink.output],
772 - tools: state.context.tools,
773 - },
774 - `${state.modelId}\0${state.cwd}`,
775 - ),
776 - store: state.store,
777 - };
778 - this.completed.set(state.sessionId, completed);
779 - if (this.checkpointRoot(state.sessionId)) {
780 - this.pendingCheckpoints.set(state.sessionId, completed);
846 + try {
847 + await state.staging.commit();
848 + if (!state.closed && state.committable) {
849 + const completed: CompletedQuery = {
850 + sdkSessionId: result.sdkSessionId,
851 + position: result.position,
852 + messageCount: state.context.messages.length + 1,
853 + protocol: 1,
854 + fingerprint: contextFingerprint(
856 + systemPrompt: state.context.systemPrompt,
857 + messages: [...state.context.messages, resultSink.output],
858 + tools: state.context.tools,
859 + },
860 + `${state.modelId}\0${state.cwd}`,
861 + ),
862 + store: state.store,
863 + };
864 + this.completed.set(state.sessionId, completed);
865 + if (this.checkpointRoot(state.sessionId)) {
866 + this.pendingCheckpoints.set(state.sessionId, completed);
869 + } catch (error) {
870 + this.warn(
871 + `Klaus could not cache the completed session: ${error instanceof Error ? error.message : String(error)}`,
872 + );
875 + if (!state.closed) {
876 + resultSink?.done(
877 + result.usage,
878 + result.responseId,
879 + result.responseModel,
880 + result.stopReason,
881 + );
783 883 await this.closeState(state, "Klaus query completed.");
784 884 })().catch((error) => {
785 - state.sink?.error(error);
885 + resultSink?.error(error);
786 886 void this.closeState(state, "Klaus checkpoint failed.");
794 894 emittedContent: state.emittedContent,
796 896 if (state.closed) return;
797 - if (transformed.resume && !state.emittedContent && state.sink) {
897 + if (
898 + transformed.resume &&
899 + !state.emittedContent &&
900 + state.sink &&
901 + isReplayableResumeError(error)
902 + ) {
798 903 const retrySink = state.sink;
799 904 state.sink = undefined;
800 905 if (state.sessionId) {
1107 +function sameStringRecord(
1108 + left: Record<string, string | null> | undefined,
1109 + right: Record<string, string | null> | undefined,
1110 +): boolean {
1111 + const entries = (value: Record<string, string | null> | undefined) =>
1112 + Object.entries(value ?? {}).sort(([leftKey], [rightKey]) =>
1113 + leftKey < rightKey ? -1 : leftKey > rightKey ? 1 : 0,
1114 + );
1115 + return JSON.stringify(entries(left)) === JSON.stringify(entries(right));
1118 +export function isReplayableResumeError(error: Error): boolean {
1119 + return (
1120 + error instanceof KlausCacheCorruptionError ||
1121 + /^Klaus cache corruption:/i.test(error.message) ||
1122 + /^Resume rejected by --resume-drops-turn:/i.test(error.message)
1123 + );
1002 1126 function thinkingBudget(options: SimpleStreamOptions): number | undefined {
1003 1127 dbg?.("coordinator.thinkingBudget", { reasoning: options.reasoning });
1004 1128 switch (options.reasoning) {

extensions/klaus/src/protocol.ts

Modified
85 85 onReady(metadata: Record<string, string>): Promise<void>;
86 86 onActivity(): void;
87 87 onContent(event: KlausContentEvent): void;
88 - onToolBoundary(): void;
88 + onToolBoundary(result: {
89 + usage: KlausUsage;
90 + responseId?: string;
91 + responseModel?: string;
92 + }): void;
89 93 onResult(result: {
90 94 usage: KlausUsage;
91 95 responseId?: string;

extensions/klaus/src/runtime/index.ts

Modified
1 -import { mkdir, mkdtemp, rm } from "node:fs/promises";
1 +import { mkdtemp, rm } from "node:fs/promises";
2 2 import { validateHeaderName, validateHeaderValue } from "node:http";
3 3 import { tmpdir } from "node:os";
4 4 import { join } from "node:path";
98 98 headerNames: Object.keys(headers),
99 99 overrideNames: Object.keys(overrides),
101 - const root = join(tmpdir(), "klaus");
102 - await mkdir(root, { recursive: true, mode: 0o700 });
103 - const configDir = await mkdtemp(join(root, "query-"));
104 - dbg?.("runtime.create.configDir", { root, configDir });
101 + const configDir = await mkdtemp(join(tmpdir(), "klaus-query-"));
102 + dbg?.("runtime.create.configDir", { configDir });
105 103 const env: Record<string, string> = {};
106 104 for (const key of ENV_ALLOWLIST) {
107 105 const value = overrides[key] ?? process.env[key];