omk-agent-core 0.98.1 → 0.98.2

package/dist/harness/operation-outcome.js

@@ -0,0 +1,131 @@
+/**
+ * Pure outcome classification and error aggregation for harness operations.
+ *
+ * Everything here is a total function over already-observed results: it never
+ * touches lifecycle state, sessions, providers, or clocks. Keeping the rules in
+ * one leaf module makes the precedence auditable in isolation and keeps
+ * `agent-harness.ts` free of the branch-heavy classification tables.
+ */
+import { isContextOverflow } from "omk-ai";
+import { AgentHarnessError, BranchSummaryError, CompactionError, SessionError, toError } from "./types.js";
+/**
+ * True only for an error that *is* an abort, not merely an error raised while
+ * an abort signal happened to be up. `AgentHarnessError` has no "aborted" code,
+ * so an explicit abort reaches us as a subsystem error carrying code "aborted"
+ * or as a DOM-style `AbortError`.
+ */
+export function isExplicitAbortError(error) {
+    const cause = toError(error);
+    if (cause.name === "AbortError")
+        return true;
+    return (cause instanceof CompactionError || cause instanceof BranchSummaryError) && cause.code === "aborted";
+}
+/** Map a subsystem failure onto the harness' stable top-level classification. */
+export function normalizeHarnessError(error, fallbackCode) {
+    if (error instanceof AgentHarnessError)
+        return error;
+    const cause = toError(error);
+    if (cause instanceof SessionError)
+        return new AgentHarnessError("session", cause.message, cause);
+    if (cause instanceof CompactionError)
+        return new AgentHarnessError("compaction", cause.message, cause);
+    if (cause instanceof BranchSummaryError)
+        return new AgentHarnessError("branch_summary", cause.message, cause);
+    return new AgentHarnessError(fallbackCode, cause.message, cause);
+}
+/** Result-based outcome for prompt-family operations that resolve with a failure/abort assistant message. */
+export function classifyAssistantOutcome(message) {
+    if (message.stopReason === "aborted")
+        return { status: "aborted" };
+    if (message.stopReason === "error") {
+        return { status: "failed", code: "provider", message: message.errorMessage ?? "Provider error" };
+    }
+    return undefined;
+}
+/** Structural cancellation is a distinct, non-failure terminal outcome. */
+export function classifyNavigateTreeOutcome(result) {
+    return result.cancelled ? { status: "cancelled", reason: "tree_navigation_cancelled" } : { status: "completed" };
+}
+/** A thrown attempt body is an aborted attempt only when the error itself is an abort. */
+export function classifyAttemptFailure(error) {
+    return isExplicitAbortError(error) ? "aborted" : "failed";
+}
+/** Context overflow is a recoverable attempt outcome, not an attempt failure. */
+export function classifyAttemptOutcome(message, contextWindow) {
+    if (message.stopReason === "aborted")
+        return "aborted";
+    if (isContextOverflow(message, contextWindow))
+        return "overflow";
+    if (message.stopReason === "error")
+        return "failed";
+    return "completed";
+}
+/**
+ * Single outcome-precedence rule for every public operation:
+ *
+ *   session persistence failure > non-abort body/hook failure >
+ *   explicit abort > result-classified outcome > completed
+ *
+ * A raised abort signal alone never downgrades another failure to "aborted":
+ * only an error that *is* an abort does. Otherwise a flush failure during an
+ * aborted turn would settle as "aborted" while the public promise rejected
+ * with "session".
+ */
+export function resolveOperationOutcome(input) {
+    if (input.flushError !== undefined) {
+        // Mirror `resolveOperationFailure`: a flush error that already carries a
+        // harness classification (e.g. an `invalid_state` coordinator reentry)
+        // keeps it, so the recorded outcome and the rejection never disagree.
+        const error = normalizeHarnessError(input.flushError, "session");
+        return { status: "failed", code: error.code, message: error.message };
+    }
+    if (input.bodyError !== undefined) {
+        if (isExplicitAbortError(input.bodyError))
+            return { status: "aborted" };
+        const error = normalizeHarnessError(input.bodyError, input.fallbackCode);
+        return { status: "failed", code: error.code, message: error.message };
+    }
+    return (input.classifyResult?.(input.result) ??
+        (input.signalAborted ? { status: "aborted" } : { status: "completed" }));
+}
+/**
+ * The error a boundary should throw after several steps may have failed, or
+ * `undefined` when none did. A single failure is returned untouched so its
+ * own classification survives; several are kept reachable through one
+ * `AggregateError`, classified by the first (primary) failure. This is what
+ * lets a failing boundary flush report *alongside* the body or listener error
+ * it followed instead of erasing it.
+ */
+export function combineBoundaryErrors(errors, message, fallbackCode) {
+    const present = errors.filter((error) => error !== undefined);
+    if (present.length <= 1)
+        return present[0];
+    const cause = new AggregateError(present.map(toError), message);
+    return new AgentHarnessError(normalizeHarnessError(present[0], fallbackCode).code, cause.message, cause);
+}
+/**
+ * Which error a public operation rejects with, or `undefined` on success.
+ *
+ * Mirrors the outcome precedence, but every concurrent cause is preserved in an
+ * `AggregateError` so an audit can still see that, say, the body and the final
+ * flush failed together.
+ */
+export function resolveOperationFailure(input) {
+    const primaryError = input.bodyError ?? input.flushError;
+    if (primaryError !== undefined && input.settleError !== undefined) {
+        const cause = new AggregateError([toError(primaryError), toError(input.settleError)], "Operation failed and settlement failed");
+        return new AgentHarnessError(normalizeHarnessError(primaryError, input.fallbackCode).code, cause.message, cause);
+    }
+    if (input.settleError !== undefined)
+        return normalizeHarnessError(input.settleError, "hook");
+    if (input.flushError !== undefined) {
+        if (input.bodyError === undefined)
+            return normalizeHarnessError(input.flushError, "session");
+        const cause = new AggregateError([toError(input.bodyError), toError(input.flushError)], "Operation failed and the final flush failed");
+        return new AgentHarnessError("session", cause.message, cause);
+    }
+    if (input.bodyError !== undefined)
+        return normalizeHarnessError(input.bodyError, input.fallbackCode);
+    return undefined;
+}
+//# sourceMappingURL=operation-outcome.js.map

