17 17 StagingSessionStore,
19 19 } from
"./cache.js";
20 +import { dbg }
from "./debug.js";
21 22 contextFingerprint,
31 32 } from
"./protocol.js";
32 33 import { replayImages, replayPrompt }
from "./replay.js";
34 +import { rewriteSubscriptionPrompt }
from "./subscription-prompt.js";
33 35 import type { PiToolResult }
from "./tool-bridge.js";
35 37 interface ActiveQuery {
76 78 type ResolveOAuth = (modelId
: string)
=> Promise<
string>;
77 79 type CurrentCwd = ()
=> string;
78 80 type CurrentSession = ()
=> SessionScope | undefined;
81 +type Warn = (message
: string)
=> void;
81 84 readonly stream
= createAssistantMessageEventStream();
85 88 private finished
= false;
87 90 constructor(private readonly model: Model
<string
>) {
91 + dbg?.(
"coordinator.sink.create", {
92 + provider: model.provider,
88 96 this.output
= createAssistant(model);
89 97 this.stream.
push({ type:
"start", partial: this.output });
92 100 content(
event: KlausContentEvent):
void {
101 + dbg?.(
"coordinator.sink.content", {
103 + index:
event.
index,
106 + ? event.delta.
length 108 + ? event.
text.
length 109 + : "thinking" in event 110 + ? event.thinking.
length 112 + name:
"name" in event ? event.
name : undefined,
93 114 if (this.finished)
return;
94 115 switch (
event.
type) {
95 116 case "text-start": {
220 241 toolUse():
void {
242 + dbg?.(
"coordinator.sink.toolUse", { finished: this.finished });
221 243 if (this.finished)
return;
222 244 this.finished
= true;
223 245 this.output.stopReason
= "toolUse";
236 258 responseModel
?: string,
237 259 stopReason:
"stop" | "length" = "stop",
261 + dbg?.(
"coordinator.sink.done", {
262 + finished: this.finished,
239 268 if (this.finished)
return;
240 269 this.finished
= true;
241 270 Object.
assign(this.output.usage, usage);
256 285 error(error: unknown, aborted
= false):
void {
286 + dbg?.(
"coordinator.sink.error", {
287 + finished: this.finished,
289 + error: error
instanceof Error ? error.message
: String(error),
257 291 if (this.finished)
return;
258 292 this.finished
= true;
259 293 this.output.stopReason
= aborted
? "aborted" : "error";
281 315 private readonly
resolveOAuth: ResolveOAuth,
282 316 private readonly
currentCwd: CurrentCwd,
283 317 private readonly
currentSession:
CurrentSession = ()
=> undefined,
318 + private readonly
warn:
Warn = ()
=> undefined,
320 + dbg?.(
"coordinator.create");
287 324 model: Model
<string
>,
288 325 context: Context,
289 326 options: SimpleStreamOptions
= {},
290 327 ): AssistantMessageEventStream {
328 + dbg?.(
"coordinator.stream", {
330 + messageCount: context.messages.
length,
331 + toolCount: context.tools?.
length ?? 0,
332 + sessionId: options.sessionId,
333 + reasoning: options.reasoning,
291 335 const sink
= new PiSink(model);
292 336 void this.
invoke(sink, model, context, options);
293 337 return sink.stream;
296 340 preparePrimaryCache(scope: SessionScope):
Promise<void> {
341 + dbg?.(
"coordinator.preparePrimaryCache", {
343 + persisted: scope.persisted,
297 346 if (
!scope.persisted) {
298 347 this.cacheReady
= Promise.
resolve();
299 348 return this.cacheReady;
307 356 async
persistCheckpoint(sessionId: string, piLeafId: string):
Promise<void> {
357 + dbg?.(
"coordinator.persistCheckpoint.start", { sessionId, piLeafId });
308 358 const checkpoint
= this.pendingCheckpoints.
get(sessionId);
309 359 const root
= this.
checkpointRoot(sessionId);
310 - if (!checkpoint || !root) return;
360 + if (
!checkpoint
|| !root) {
361 + dbg?.(
"coordinator.persistCheckpoint.skip", {
363 + hasCheckpoint:
Boolean(checkpoint),
364 + hasRoot:
Boolean(
root),
311 368 checkpoint.piLeafId
= piLeafId;
312 369 await saveCheckpoint(
root, sessionId, checkpoint);
313 370 this.pendingCheckpoints.
delete(sessionId);
371 + dbg?.(
"coordinator.persistCheckpoint.end", { sessionId, piLeafId });
316 374 async
closeAll(reason: string):
Promise<void> {
375 + dbg?.(
"coordinator.closeAll.start", { reason });
318 377 ...this.anonymous,
319 378 ...[
...this.bySession.
values()].
flatMap((states)
=> [
...states]),
323 382 this.memoryStores.
clear();
324 383 this.diskStores.
clear();
325 384 this.pendingCheckpoints.
clear();
385 + dbg?.(
"coordinator.closeAll.end", { reason, stateCount: states.
length });
328 388 private async
invoke(
331 391 context: Context,
332 392 options: SimpleStreamOptions,
333 393 ):
Promise<void> {
394 + dbg?.(
"coordinator.invoke.start", {
396 + sessionId: options.sessionId,
397 + messageCount: context.messages.
length,
335 400 if (
!isKlausModelId(model.
id))
336 401 throw new Error(
`Unsupported Klaus model ${model.id}.`);
343 408 const batch
= recentToolResults(context);
409 + dbg?.(
"coordinator.invoke.batch", {
410 + resultCount: batch.results.
length,
411 + userAfter: batch.userAfter,
344 413 const continuation
= this.
findContinuation(
345 414 options.sessionId,
348 417 const tools
= toKlausTools(context.tools);
418 + dbg?.(
"coordinator.invoke.continuation", {
419 + found:
Boolean(continuation),
420 + hasHandle:
Boolean(continuation?.handle),
349 422 if (continuation?.handle) {
350 423 const incompatible
= 351 424 batch.userAfter
|| 355 428 JSON.
stringify(continuation.
headers ?? {})
!== 356 429 JSON.
stringify(options.
headers ?? {})
|| 357 430 options.onPayload
!== undefined;
431 + dbg?.(
"coordinator.invoke.compatibility", { incompatible });
358 432 if (incompatible) {
359 433 await this.
closeState(
388 462 await this.
start(sink, model, context, options, tools);
389 463 }
catch (error) {
464 + dbg?.(
"coordinator.invoke.error", {
465 + error: error
instanceof Error ? error.message
: String(error),
390 467 sink.
error(error, options.signal?.aborted);
399 476 tools: KlausRequest[
"tools"],
400 477 forceCold
= false,
401 478 ):
Promise<void> {
479 + dbg?.(
"coordinator.start.begin", {
481 + sessionId: options.sessionId,
483 + messageCount: context.messages.
length,
484 + toolNames: tools.
map((tool)
=> tool.
name),
402 486 await this.cacheReady;
487 + dbg?.(
"coordinator.start.cacheReady");
403 488 const store
= this.
storeFor(options.sessionId);
404 489 const cwd
= this.
currentCwd();
405 490 const identity
= `${model.id}\0${cwd}`;
409 494 ? this.completed.
get(options.sessionId)
411 496 if (memory) candidates.
push(memory);
497 + dbg?.(
"coordinator.start.memoryCandidate", { found:
Boolean(memory) });
412 498 const checkpointRoot
= this.
checkpointRoot(options.sessionId);
413 499 if (
!forceCold
&& options.sessionId
&& checkpointRoot) {
424 510 candidates.
push({
...checkpoint, store });
514 + dbg?.(
"coordinator.start.checkpointLoadError", {
515 + error: error
instanceof Error ? error.message
: String(error),
428 517 candidates.
length = memory
? 1 : 0;
520 + dbg?.(
"coordinator.start.candidates", { count: candidates.
length });
431 521 const completed
= candidates.
toReversed().
find(
433 523 checkpoint.messageCount
< context.messages.
length && 534 + dbg?.(
"coordinator.start.completed", {
535 + found:
Boolean(completed),
536 + messageCount: completed?.messageCount,
444 538 const deltaContext
: Context = {
445 539 systemPrompt: context.systemPrompt,
446 540 messages: completed
453 547 deltaContext.messages.
length === 1 && 454 548 isTextUser(deltaContext.messages[
0]);
455 549 const canResume
= completed
!== undefined;
550 + dbg?.(
"coordinator.start.resumePlan", {
553 + deltaMessageCount: deltaContext.messages.
length,
456 555 const staging
= new StagingSessionStore(completed?.store
?? store);
457 556 const request
: KlausRequest = {
458 557 modelId: model.
id as keyof typeof MODEL_SELECTORS,
475 574 resumeAt: canResume
&& !linearResume
? completed?.position
: undefined,
476 575 forkSession: canResume
&& !linearResume,
577 + dbg?.(
"coordinator.start.request", {
578 + modelId: request.modelId,
579 + selector: request.selector,
580 + promptLength: request.
prompt.
length,
581 + systemPromptLength: request.systemPrompt.
length,
582 + imageCount: request.
images?.
length ?? 0,
583 + toolNames: request.tools.
map((tool)
=> tool.
name),
584 + thinking: request.thinking,
585 + thinkingBudget: request.thinkingBudget,
587 + resume:
Boolean(request.resume),
588 + resumeAt:
Boolean(request.resumeAt),
589 + forkSession: request.forkSession,
478 591 const payloadRequest
: KlausRequest = {
...request };
479 592 delete payloadRequest.sessionStore;
480 593 delete payloadRequest.resume;
481 594 delete payloadRequest.resumeAt;
482 595 delete payloadRequest.forkSession;
596 + dbg?.(
"coordinator.start.payloadHook", {
597 + enabled: options.onPayload
!== undefined,
483 599 const hookPayload
= options.onPayload
484 600 ? await options.
onPayload(payloadRequest, model)
494 610 forkSession: request.forkSession,
496 612 : transformedPayload;
613 + dbg?.(
"coordinator.start.payloadTransformed", {
614 + transformed: hookPayload
!== undefined,
615 + valid:
isRequest(transformed),
497 617 if (
!isRequest(transformed))
498 618 throw new Error(
"Klaus onPayload returned an invalid request.");
511 631 transformed.
images = replayImages(context);
513 633 const scope
= this.
currentSession();
634 + dbg?.(
"coordinator.start.scope", {
635 + sessionId: scope?.
id,
636 + persisted: scope?.persisted,
514 639 const state
: ActiveQuery = {
515 640 id:
Symbol(
"klaus-query"),
516 641 sessionId: options.sessionId,
532 657 this.
addState(state);
658 + dbg?.(
"coordinator.start.stateAdded", {
659 + sessionId: state.sessionId,
660 + secondary: state.secondary,
661 + committable: state.committable,
533 663 this.
armTimeout(state, transformed.timeoutMs);
534 664 this.
replaceAbort(state, options.signal);
535 665 if (options.signal?.aborted) {
539 669 const callbacks
: KlausQueryCallbacks = {
540 670 onReady:
async (metadata)
=> {
671 + dbg?.(
"coordinator.callback.ready", metadata);
541 672 if (state.
closed)
return;
542 673 state.metadata
= metadata;
543 674 await options.
onResponse?.({ status:
200, headers: metadata }, model);
545 - onActivity: ()
=> this.
touchState(state, transformed.timeoutMs),
676 + onActivity: ()
=> {
677 + dbg?.(
"coordinator.callback.activity", { closed: state.
closed });
678 + this.
touchState(state, transformed.timeoutMs);
546 680 onContent: (event)
=> {
681 + dbg?.(
"coordinator.callback.content", {
683 + index:
event.
index,
684 + name:
"name" in event ? event.
name : undefined,
547 686 if (state.
closed)
return;
548 687 state.emittedContent
= true;
549 688 if (
event.
type === "tool-start") state.toolCallIds.
add(
event.
id);
550 689 state.sink?.
content(
event);
552 691 onToolBoundary: ()
=> {
692 + dbg?.(
"coordinator.callback.toolBoundary", {
693 + closed: state.
closed,
694 + sessionId: state.sessionId,
695 + secondary: state.secondary,
553 697 if (state.
closed)
return;
554 698 if (
!state.sessionId) {
555 699 state.sink?.
error(
579 723 onResult: (result)
=> {
724 + dbg?.(
"coordinator.callback.result", {
726 + closed: state.
closed,
580 728 if (state.
closed)
return;
581 729 state.sink?.
done(
621 769 onError: (error)
=> {
770 + dbg?.(
"coordinator.callback.error", {
771 + error: error.message,
772 + closed: state.
closed,
773 + resume:
Boolean(transformed.resume),
774 + emittedContent: state.emittedContent,
622 776 if (state.
closed)
return;
623 777 if (transformed.resume
&& !state.emittedContent
&& state.sink) {
624 778 const retrySink
= state.sink;
798 + dbg?.(
"coordinator.oauth.resolve.start", { modelId: model.
id });
644 799 const oauth
= await this.
resolveOAuth(model.
id);
800 + dbg?.(
"coordinator.oauth.resolve.end", {
802 + tokenLength: oauth.
length,
645 804 if (state.
closed)
return;
646 - const handle
= await startSdkQuery(transformed, oauth, callbacks);
805 + dbg?.(
"coordinator.sdk.start");
806 + const outgoing
= rewriteSubscriptionPrompt(transformed, this.warn);
807 + const handle
= await startSdkQuery(outgoing, oauth, callbacks);
808 + dbg?.(
"coordinator.sdk.started");
647 809 if (state.
closed) {
648 810 await handle.
close(
"Klaus query closed during startup.");
651 813 state.handle
= handle;
814 + dbg?.(
"coordinator.handle.attached");
652 815 }
catch (error) {
816 + dbg?.(
"coordinator.start.error", {
817 + error: error
instanceof Error ? error.message
: String(error),
653 819 state.sink?.
error(error, options.signal?.aborted);
654 820 await this.
closeState(state,
"Klaus query startup failed.");
659 825 sessionId: string
| undefined,
660 826 results: PiToolResult[],
661 827 ): ActiveQuery
| undefined {
828 + dbg?.(
"coordinator.findContinuation", {
830 + resultIds: results.
map((result)
=> result.
id),
662 832 if (
!sessionId
|| results.
length === 0)
return undefined;
663 833 return [
...(this.bySession.
get(sessionId)
?? [])].
find(
670 840 private
addState(state: ActiveQuery):
void {
841 + dbg?.(
"coordinator.addState", { sessionId: state.sessionId });
671 842 if (
!state.sessionId) {
672 843 this.anonymous.
add(state);
685 856 state: ActiveQuery,
686 857 signal: AbortSignal
| undefined,
859 + dbg?.(
"coordinator.replaceAbort", {
860 + hadSignal:
Boolean(state.signal),
861 + hasSignal:
Boolean(signal),
862 + aborted: signal?.aborted,
688 864 if (state.signal
&& state.abort) {
689 865 state.signal.
removeEventListener(
"abort", state.abort);
700 876 private
touchState(state: ActiveQuery, timeoutMs: number
| undefined):
void {
877 + dbg?.(
"coordinator.touchState", {
878 + sessionId: state.sessionId,
880 + hasIdleLease:
Boolean(state.idleLease),
701 882 this.
armTimeout(state, timeoutMs);
702 883 if (
!state.idleLease)
return;
703 884 clearTimeout(state.idleLease);
714 895 private
checkpointRoot(sessionId: string
| undefined): string
| undefined {
715 896 const scope
= this.
currentSession();
897 + dbg?.(
"coordinator.checkpointRoot", {
899 + scopeId: scope?.
id,
900 + persisted: scope?.persisted,
716 902 return sessionId
&& scope?.
id === sessionId
&& scope.persisted
717 903 ? join(scope.
dir,
".klaus",
"checkpoints")
721 907 private
storeFor(sessionId: string
| undefined): KlausSessionStore {
908 + dbg?.(
"coordinator.storeFor", { sessionId });
722 909 if (
!sessionId)
return new MemorySessionStore();
723 910 const scope
= this.
currentSession();
724 911 if (scope?.
id === sessionId
&& scope.persisted) {
738 925 private
armTimeout(state: ActiveQuery, timeoutMs: number
| undefined):
void {
926 + dbg?.(
"coordinator.armTimeout", {
927 + sessionId: state.sessionId,
929 + closed: state.
closed,
930 + hasSink:
Boolean(state.sink),
739 932 if (state.timer)
clearTimeout(state.timer);
740 933 if (
!timeoutMs
|| state.
closed || !state.sink)
return;
741 934 state.timer
= setTimeout(()
=> {
753 946 ):
Promise<void> {
947 + dbg?.(
"coordinator.closeState.start", {
948 + sessionId: state.sessionId,
951 + alreadyClosed: state.
closed,
952 + hasHandle:
Boolean(state.handle),
754 954 if (state.
closed)
return;
755 955 state.
closed = true;
756 956 if (state.timer)
clearTimeout(state.timer);
768 968 this.anonymous.
delete(state);
970 + dbg?.(
"coordinator.closeState.end", { sessionId: state.sessionId, reason });
773 974 function thinkingBudget(options
: SimpleStreamOptions)
: number | undefined {
975 + dbg?.(
"coordinator.thinkingBudget", { reasoning: options.reasoning });
774 976 switch (options.reasoning) {
776 978 return options.thinkingBudgets?.minimal;
798 1000 function finalUserPrompt(context
: Context)
: string {
1001 + dbg?.(
"coordinator.finalUserPrompt", {
1002 + messageCount: context.messages.
length,
799 1004 const message
= context.messages.
at(
-1);
800 1005 if (message?.role
!== "user")
return replayPrompt(context);
801 1006 return typeof message.
content === "string" 810 1015 results: PiToolResult[];
811 1016 userAfter: boolean;
1018 + dbg?.(
"coordinator.recentToolResults.start", {
1019 + messageCount: context.messages.
length,
813 1021 const results
: PiToolResult[]
= [];
814 1022 let userAfter
= false;
815 1023 for (
let index
= context.messages.
length - 1; index
>= 0; index
-= 1) {
825 1033 isError: message.isError,
1036 + dbg?.(
"coordinator.recentToolResults.end", {
1037 + resultIds: results.
map((result)
=> result.
id),
828 1040 return { results, userAfter };
831 1043 function isRequest(value
: unknown)
: value
is KlausRequest {
1044 + dbg?.(
"coordinator.isRequest", {
1045 + type:
typeof value,
1046 + isArray:
Array.
isArray(value),
832 1048 if (
typeof value
!== "object" || value
=== null || Array.
isArray(value))
834 1050 const request
= value
as Partial<
KlausRequest>;