package/dist/harness/operation-outcome.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"operation-outcome.js","sourceRoot":"","sources":["../../src/harness/operation-outcome.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Pure outcome classification and error aggregation for harness operations.\n *\n * Everything here is a total function over already-observed results: it never\n * touches lifecycle state, sessions, providers, or clocks. Keeping the rules in\n * one leaf module makes the precedence auditable in isolation and keeps\n * `agent-harness.ts` free of the branch-heavy classification tables.\n */\n\nimport { type AssistantMessage, isContextOverflow } from \"omk-ai\";\nimport type { HarnessAttemptOutcome, HarnessOperationOutcome } from \"./operation-lifecycle-types.ts\";\nimport type { NavigateTreeResult } from \"./types.ts\";\nimport { AgentHarnessError, BranchSummaryError, CompactionError, SessionError, toError } from \"./types.ts\";\n\n/**\n * True only for an error that *is* an abort, not merely an error raised while\n * an abort signal happened to be up. `AgentHarnessError` has no \"aborted\" code,\n * so an explicit abort reaches us as a subsystem error carrying code \"aborted\"\n * or as a DOM-style `AbortError`.\n */\nexport function isExplicitAbortError(error: unknown): boolean {\n\tconst cause = toError(error);\n\tif (cause.name === \"AbortError\") return true;\n\treturn (cause instanceof CompactionError || cause instanceof BranchSummaryError) && cause.code === \"aborted\";\n}\n\n/** Map a subsystem failure onto the harness' stable top-level classification. */\nexport function normalizeHarnessError(error: unknown, fallbackCode: AgentHarnessError[\"code\"]): AgentHarnessError {\n\tif (error instanceof AgentHarnessError) return error;\n\tconst cause = toError(error);\n\tif (cause instanceof SessionError) return new AgentHarnessError(\"session\", cause.message, cause);\n\tif (cause instanceof CompactionError) return new AgentHarnessError(\"compaction\", cause.message, cause);\n\tif (cause instanceof BranchSummaryError) return new AgentHarnessError(\"branch_summary\", cause.message, cause);\n\treturn new AgentHarnessError(fallbackCode, cause.message, cause);\n}\n\n/** Result-based outcome for prompt-family operations that resolve with a failure/abort assistant message. */\nexport function classifyAssistantOutcome(message: AssistantMessage): HarnessOperationOutcome | undefined {\n\tif (message.stopReason === \"aborted\") return { status: \"aborted\" };\n\tif (message.stopReason === \"error\") {\n\t\treturn { status: \"failed\", code: \"provider\", message: message.errorMessage ?? \"Provider error\" };\n\t}\n\treturn undefined;\n}\n\n/** Structural cancellation is a distinct, non-failure terminal outcome. */\nexport function classifyNavigateTreeOutcome(result: NavigateTreeResult): HarnessOperationOutcome {\n\treturn result.cancelled ? { status: \"cancelled\", reason: \"tree_navigation_cancelled\" } : { status: \"completed\" };\n}\n\n/** A thrown attempt body is an aborted attempt only when the error itself is an abort. */\nexport function classifyAttemptFailure(error: unknown): HarnessAttemptOutcome {\n\treturn isExplicitAbortError(error) ? \"aborted\" : \"failed\";\n}\n\n/** Context overflow is a recoverable attempt outcome, not an attempt failure. */\nexport function classifyAttemptOutcome(\n\tmessage: AssistantMessage,\n\tcontextWindow: number | undefined,\n): HarnessAttemptOutcome {\n\tif (message.stopReason === \"aborted\") return \"aborted\";\n\tif (isContextOverflow(message, contextWindow)) return \"overflow\";\n\tif (message.stopReason === \"error\") return \"failed\";\n\treturn \"completed\";\n}\n\n/**\n * Single outcome-precedence rule for every public operation:\n *\n *   session persistence failure > non-abort body/hook failure >\n *   explicit abort > result-classified outcome > completed\n *\n * A raised abort signal alone never downgrades another failure to \"aborted\":\n * only an error that *is* an abort does. Otherwise a flush failure during an\n * aborted turn would settle as \"aborted\" while the public promise rejected\n * with \"session\".\n */\nexport function resolveOperationOutcome<T>(input: {\n\treadonly signalAborted: boolean;\n\treadonly result: T | undefined;\n\treadonly bodyError: unknown;\n\treadonly flushError: unknown;\n\treadonly classifyResult: ((result: T) => HarnessOperationOutcome | undefined) | undefined;\n\treadonly fallbackCode: AgentHarnessError[\"code\"];\n}): HarnessOperationOutcome {\n\tif (input.flushError !== undefined) {\n\t\t// Mirror `resolveOperationFailure`: a flush error that already carries a\n\t\t// harness classification (e.g. an `invalid_state` coordinator reentry)\n\t\t// keeps it, so the recorded outcome and the rejection never disagree.\n\t\tconst error = normalizeHarnessError(input.flushError, \"session\");\n\t\treturn { status: \"failed\", code: error.code, message: error.message };\n\t}\n\tif (input.bodyError !== undefined) {\n\t\tif (isExplicitAbortError(input.bodyError)) return { status: \"aborted\" };\n\t\tconst error = normalizeHarnessError(input.bodyError, input.fallbackCode);\n\t\treturn { status: \"failed\", code: error.code, message: error.message };\n\t}\n\treturn (\n\t\tinput.classifyResult?.(input.result as T) ??\n\t\t(input.signalAborted ? { status: \"aborted\" } : { status: \"completed\" })\n\t);\n}\n\n/**\n * The error a boundary should throw after several steps may have failed, or\n * `undefined` when none did. A single failure is returned untouched so its\n * own classification survives; several are kept reachable through one\n * `AggregateError`, classified by the first (primary) failure. This is what\n * lets a failing boundary flush report *alongside* the body or listener error\n * it followed instead of erasing it.\n */\nexport function combineBoundaryErrors(\n\terrors: readonly unknown[],\n\tmessage: string,\n\tfallbackCode: AgentHarnessError[\"code\"],\n): unknown {\n\tconst present = errors.filter((error) => error !== undefined);\n\tif (present.length <= 1) return present[0];\n\tconst cause = new AggregateError(present.map(toError), message);\n\treturn new AgentHarnessError(normalizeHarnessError(present[0], fallbackCode).code, cause.message, cause);\n}\n\n/**\n * Which error a public operation rejects with, or `undefined` on success.\n *\n * Mirrors the outcome precedence, but every concurrent cause is preserved in an\n * `AggregateError` so an audit can still see that, say, the body and the final\n * flush failed together.\n */\nexport function resolveOperationFailure(input: {\n\treadonly bodyError: unknown;\n\treadonly flushError: unknown;\n\treadonly settleError: unknown;\n\treadonly fallbackCode: AgentHarnessError[\"code\"];\n}): AgentHarnessError | undefined {\n\tconst primaryError = input.bodyError ?? input.flushError;\n\tif (primaryError !== undefined && input.settleError !== undefined) {\n\t\tconst cause = new AggregateError(\n\t\t\t[toError(primaryError), toError(input.settleError)],\n\t\t\t\"Operation failed and settlement failed\",\n\t\t);\n\t\treturn new AgentHarnessError(normalizeHarnessError(primaryError, input.fallbackCode).code, cause.message, cause);\n\t}\n\tif (input.settleError !== undefined) return normalizeHarnessError(input.settleError, \"hook\");\n\tif (input.flushError !== undefined) {\n\t\tif (input.bodyError === undefined) return normalizeHarnessError(input.flushError, \"session\");\n\t\tconst cause = new AggregateError(\n\t\t\t[toError(input.bodyError), toError(input.flushError)],\n\t\t\t\"Operation failed and the final flush failed\",\n\t\t);\n\t\treturn new AgentHarnessError(\"session\", cause.message, cause);\n\t}\n\tif (input.bodyError !== undefined) return normalizeHarnessError(input.bodyError, input.fallbackCode);\n\treturn undefined;\n}\n"]}

package/dist/harness/session-write-coordinator.d.ts

@@ -0,0 +1,76 @@
+import type { ImageContent, TextContent } from "omk-ai";
+export type QueuedSessionWrite<TMessage> = {
+    readonly type: "message";
+    readonly message: TMessage;
+} | {
+    readonly type: "thinking_level_change";
+    readonly thinkingLevel: string;
+} | {
+    readonly type: "model_change";
+    readonly provider: string;
+    readonly modelId: string;
+} | {
+    readonly type: "active_tools_change";
+    readonly activeToolNames: string[];
+} | {
+    readonly type: "custom";
+    readonly customType: string;
+    readonly data?: unknown;
+} | {
+    readonly type: "custom_message";
+    readonly customType: string;
+    readonly content: string | (TextContent | ImageContent)[];
+    readonly details?: unknown;
+    readonly display: boolean;
+} | {
+    readonly type: "label";
+    readonly targetId: string;
+    readonly label: string | undefined;
+} | {
+    readonly type: "session_info";
+    readonly name?: string;
+} | {
+    readonly type: "leaf";
+    readonly targetId: string | null;
+};
+interface SessionWritePort<TMessage> {
+    getStorage(): {
+        setLeafId(targetId: string | null): Promise<void>;
+    };
+    appendMessage(message: TMessage): Promise<unknown>;
+    appendThinkingLevelChange(thinkingLevel: string): Promise<unknown>;
+    appendModelChange(provider: string, modelId: string): Promise<unknown>;
+    appendActiveToolsChange(activeToolNames: string[]): Promise<unknown>;
+    appendCustomEntry(customType: string, data?: unknown): Promise<unknown>;
+    appendCustomMessageEntry(customType: string, content: string | (TextContent | ImageContent)[], display: boolean, details?: unknown): Promise<unknown>;
+    appendLabel(targetId: string, label: string | undefined): Promise<unknown>;
+    appendSessionName(name: string): Promise<unknown>;
+    moveTo(targetId: string | null): Promise<unknown>;
+}
+/**
+ * Owns ordered pending writes and serializes coordinator-routed persistence.
+ *
+ * Persistence follows *acceptance* order, not the queue contents observed when
+ * a boundary finally runs. Each boundary captures a watermark at invocation
+ * time and drains only writes accepted at or before it, so a write enqueued
+ * after an idle boundary was reserved can never overtake it.
+ */
+export declare class SessionWriteCoordinator<TMessage> {
+    private readonly pendingWrites;
+    private nextSequence;
+    private operationTail?;
+    private invokingOperation;
+    private readonly session;
+    constructor(session: SessionWritePort<TMessage>);
+    enqueue(write: QueuedSessionWrite<TMessage>): void;
+    hasPending(): boolean;
+    snapshot(): readonly QueuedSessionWrite<TMessage>[];
+    flush(): Promise<void>;
+    persistAfterPending(write: QueuedSessionWrite<TMessage>): Promise<void>;
+    private flushPendingThrough;
+    private persistIdleWrite;
+    private persist;
+    private serialize;
+}
+export {};
+//# sourceMappingURL=session-write-coordinator.d.ts.map

package/dist/harness/session-write-coordinator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-write-coordinator.d.ts","sourceRoot":"","sources":["../../src/harness/session-write-coordinator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AAIxD,MAAM,MAAM,kBAAkB,CAAC,QAAQ,IACpC;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAA;CAAE,GACxD;IAAE,QAAQ,CAAC,IAAI,EAAE,uBAAuB,CAAC;IAAC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;CAAE,GAC1E;IAAE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACtF;IAAE,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC;IAAC,QAAQ,CAAC,eAAe,EAAE,MAAM,EAAE,CAAA;CAAE,GAC5E;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,GACjF;IACA,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,CAAC,WAAW,GAAG,YAAY,CAAC,EAAE,CAAC;IAC1D,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CACzB,GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,GACzF;IAAE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GACzD;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC;AAE/D,UAAU,gBAAgB,CAAC,QAAQ;IAClC,UAAU,IAAI;QAAE,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;KAAE,CAAC;IACpE,aAAa,CAAC,OAAO,EAAE,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACnD,yBAAyB,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACnE,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACvE,uBAAuB,CAAC,eAAe,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACrE,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACxE,wBAAwB,CACvB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,GAAG,CAAC,WAAW,GAAG,YAAY,CAAC,EAAE,EAChD,OAAO,EAAE,OAAO,EAChB,OAAO,CAAC,EAAE,OAAO,GACf,OAAO,CAAC,OAAO,CAAC,CAAC;IACpB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC3E,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAClD,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAClD;AAQD;;;;;;;GAOG;AACH,qBAAa,uBAAuB,CAAC,QAAQ;IAC5C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAyC;IACvE,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,aAAa,CAAC,CAAgB;IACtC,OAAO,CAAC,iBAAiB,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA6B;IAErD,YAAY,OAAO,EAAE,gBAAgB,CAAC,QAAQ,CAAC,EAE9C;IAED,OAAO,CAAC,KAAK,EAAE,kBAAkB,CAAC,QAAQ,CAAC,GAAG,IAAI,CAEjD;IAED,UAAU,IAAI,OAAO,CAEpB;IAED,QAAQ,IAAI,SAAS,kBAAkB,CAAC,QAAQ,CAAC,EAAE,CAGlD;IAEK,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAG3B;IAEK,mBAAmB,CAAC,KAAK,EAAE,kBAAkB,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAQ5E;YAGa,mBAAmB;YAUnB,gBAAgB;YAQhB,OAAO;IA4CrB,OAAO,CAAC,SAAS;CA2BjB","sourcesContent":["import type { ImageContent, TextContent } from \"omk-ai\";\nimport { createImmutableSnapshot } from \"../plain-data.ts\";\nimport { AgentHarnessError } from \"./errors.ts\";\n\nexport type QueuedSessionWrite<TMessage> =\n\t| { readonly type: \"message\"; readonly message: TMessage }\n\t| { readonly type: \"thinking_level_change\"; readonly thinkingLevel: string }\n\t| { readonly type: \"model_change\"; readonly provider: string; readonly modelId: string }\n\t| { readonly type: \"active_tools_change\"; readonly activeToolNames: string[] }\n\t| { readonly type: \"custom\"; readonly customType: string; readonly data?: unknown }\n\t| {\n\t\t\treadonly type: \"custom_message\";\n\t\t\treadonly customType: string;\n\t\t\treadonly content: string | (TextContent | ImageContent)[];\n\t\t\treadonly details?: unknown;\n\t\t\treadonly display: boolean;\n\t  }\n\t| { readonly type: \"label\"; readonly targetId: string; readonly label: string | undefined }\n\t| { readonly type: \"session_info\"; readonly name?: string }\n\t| { readonly type: \"leaf\"; readonly targetId: string | null };\n\ninterface SessionWritePort<TMessage> {\n\tgetStorage(): { setLeafId(targetId: string | null): Promise<void> };\n\tappendMessage(message: TMessage): Promise<unknown>;\n\tappendThinkingLevelChange(thinkingLevel: string): Promise<unknown>;\n\tappendModelChange(provider: string, modelId: string): Promise<unknown>;\n\tappendActiveToolsChange(activeToolNames: string[]): Promise<unknown>;\n\tappendCustomEntry(customType: string, data?: unknown): Promise<unknown>;\n\tappendCustomMessageEntry(\n\t\tcustomType: string,\n\t\tcontent: string | (TextContent | ImageContent)[],\n\t\tdisplay: boolean,\n\t\tdetails?: unknown,\n\t): Promise<unknown>;\n\tappendLabel(targetId: string, label: string | undefined): Promise<unknown>;\n\tappendSessionName(name: string): Promise<unknown>;\n\tmoveTo(targetId: string | null): Promise<unknown>;\n}\n\n/** A queued write tagged with the monotonic order in which it was accepted. */\ninterface SequencedSessionWrite<TMessage> {\n\treadonly sequence: number;\n\treadonly write: QueuedSessionWrite<TMessage>;\n}\n\n/**\n * Owns ordered pending writes and serializes coordinator-routed persistence.\n *\n * Persistence follows *acceptance* order, not the queue contents observed when\n * a boundary finally runs. Each boundary captures a watermark at invocation\n * time and drains only writes accepted at or before it, so a write enqueued\n * after an idle boundary was reserved can never overtake it.\n */\nexport class SessionWriteCoordinator<TMessage> {\n\tprivate readonly pendingWrites: SequencedSessionWrite<TMessage>[] = [];\n\tprivate nextSequence = 1;\n\tprivate operationTail?: Promise<void>;\n\tprivate invokingOperation = false;\n\tprivate readonly session: SessionWritePort<TMessage>;\n\n\tconstructor(session: SessionWritePort<TMessage>) {\n\t\tthis.session = session;\n\t}\n\n\tenqueue(write: QueuedSessionWrite<TMessage>): void {\n\t\tthis.pendingWrites.push({ sequence: this.nextSequence++, write: createImmutableSnapshot(write) });\n\t}\n\n\thasPending(): boolean {\n\t\treturn this.pendingWrites.length > 0;\n\t}\n\n\tsnapshot(): readonly QueuedSessionWrite<TMessage>[] {\n\t\t// Each queued write was frozen on acceptance, so exposing them needs no clone.\n\t\treturn Object.freeze(this.pendingWrites.map((entry) => entry.write));\n\t}\n\n\tasync flush(): Promise<void> {\n\t\tconst acceptedThrough = this.nextSequence - 1;\n\t\tawait this.serialize(async () => await this.flushPendingThrough(acceptedThrough));\n\t}\n\n\tasync persistAfterPending(write: QueuedSessionWrite<TMessage>): Promise<void> {\n\t\tconst snapshot = createImmutableSnapshot(write);\n\t\t// Reserve the boundary now: only writes already accepted precede this one.\n\t\tconst acceptedThrough = this.nextSequence - 1;\n\t\tawait this.serialize(async () => {\n\t\t\tawait this.flushPendingThrough(acceptedThrough);\n\t\t\tawait this.persistIdleWrite(snapshot);\n\t\t});\n\t}\n\n\t/** Drains queued writes up to `acceptedThrough`; a failed head stays at the head. */\n\tprivate async flushPendingThrough(acceptedThrough: number): Promise<void> {\n\t\twhile (this.pendingWrites.length > 0) {\n\t\t\tconst head = this.pendingWrites[0];\n\t\t\tif (head === undefined || head.sequence > acceptedThrough) return;\n\t\t\tawait this.persist(head.write);\n\t\t\tthis.pendingWrites.shift();\n\t\t}\n\t}\n\n\t/** Idle leaf moves keep the summarizing `Session.moveTo()` path. */\n\tprivate async persistIdleWrite(write: QueuedSessionWrite<TMessage>): Promise<void> {\n\t\tif (write.type === \"leaf\") {\n\t\t\tawait this.session.moveTo(write.targetId);\n\t\t\treturn;\n\t\t}\n\t\tawait this.persist(write);\n\t}\n\n\tprivate async persist(write: QueuedSessionWrite<TMessage>): Promise<void> {\n\t\tswitch (write.type) {\n\t\t\tcase \"message\":\n\t\t\t\tawait this.session.appendMessage(write.message);\n\t\t\t\treturn;\n\t\t\tcase \"thinking_level_change\":\n\t\t\t\tawait this.session.appendThinkingLevelChange(write.thinkingLevel);\n\t\t\t\treturn;\n\t\t\tcase \"model_change\":\n\t\t\t\tawait this.session.appendModelChange(write.provider, write.modelId);\n\t\t\t\treturn;\n\t\t\tcase \"active_tools_change\":\n\t\t\t\tawait this.session.appendActiveToolsChange([...write.activeToolNames]);\n\t\t\t\treturn;\n\t\t\tcase \"custom\":\n\t\t\t\tawait this.session.appendCustomEntry(write.customType, write.data);\n\t\t\t\treturn;\n\t\t\tcase \"custom_message\":\n\t\t\t\tawait this.session.appendCustomMessageEntry(\n\t\t\t\t\twrite.customType,\n\t\t\t\t\ttypeof write.content === \"string\" ? write.content : [...write.content],\n\t\t\t\t\twrite.display,\n\t\t\t\t\twrite.details,\n\t\t\t\t);\n\t\t\t\treturn;\n\t\t\tcase \"label\":\n\t\t\t\tawait this.session.appendLabel(write.targetId, write.label);\n\t\t\t\treturn;\n\t\t\tcase \"session_info\":\n\t\t\t\tawait this.session.appendSessionName(write.name ?? \"\");\n\t\t\t\treturn;\n\t\t\tcase \"leaf\":\n\t\t\t\tawait this.session.getStorage().setLeafId(write.targetId);\n\t\t\t\treturn;\n\t\t\tdefault: {\n\t\t\t\tconst unsupportedWrite: never = write;\n\t\t\t\tthrow new AgentHarnessError(\n\t\t\t\t\t\"invalid_state\",\n\t\t\t\t\t`Unsupported pending session write: ${String(unsupportedWrite)}`,\n\t\t\t\t);\n\t\t\t}\n\t\t}\n\t}\n\n\tprivate serialize(operation: () => Promise<void>): Promise<void> {\n\t\tif (this.invokingOperation) {\n\t\t\tthrow new AgentHarnessError(\"invalid_state\", \"Session persistence cannot synchronously reenter itself\");\n\t\t}\n\t\tconst previous = this.operationTail;\n\t\tlet releaseTail = (): void => undefined;\n\t\tconst tail = new Promise<void>((resolve) => {\n\t\t\treleaseTail = resolve;\n\t\t});\n\t\tthis.operationTail = tail;\n\t\tconst invoke = (): Promise<void> => {\n\t\t\tthis.invokingOperation = true;\n\t\t\ttry {\n\t\t\t\treturn operation();\n\t\t\t} finally {\n\t\t\t\tthis.invokingOperation = false;\n\t\t\t}\n\t\t};\n\t\tconst next = previous ? previous.then(invoke) : invoke();\n\t\tconst release = (): void => {\n\t\t\treleaseTail();\n\t\t\tif (this.operationTail === tail) this.operationTail = undefined;\n\t\t};\n\t\t// Keep the serialization tail usable after a caller observes a failed write.\n\t\tvoid next.then(release, release);\n\t\treturn next;\n\t}\n}\n"]}

package/dist/harness/session-write-coordinator.js

@@ -0,0 +1,126 @@
+import { createImmutableSnapshot } from "../plain-data.js";
+import { AgentHarnessError } from "./errors.js";
+/**
+ * Owns ordered pending writes and serializes coordinator-routed persistence.
+ *
+ * Persistence follows *acceptance* order, not the queue contents observed when
+ * a boundary finally runs. Each boundary captures a watermark at invocation
+ * time and drains only writes accepted at or before it, so a write enqueued
+ * after an idle boundary was reserved can never overtake it.
+ */
+export class SessionWriteCoordinator {
+    pendingWrites = [];
+    nextSequence = 1;
+    operationTail;
+    invokingOperation = false;
+    session;
+    constructor(session) {
+        this.session = session;
+    }
+    enqueue(write) {
+        this.pendingWrites.push({ sequence: this.nextSequence++, write: createImmutableSnapshot(write) });
+    }
+    hasPending() {
+        return this.pendingWrites.length > 0;
+    }
+    snapshot() {
+        // Each queued write was frozen on acceptance, so exposing them needs no clone.
+        return Object.freeze(this.pendingWrites.map((entry) => entry.write));
+    }
+    async flush() {
+        const acceptedThrough = this.nextSequence - 1;
+        await this.serialize(async () => await this.flushPendingThrough(acceptedThrough));
+    }
+    async persistAfterPending(write) {
+        const snapshot = createImmutableSnapshot(write);
+        // Reserve the boundary now: only writes already accepted precede this one.
+        const acceptedThrough = this.nextSequence - 1;
+        await this.serialize(async () => {
+            await this.flushPendingThrough(acceptedThrough);
+            await this.persistIdleWrite(snapshot);
+        });
+    }
+    /** Drains queued writes up to `acceptedThrough`; a failed head stays at the head. */
+    async flushPendingThrough(acceptedThrough) {
+        while (this.pendingWrites.length > 0) {
+            const head = this.pendingWrites[0];
+            if (head === undefined || head.sequence > acceptedThrough)
+                return;
+            await this.persist(head.write);
+            this.pendingWrites.shift();
+        }
+    }
+    /** Idle leaf moves keep the summarizing `Session.moveTo()` path. */
+    async persistIdleWrite(write) {
+        if (write.type === "leaf") {
+            await this.session.moveTo(write.targetId);
+            return;
+        }
+        await this.persist(write);
+    }
+    async persist(write) {
+        switch (write.type) {
+            case "message":
+                await this.session.appendMessage(write.message);
+                return;
+            case "thinking_level_change":
+                await this.session.appendThinkingLevelChange(write.thinkingLevel);
+                return;
+            case "model_change":
+                await this.session.appendModelChange(write.provider, write.modelId);
+                return;
+            case "active_tools_change":
+                await this.session.appendActiveToolsChange([...write.activeToolNames]);
+                return;
+            case "custom":
+                await this.session.appendCustomEntry(write.customType, write.data);
+                return;
+            case "custom_message":
+                await this.session.appendCustomMessageEntry(write.customType, typeof write.content === "string" ? write.content : [...write.content], write.display, write.details);
+                return;
+            case "label":
+                await this.session.appendLabel(write.targetId, write.label);
+                return;
+            case "session_info":
+                await this.session.appendSessionName(write.name ?? "");
+                return;
+            case "leaf":
+                await this.session.getStorage().setLeafId(write.targetId);
+                return;
+            default: {
+                const unsupportedWrite = write;
+                throw new AgentHarnessError("invalid_state", `Unsupported pending session write: ${String(unsupportedWrite)}`);
+            }
+        }
+    }
+    serialize(operation) {
+        if (this.invokingOperation) {
+            throw new AgentHarnessError("invalid_state", "Session persistence cannot synchronously reenter itself");
+        }
+        const previous = this.operationTail;
+        let releaseTail = () => undefined;
+        const tail = new Promise((resolve) => {
+            releaseTail = resolve;
+        });
+        this.operationTail = tail;
+        const invoke = () => {
+            this.invokingOperation = true;
+            try {
+                return operation();
+            }
+            finally {
+                this.invokingOperation = false;
+            }
+        };
+        const next = previous ? previous.then(invoke) : invoke();
+        const release = () => {
+            releaseTail();
+            if (this.operationTail === tail)
+                this.operationTail = undefined;
+        };
+        // Keep the serialization tail usable after a caller observes a failed write.
+        void next.then(release, release);
+        return next;
+    }
+}
+//# sourceMappingURL=session-write-coordinator.js.map

package/dist/harness/session-write-coordinator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-write-coordinator.js","sourceRoot":"","sources":["../../src/harness/session-write-coordinator.ts"],"names":[],"mappings":"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","sourcesContent":["import type { ImageContent, TextContent } from \"omk-ai\";\nimport { createImmutableSnapshot } from \"../plain-data.ts\";\nimport { AgentHarnessError } from \"./errors.ts\";\n\nexport type QueuedSessionWrite<TMessage> =\n\t| { readonly type: \"message\"; readonly message: TMessage }\n\t| { readonly type: \"thinking_level_change\"; readonly thinkingLevel: string }\n\t| { readonly type: \"model_change\"; readonly provider: string; readonly modelId: string }\n\t| { readonly type: \"active_tools_change\"; readonly activeToolNames: string[] }\n\t| { readonly type: \"custom\"; readonly customType: string; readonly data?: unknown }\n\t| {\n\t\t\treadonly type: \"custom_message\";\n\t\t\treadonly customType: string;\n\t\t\treadonly content: string | (TextContent | ImageContent)[];\n\t\t\treadonly details?: unknown;\n\t\t\treadonly display: boolean;\n\t  }\n\t| { readonly type: \"label\"; readonly targetId: string; readonly label: string | undefined }\n\t| { readonly type: \"session_info\"; readonly name?: string }\n\t| { readonly type: \"leaf\"; readonly targetId: string | null };\n\ninterface SessionWritePort<TMessage> {\n\tgetStorage(): { setLeafId(targetId: string | null): Promise<void> };\n\tappendMessage(message: TMessage): Promise<unknown>;\n\tappendThinkingLevelChange(thinkingLevel: string): Promise<unknown>;\n\tappendModelChange(provider: string, modelId: string): Promise<unknown>;\n\tappendActiveToolsChange(activeToolNames: string[]): Promise<unknown>;\n\tappendCustomEntry(customType: string, data?: unknown): Promise<unknown>;\n\tappendCustomMessageEntry(\n\t\tcustomType: string,\n\t\tcontent: string | (TextContent | ImageContent)[],\n\t\tdisplay: boolean,\n\t\tdetails?: unknown,\n\t): Promise<unknown>;\n\tappendLabel(targetId: string, label: string | undefined): Promise<unknown>;\n\tappendSessionName(name: string): Promise<unknown>;\n\tmoveTo(targetId: string | null): Promise<unknown>;\n}\n\n/** A queued write tagged with the monotonic order in which it was accepted. */\ninterface SequencedSessionWrite<TMessage> {\n\treadonly sequence: number;\n\treadonly write: QueuedSessionWrite<TMessage>;\n}\n\n/**\n * Owns ordered pending writes and serializes coordinator-routed persistence.\n *\n * Persistence follows *acceptance* order, not the queue contents observed when\n * a boundary finally runs. Each boundary captures a watermark at invocation\n * time and drains only writes accepted at or before it, so a write enqueued\n * after an idle boundary was reserved can never overtake it.\n */\nexport class SessionWriteCoordinator<TMessage> {\n\tprivate readonly pendingWrites: SequencedSessionWrite<TMessage>[] = [];\n\tprivate nextSequence = 1;\n\tprivate operationTail?: Promise<void>;\n\tprivate invokingOperation = false;\n\tprivate readonly session: SessionWritePort<TMessage>;\n\n\tconstructor(session: SessionWritePort<TMessage>) {\n\t\tthis.session = session;\n\t}\n\n\tenqueue(write: QueuedSessionWrite<TMessage>): void {\n\t\tthis.pendingWrites.push({ sequence: this.nextSequence++, write: createImmutableSnapshot(write) });\n\t}\n\n\thasPending(): boolean {\n\t\treturn this.pendingWrites.length > 0;\n\t}\n\n\tsnapshot(): readonly QueuedSessionWrite<TMessage>[] {\n\t\t// Each queued write was frozen on acceptance, so exposing them needs no clone.\n\t\treturn Object.freeze(this.pendingWrites.map((entry) => entry.write));\n\t}\n\n\tasync flush(): Promise<void> {\n\t\tconst acceptedThrough = this.nextSequence - 1;\n\t\tawait this.serialize(async () => await this.flushPendingThrough(acceptedThrough));\n\t}\n\n\tasync persistAfterPending(write: QueuedSessionWrite<TMessage>): Promise<void> {\n\t\tconst snapshot = createImmutableSnapshot(write);\n\t\t// Reserve the boundary now: only writes already accepted precede this one.\n\t\tconst acceptedThrough = this.nextSequence - 1;\n\t\tawait this.serialize(async () => {\n\t\t\tawait this.flushPendingThrough(acceptedThrough);\n\t\t\tawait this.persistIdleWrite(snapshot);\n\t\t});\n\t}\n\n\t/** Drains queued writes up to `acceptedThrough`; a failed head stays at the head. */\n\tprivate async flushPendingThrough(acceptedThrough: number): Promise<void> {\n\t\twhile (this.pendingWrites.length > 0) {\n\t\t\tconst head = this.pendingWrites[0];\n\t\t\tif (head === undefined || head.sequence > acceptedThrough) return;\n\t\t\tawait this.persist(head.write);\n\t\t\tthis.pendingWrites.shift();\n\t\t}\n\t}\n\n\t/** Idle leaf moves keep the summarizing `Session.moveTo()` path. */\n\tprivate async persistIdleWrite(write: QueuedSessionWrite<TMessage>): Promise<void> {\n\t\tif (write.type === \"leaf\") {\n\t\t\tawait this.session.moveTo(write.targetId);\n\t\t\treturn;\n\t\t}\n\t\tawait this.persist(write);\n\t}\n\n\tprivate async persist(write: QueuedSessionWrite<TMessage>): Promise<void> {\n\t\tswitch (write.type) {\n\t\t\tcase \"message\":\n\t\t\t\tawait this.session.appendMessage(write.message);\n\t\t\t\treturn;\n\t\t\tcase \"thinking_level_change\":\n\t\t\t\tawait this.session.appendThinkingLevelChange(write.thinkingLevel);\n\t\t\t\treturn;\n\t\t\tcase \"model_change\":\n\t\t\t\tawait this.session.appendModelChange(write.provider, write.modelId);\n\t\t\t\treturn;\n\t\t\tcase \"active_tools_change\":\n\t\t\t\tawait this.session.appendActiveToolsChange([...write.activeToolNames]);\n\t\t\t\treturn;\n\t\t\tcase \"custom\":\n\t\t\t\tawait this.session.appendCustomEntry(write.customType, write.data);\n\t\t\t\treturn;\n\t\t\tcase \"custom_message\":\n\t\t\t\tawait this.session.appendCustomMessageEntry(\n\t\t\t\t\twrite.customType,\n\t\t\t\t\ttypeof write.content === \"string\" ? write.content : [...write.content],\n\t\t\t\t\twrite.display,\n\t\t\t\t\twrite.details,\n\t\t\t\t);\n\t\t\t\treturn;\n\t\t\tcase \"label\":\n\t\t\t\tawait this.session.appendLabel(write.targetId, write.label);\n\t\t\t\treturn;\n\t\t\tcase \"session_info\":\n\t\t\t\tawait this.session.appendSessionName(write.name ?? \"\");\n\t\t\t\treturn;\n\t\t\tcase \"leaf\":\n\t\t\t\tawait this.session.getStorage().setLeafId(write.targetId);\n\t\t\t\treturn;\n\t\t\tdefault: {\n\t\t\t\tconst unsupportedWrite: never = write;\n\t\t\t\tthrow new AgentHarnessError(\n\t\t\t\t\t\"invalid_state\",\n\t\t\t\t\t`Unsupported pending session write: ${String(unsupportedWrite)}`,\n\t\t\t\t);\n\t\t\t}\n\t\t}\n\t}\n\n\tprivate serialize(operation: () => Promise<void>): Promise<void> {\n\t\tif (this.invokingOperation) {\n\t\t\tthrow new AgentHarnessError(\"invalid_state\", \"Session persistence cannot synchronously reenter itself\");\n\t\t}\n\t\tconst previous = this.operationTail;\n\t\tlet releaseTail = (): void => undefined;\n\t\tconst tail = new Promise<void>((resolve) => {\n\t\t\treleaseTail = resolve;\n\t\t});\n\t\tthis.operationTail = tail;\n\t\tconst invoke = (): Promise<void> => {\n\t\t\tthis.invokingOperation = true;\n\t\t\ttry {\n\t\t\t\treturn operation();\n\t\t\t} finally {\n\t\t\t\tthis.invokingOperation = false;\n\t\t\t}\n\t\t};\n\t\tconst next = previous ? previous.then(invoke) : invoke();\n\t\tconst release = (): void => {\n\t\t\treleaseTail();\n\t\t\tif (this.operationTail === tail) this.operationTail = undefined;\n\t\t};\n\t\t// Keep the serialization tail usable after a caller observes a failed write.\n\t\tvoid next.then(release, release);\n\t\treturn next;\n\t}\n}\n"]}

package/dist/harness/subscriber-fanout.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Subscriber fan-out with a self-wait barrier, extracted from `AgentHarness`.
+ *
+ * A listener that awaits the end of the very operation whose emission it is
+ * blocking forms a cycle. The call that closes that cycle (`waitForIdle()`,
+ * `abort()`) is always made during the listener's *synchronous* prologue — an
+ * async function body runs synchronously up to its first `await` — so marking
+ * just that window identifies callback-originated waits exactly, without
+ * falsely rejecting an unrelated concurrent caller that runs later while the
+ * listener's promise is merely pending.
+ *
+ * This module imports no harness or session types so it stays a leaf for the
+ * import-cycle ratchet; the harness passes the current operation id in.
+ */
+export type SubscriberListener<TEvent> = (event: TEvent, signal?: AbortSignal) => Promise<void> | void;
+export declare class SubscriberFanout<TEvent extends {
+    readonly type: string;
+}> {
+    private readonly listeners;
+    /** Non-zero only while a subscriber's synchronous prologue is on the stack. */
+    private syncFrameDepth;
+    private operationId;
+    private eventType;
+    subscribe(listener: SubscriberListener<TEvent>): () => void;
+    /** Deliver `event` to every subscriber in order; a throwing subscriber fails the emission as `hook`. */
+    emit(event: TEvent, currentOperationId: string | undefined, signal?: AbortSignal): Promise<void>;
+    /**
+     * Fail closed when an awaited listener tries to wait on its own operation.
+     * Rejecting immediately turns a permanent deadlock into a classified error.
+     *
+     * Scope: this catches a wait issued from the listener's synchronous prologue,
+     * which covers `await harness.waitForIdle()` / `await harness.abort()`. A wait
+     * deferred behind an unrelated `await` inside the listener is not detected.
+     */
+    assertNotSelfWait(api: string, currentOperationId: string | undefined): void;
+}
+//# sourceMappingURL=subscriber-fanout.d.ts.map

package/dist/harness/subscriber-fanout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscriber-fanout.d.ts","sourceRoot":"","sources":["../../src/harness/subscriber-fanout.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH,MAAM,MAAM,kBAAkB,CAAC,MAAM,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAEvG,qBAAa,gBAAgB,CAAC,MAAM,SAAS;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE;IACrE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAyC;IACnE,+EAA+E;IAC/E,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,WAAW,CAAqB;IACxC,OAAO,CAAC,SAAS,CAAqB;IAEtC,SAAS,CAAC,QAAQ,EAAE,kBAAkB,CAAC,MAAM,CAAC,GAAG,MAAM,IAAI,CAG1D;IAED,wGAAwG;IAClG,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,kBAAkB,EAAE,MAAM,GAAG,SAAS,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CA0BrG;IAED;;;;;;;OAOG;IACH,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,kBAAkB,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAO3E;CACD","sourcesContent":["/**\n * Subscriber fan-out with a self-wait barrier, extracted from `AgentHarness`.\n *\n * A listener that awaits the end of the very operation whose emission it is\n * blocking forms a cycle. The call that closes that cycle (`waitForIdle()`,\n * `abort()`) is always made during the listener's *synchronous* prologue — an\n * async function body runs synchronously up to its first `await` — so marking\n * just that window identifies callback-originated waits exactly, without\n * falsely rejecting an unrelated concurrent caller that runs later while the\n * listener's promise is merely pending.\n *\n * This module imports no harness or session types so it stays a leaf for the\n * import-cycle ratchet; the harness passes the current operation id in.\n */\n\nimport { AgentHarnessError } from \"./errors.ts\";\nimport { normalizeHarnessError } from \"./operation-outcome.ts\";\n\nexport type SubscriberListener<TEvent> = (event: TEvent, signal?: AbortSignal) => Promise<void> | void;\n\nexport class SubscriberFanout<TEvent extends { readonly type: string }> {\n\tprivate readonly listeners = new Set<SubscriberListener<TEvent>>();\n\t/** Non-zero only while a subscriber's synchronous prologue is on the stack. */\n\tprivate syncFrameDepth = 0;\n\tprivate operationId: string | undefined;\n\tprivate eventType: string | undefined;\n\n\tsubscribe(listener: SubscriberListener<TEvent>): () => void {\n\t\tthis.listeners.add(listener);\n\t\treturn () => this.listeners.delete(listener);\n\t}\n\n\t/** Deliver `event` to every subscriber in order; a throwing subscriber fails the emission as `hook`. */\n\tasync emit(event: TEvent, currentOperationId: string | undefined, signal?: AbortSignal): Promise<void> {\n\t\tfor (const listener of this.listeners) {\n\t\t\tconst previousOperationId = this.operationId;\n\t\t\tconst previousEventType = this.eventType;\n\t\t\tthis.operationId = currentOperationId;\n\t\t\tthis.eventType = event.type;\n\t\t\tlet pending: Promise<unknown> | unknown;\n\t\t\tthis.syncFrameDepth += 1;\n\t\t\ttry {\n\t\t\t\tpending = listener(event, signal);\n\t\t\t} catch (error) {\n\t\t\t\tthis.operationId = previousOperationId;\n\t\t\t\tthis.eventType = previousEventType;\n\t\t\t\tthrow normalizeHarnessError(error, \"hook\");\n\t\t\t} finally {\n\t\t\t\tthis.syncFrameDepth -= 1;\n\t\t\t}\n\t\t\ttry {\n\t\t\t\tawait pending;\n\t\t\t} catch (error) {\n\t\t\t\tthrow normalizeHarnessError(error, \"hook\");\n\t\t\t} finally {\n\t\t\t\tthis.operationId = previousOperationId;\n\t\t\t\tthis.eventType = previousEventType;\n\t\t\t}\n\t\t}\n\t}\n\n\t/**\n\t * Fail closed when an awaited listener tries to wait on its own operation.\n\t * Rejecting immediately turns a permanent deadlock into a classified error.\n\t *\n\t * Scope: this catches a wait issued from the listener's synchronous prologue,\n\t * which covers `await harness.waitForIdle()` / `await harness.abort()`. A wait\n\t * deferred behind an unrelated `await` inside the listener is not detected.\n\t */\n\tassertNotSelfWait(api: string, currentOperationId: string | undefined): void {\n\t\tif (this.syncFrameDepth > 0 && currentOperationId !== undefined && currentOperationId === this.operationId) {\n\t\t\tthrow new AgentHarnessError(\n\t\t\t\t\"invalid_state\",\n\t\t\t\t`${api} cannot await the current operation from an awaited ${this.eventType ?? \"unknown\"} callback`,\n\t\t\t);\n\t\t}\n\t}\n}\n"]}

package/dist/harness/subscriber-fanout.js

@@ -0,0 +1,73 @@
+/**
+ * Subscriber fan-out with a self-wait barrier, extracted from `AgentHarness`.
+ *
+ * A listener that awaits the end of the very operation whose emission it is
+ * blocking forms a cycle. The call that closes that cycle (`waitForIdle()`,
+ * `abort()`) is always made during the listener's *synchronous* prologue — an
+ * async function body runs synchronously up to its first `await` — so marking
+ * just that window identifies callback-originated waits exactly, without
+ * falsely rejecting an unrelated concurrent caller that runs later while the
+ * listener's promise is merely pending.
+ *
+ * This module imports no harness or session types so it stays a leaf for the
+ * import-cycle ratchet; the harness passes the current operation id in.
+ */
+import { AgentHarnessError } from "./errors.js";
+import { normalizeHarnessError } from "./operation-outcome.js";
+export class SubscriberFanout {
+    listeners = new Set();
+    /** Non-zero only while a subscriber's synchronous prologue is on the stack. */
+    syncFrameDepth = 0;
+    operationId;
+    eventType;
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    /** Deliver `event` to every subscriber in order; a throwing subscriber fails the emission as `hook`. */
+    async emit(event, currentOperationId, signal) {
+        for (const listener of this.listeners) {
+            const previousOperationId = this.operationId;
+            const previousEventType = this.eventType;
+            this.operationId = currentOperationId;
+            this.eventType = event.type;
+            let pending;
+            this.syncFrameDepth += 1;
+            try {
+                pending = listener(event, signal);
+            }
+            catch (error) {
+                this.operationId = previousOperationId;
+                this.eventType = previousEventType;
+                throw normalizeHarnessError(error, "hook");
+            }
+            finally {
+                this.syncFrameDepth -= 1;
+            }
+            try {
+                await pending;
+            }
+            catch (error) {
+                throw normalizeHarnessError(error, "hook");
+            }
+            finally {
+                this.operationId = previousOperationId;
+                this.eventType = previousEventType;
+            }
+        }
+    }
+    /**
+     * Fail closed when an awaited listener tries to wait on its own operation.
+     * Rejecting immediately turns a permanent deadlock into a classified error.
+     *
+     * Scope: this catches a wait issued from the listener's synchronous prologue,
+     * which covers `await harness.waitForIdle()` / `await harness.abort()`. A wait
+     * deferred behind an unrelated `await` inside the listener is not detected.
+     */
+    assertNotSelfWait(api, currentOperationId) {
+        if (this.syncFrameDepth > 0 && currentOperationId !== undefined && currentOperationId === this.operationId) {
+            throw new AgentHarnessError("invalid_state", `${api} cannot await the current operation from an awaited ${this.eventType ?? "unknown"} callback`);
+        }
+    }
+}
+//# sourceMappingURL=subscriber-fanout.js.map

package/dist/harness/subscriber-fanout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscriber-fanout.js","sourceRoot":"","sources":["../../src/harness/subscriber-fanout.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAI/D,MAAM,OAAO,gBAAgB;IACX,SAAS,GAAG,IAAI,GAAG,EAA8B,CAAC;IACnE,+EAA+E;IACvE,cAAc,GAAG,CAAC,CAAC;IACnB,WAAW,CAAqB;IAChC,SAAS,CAAqB;IAEtC,SAAS,CAAC,QAAoC,EAAc;QAC3D,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC7B,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAAA,CAC7C;IAED,wGAAwG;IACxG,KAAK,CAAC,IAAI,CAAC,KAAa,EAAE,kBAAsC,EAAE,MAAoB,EAAiB;QACtG,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACvC,MAAM,mBAAmB,GAAG,IAAI,CAAC,WAAW,CAAC;YAC7C,MAAM,iBAAiB,GAAG,IAAI,CAAC,SAAS,CAAC;YACzC,IAAI,CAAC,WAAW,GAAG,kBAAkB,CAAC;YACtC,IAAI,CAAC,SAAS,GAAG,KAAK,CAAC,IAAI,CAAC;YAC5B,IAAI,OAAmC,CAAC;YACxC,IAAI,CAAC,cAAc,IAAI,CAAC,CAAC;YACzB,IAAI,CAAC;gBACJ,OAAO,GAAG,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;YACnC,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBAChB,IAAI,CAAC,WAAW,GAAG,mBAAmB,CAAC;gBACvC,IAAI,CAAC,SAAS,GAAG,iBAAiB,CAAC;gBACnC,MAAM,qBAAqB,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;YAC5C,CAAC;oBAAS,CAAC;gBACV,IAAI,CAAC,cAAc,IAAI,CAAC,CAAC;YAC1B,CAAC;YACD,IAAI,CAAC;gBACJ,MAAM,OAAO,CAAC;YACf,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBAChB,MAAM,qBAAqB,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;YAC5C,CAAC;oBAAS,CAAC;gBACV,IAAI,CAAC,WAAW,GAAG,mBAAmB,CAAC;gBACvC,IAAI,CAAC,SAAS,GAAG,iBAAiB,CAAC;YACpC,CAAC;QACF,CAAC;IAAA,CACD;IAED;;;;;;;OAOG;IACH,iBAAiB,CAAC,GAAW,EAAE,kBAAsC,EAAQ;QAC5E,IAAI,IAAI,CAAC,cAAc,GAAG,CAAC,IAAI,kBAAkB,KAAK,SAAS,IAAI,kBAAkB,KAAK,IAAI,CAAC,WAAW,EAAE,CAAC;YAC5G,MAAM,IAAI,iBAAiB,CAC1B,eAAe,EACf,GAAG,GAAG,uDAAuD,IAAI,CAAC,SAAS,IAAI,SAAS,WAAW,CACnG,CAAC;QACH,CAAC;IAAA,CACD;CACD","sourcesContent":["/**\n * Subscriber fan-out with a self-wait barrier, extracted from `AgentHarness`.\n *\n * A listener that awaits the end of the very operation whose emission it is\n * blocking forms a cycle. The call that closes that cycle (`waitForIdle()`,\n * `abort()`) is always made during the listener's *synchronous* prologue — an\n * async function body runs synchronously up to its first `await` — so marking\n * just that window identifies callback-originated waits exactly, without\n * falsely rejecting an unrelated concurrent caller that runs later while the\n * listener's promise is merely pending.\n *\n * This module imports no harness or session types so it stays a leaf for the\n * import-cycle ratchet; the harness passes the current operation id in.\n */\n\nimport { AgentHarnessError } from \"./errors.ts\";\nimport { normalizeHarnessError } from \"./operation-outcome.ts\";\n\nexport type SubscriberListener<TEvent> = (event: TEvent, signal?: AbortSignal) => Promise<void> | void;\n\nexport class SubscriberFanout<TEvent extends { readonly type: string }> {\n\tprivate readonly listeners = new Set<SubscriberListener<TEvent>>();\n\t/** Non-zero only while a subscriber's synchronous prologue is on the stack. */\n\tprivate syncFrameDepth = 0;\n\tprivate operationId: string | undefined;\n\tprivate eventType: string | undefined;\n\n\tsubscribe(listener: SubscriberListener<TEvent>): () => void {\n\t\tthis.listeners.add(listener);\n\t\treturn () => this.listeners.delete(listener);\n\t}\n\n\t/** Deliver `event` to every subscriber in order; a throwing subscriber fails the emission as `hook`. */\n\tasync emit(event: TEvent, currentOperationId: string | undefined, signal?: AbortSignal): Promise<void> {\n\t\tfor (const listener of this.listeners) {\n\t\t\tconst previousOperationId = this.operationId;\n\t\t\tconst previousEventType = this.eventType;\n\t\t\tthis.operationId = currentOperationId;\n\t\t\tthis.eventType = event.type;\n\t\t\tlet pending: Promise<unknown> | unknown;\n\t\t\tthis.syncFrameDepth += 1;\n\t\t\ttry {\n\t\t\t\tpending = listener(event, signal);\n\t\t\t} catch (error) {\n\t\t\t\tthis.operationId = previousOperationId;\n\t\t\t\tthis.eventType = previousEventType;\n\t\t\t\tthrow normalizeHarnessError(error, \"hook\");\n\t\t\t} finally {\n\t\t\t\tthis.syncFrameDepth -= 1;\n\t\t\t}\n\t\t\ttry {\n\t\t\t\tawait pending;\n\t\t\t} catch (error) {\n\t\t\t\tthrow normalizeHarnessError(error, \"hook\");\n\t\t\t} finally {\n\t\t\t\tthis.operationId = previousOperationId;\n\t\t\t\tthis.eventType = previousEventType;\n\t\t\t}\n\t\t}\n\t}\n\n\t/**\n\t * Fail closed when an awaited listener tries to wait on its own operation.\n\t * Rejecting immediately turns a permanent deadlock into a classified error.\n\t *\n\t * Scope: this catches a wait issued from the listener's synchronous prologue,\n\t * which covers `await harness.waitForIdle()` / `await harness.abort()`. A wait\n\t * deferred behind an unrelated `await` inside the listener is not detected.\n\t */\n\tassertNotSelfWait(api: string, currentOperationId: string | undefined): void {\n\t\tif (this.syncFrameDepth > 0 && currentOperationId !== undefined && currentOperationId === this.operationId) {\n\t\t\tthrow new AgentHarnessError(\n\t\t\t\t\"invalid_state\",\n\t\t\t\t`${api} cannot await the current operation from an awaited ${this.eventType ?? \"unknown\"} callback`,\n\t\t\t);\n\t\t}\n\t}\n}\n"]}

package/dist/harness/tree-navigation.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Tree-navigation helpers extracted from `AgentHarness.navigateTree`.
+ *
+ * These cover the two self-contained steps of a navigation — deciding where to
+ * land, and producing a branch summary — so the harness method is left with
+ * lifecycle staging, hook dispatch, and the session commit.
+ */
+import type { Model, RetryPolicy } from "omk-ai";
+import { type SummarizationRetryEvent } from "./summarization-retry.ts";
+import type { SessionTreeEntry } from "./types.ts";
+export interface NavigationTarget {
+    /** Leaf the session should move to. */
+    readonly newLeafId: string | null;
+    /** Original text of a user-authored target, handed back for re-editing. */
+    readonly editorText?: string;
+}
+/**
+ * Where a navigation lands. Targeting a user-authored entry rewinds to its
+ * parent and returns that entry's text, so the caller can edit and resend it;
+ * any other entry is entered directly.
+ */
+export declare function resolveNavigationTarget(targetEntry: SessionTreeEntry, targetId: string): NavigationTarget;
+export type BranchSummaryOutcome = {
+    readonly cancelled: true;
+} | {
+    readonly cancelled: false;
+    readonly summary: string;
+    readonly details: unknown;
+};
+/**
+ * Summarize the entries being navigated away from. An aborted summary is a
+ * cancellation, not a failure; every other summarization error is classified
+ * as `branch_summary`.
+ */
+export declare function runBranchSummary(input: {
+    readonly entries: SessionTreeEntry[];
+    readonly model: Model<any>;
+    readonly apiKey: string;
+    readonly headers?: Record<string, string>;
+    readonly customInstructions?: string;
+    readonly replaceInstructions?: boolean;
+    readonly summarizationRetry: RetryPolicy | undefined;
+    readonly emit: (event: SummarizationRetryEvent) => Promise<void> | void;
+}): Promise<BranchSummaryOutcome>;
+//# sourceMappingURL=tree-navigation.d.ts.map

package/dist/harness/tree-navigation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree-navigation.d.ts","sourceRoot":"","sources":["../../src/harness/tree-navigation.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAgB,KAAK,EAAE,WAAW,EAAe,MAAM,QAAQ,CAAC;AAE5E,OAAO,EAA4B,KAAK,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AAClG,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAWnD,MAAM,WAAW,gBAAgB;IAChC,uCAAuC;IACvC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,2EAA2E;IAC3E,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,GAAG,gBAAgB,CAQzG;AAED,MAAM,MAAM,oBAAoB,GAC7B;IAAE,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAA;CAAE,GAC5B;IAAE,QAAQ,CAAC,SAAS,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC;AAEtF;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,KAAK,EAAE;IAC7C,QAAQ,CAAC,OAAO,EAAE,gBAAgB,EAAE,CAAC;IACrC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;IACvC,QAAQ,CAAC,kBAAkB,EAAE,WAAW,GAAG,SAAS,CAAC;IACrD,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,uBAAuB,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CACxE,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAmBhC","sourcesContent":["/**\n * Tree-navigation helpers extracted from `AgentHarness.navigateTree`.\n *\n * These cover the two self-contained steps of a navigation — deciding where to\n * land, and producing a branch summary — so the harness method is left with\n * lifecycle staging, hook dispatch, and the session commit.\n */\n\nimport type { ImageContent, Model, RetryPolicy, TextContent } from \"omk-ai\";\nimport { generateBranchSummary } from \"./compaction/branch-summarization.ts\";\nimport { createSummarizationRetry, type SummarizationRetryEvent } from \"./summarization-retry.ts\";\nimport type { SessionTreeEntry } from \"./types.ts\";\nimport { AgentHarnessError } from \"./types.ts\";\n\nfunction flattenText(content: string | (TextContent | ImageContent)[]): string {\n\tif (typeof content === \"string\") return content;\n\treturn content\n\t\t.filter((part): part is TextContent => part.type === \"text\")\n\t\t.map((part) => part.text)\n\t\t.join(\"\");\n}\n\nexport interface NavigationTarget {\n\t/** Leaf the session should move to. */\n\treadonly newLeafId: string | null;\n\t/** Original text of a user-authored target, handed back for re-editing. */\n\treadonly editorText?: string;\n}\n\n/**\n * Where a navigation lands. Targeting a user-authored entry rewinds to its\n * parent and returns that entry's text, so the caller can edit and resend it;\n * any other entry is entered directly.\n */\nexport function resolveNavigationTarget(targetEntry: SessionTreeEntry, targetId: string): NavigationTarget {\n\tif (targetEntry.type === \"message\" && targetEntry.message.role === \"user\") {\n\t\treturn { newLeafId: targetEntry.parentId, editorText: flattenText(targetEntry.message.content) };\n\t}\n\tif (targetEntry.type === \"custom_message\") {\n\t\treturn { newLeafId: targetEntry.parentId, editorText: flattenText(targetEntry.content) };\n\t}\n\treturn { newLeafId: targetId };\n}\n\nexport type BranchSummaryOutcome =\n\t| { readonly cancelled: true }\n\t| { readonly cancelled: false; readonly summary: string; readonly details: unknown };\n\n/**\n * Summarize the entries being navigated away from. An aborted summary is a\n * cancellation, not a failure; every other summarization error is classified\n * as `branch_summary`.\n */\nexport async function runBranchSummary(input: {\n\treadonly entries: SessionTreeEntry[];\n\treadonly model: Model<any>;\n\treadonly apiKey: string;\n\treadonly headers?: Record<string, string>;\n\treadonly customInstructions?: string;\n\treadonly replaceInstructions?: boolean;\n\treadonly summarizationRetry: RetryPolicy | undefined;\n\treadonly emit: (event: SummarizationRetryEvent) => Promise<void> | void;\n}): Promise<BranchSummaryOutcome> {\n\tconst result = await generateBranchSummary(input.entries, {\n\t\tmodel: input.model,\n\t\tapiKey: input.apiKey,\n\t\theaders: input.headers,\n\t\tsignal: new AbortController().signal,\n\t\tcustomInstructions: input.customInstructions,\n\t\treplaceInstructions: input.replaceInstructions,\n\t\t...createSummarizationRetry(\"branch_summary\", input.summarizationRetry, input.emit),\n\t});\n\tif (!result.ok) {\n\t\tif (result.error.code === \"aborted\") return { cancelled: true };\n\t\tthrow new AgentHarnessError(\"branch_summary\", result.error.message, result.error);\n\t}\n\treturn {\n\t\tcancelled: false,\n\t\tsummary: result.value.summary,\n\t\tdetails: { readFiles: result.value.readFiles, modifiedFiles: result.value.modifiedFiles },\n\t};\n}\n"]}