@ai-agent-forge/agent-forge 0.85.0

package/dist/host/overflow-recovery.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Provider overflow recovery (2A.3b) — classifies provider errors, offers a
+ * recovery entry point for context overflow, and keeps the original error
+ * traceable through every outcome.
+ *
+ * Classification is a deterministic pattern table (context overflow,
+ * rate limit, auth, transient, unknown). Only context overflow is
+ * recoverable in this slice; other classes are answered `not_recoverable`
+ * with the classification attached (rate-limit retry belongs to 2A.4).
+ * The recovery path shrinks the payload through a caller callback and
+ * commits via the 2A.1 checkpoint; a failing shrink is a structured
+ * `projection_failed` — and EVERY outcome carries the raw provider error
+ * message, so nothing about the original failure is ever lost. Summary
+ * retry is 2A.4a; tree/branch migration stays out of scope.
+ */
+import type { JsonValue } from "@agent-forge/ai";
+import type { HostCheckpointCoordinatorV1 } from "./checkpoint-commit.ts";
+export type ProviderErrorClassV1 = "context_overflow" | "rate_limit" | "auth" | "transient" | "unknown";
+export interface ProviderErrorClassificationV1 {
+    readonly errorClass: ProviderErrorClassV1;
+    readonly rawMessage: string;
+    readonly rawName: string;
+}
+export type OverflowRecoveryOutcomeV1 = {
+    readonly status: "recovered";
+    readonly revision: number;
+    readonly shrunk: JsonValue;
+} | {
+    readonly status: "not_recoverable";
+    readonly errorClass: ProviderErrorClassV1;
+    readonly rawMessage: string;
+    readonly hint: string;
+} | {
+    readonly status: "projection_failed";
+    readonly errorClass: ProviderErrorClassV1;
+    readonly rawMessage: string;
+    readonly reason: string;
+} | {
+    readonly status: "stale";
+    readonly currentRevision: number;
+    readonly errorClass: ProviderErrorClassV1;
+    readonly rawMessage: string;
+};
+export interface OverflowRecoveryV1 {
+    classify(error: unknown): ProviderErrorClassificationV1;
+    recover(input: {
+        readonly operationId: string;
+        readonly error: unknown;
+        readonly shrink: (classification: ProviderErrorClassificationV1) => JsonValue;
+    }): OverflowRecoveryOutcomeV1;
+}
+export declare function createOverflowRecovery(options: {
+    readonly coordinator: HostCheckpointCoordinatorV1;
+}): OverflowRecoveryV1;
+//# sourceMappingURL=overflow-recovery.d.ts.map

package/dist/host/overflow-recovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"overflow-recovery.d.ts","sourceRoot":"","sources":["../../src/host/overflow-recovery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,wBAAwB,CAAC;AAE1E,MAAM,MAAM,oBAAoB,GAAG,kBAAkB,GAAG,YAAY,GAAG,MAAM,GAAG,WAAW,GAAG,SAAS,CAAC;AAExG,MAAM,WAAW,6BAA6B;IAC7C,QAAQ,CAAC,UAAU,EAAE,oBAAoB,CAAC;IAC1C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,MAAM,yBAAyB,GAClC;IAAE,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAA;CAAE,GACvF;IACA,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IACnC,QAAQ,CAAC,UAAU,EAAE,oBAAoB,CAAC;IAC1C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACrB,GACD;IACA,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAC;IACrC,QAAQ,CAAC,UAAU,EAAE,oBAAoB,CAAC;IAC1C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACvB,GACD;IACA,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,UAAU,EAAE,oBAAoB,CAAC;IAC1C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC3B,CAAC;AAEL,MAAM,WAAW,kBAAkB;IAClC,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,6BAA6B,CAAC;IACxD,OAAO,CAAC,KAAK,EAAE;QACd,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;QAC7B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;QACxB,QAAQ,CAAC,MAAM,EAAE,CAAC,cAAc,EAAE,6BAA6B,KAAK,SAAS,CAAC;KAC9E,GAAG,yBAAyB,CAAC;CAC9B;AAYD,wBAAgB,sBAAsB,CAAC,OAAO,EAAE;IAC/C,QAAQ,CAAC,WAAW,EAAE,2BAA2B,CAAC;CAClD,GAAG,kBAAkB,CAgFrB","sourcesContent":["/**\n * Provider overflow recovery (2A.3b) — classifies provider errors, offers a\n * recovery entry point for context overflow, and keeps the original error\n * traceable through every outcome.\n *\n * Classification is a deterministic pattern table (context overflow,\n * rate limit, auth, transient, unknown). Only context overflow is\n * recoverable in this slice; other classes are answered `not_recoverable`\n * with the classification attached (rate-limit retry belongs to 2A.4).\n * The recovery path shrinks the payload through a caller callback and\n * commits via the 2A.1 checkpoint; a failing shrink is a structured\n * `projection_failed` — and EVERY outcome carries the raw provider error\n * message, so nothing about the original failure is ever lost. Summary\n * retry is 2A.4a; tree/branch migration stays out of scope.\n */\nimport type { JsonValue } from \"@agent-forge/ai\";\nimport type { HostCheckpointCoordinatorV1 } from \"./checkpoint-commit.ts\";\n\nexport type ProviderErrorClassV1 = \"context_overflow\" | \"rate_limit\" | \"auth\" | \"transient\" | \"unknown\";\n\nexport interface ProviderErrorClassificationV1 {\n\treadonly errorClass: ProviderErrorClassV1;\n\treadonly rawMessage: string;\n\treadonly rawName: string;\n}\n\nexport type OverflowRecoveryOutcomeV1 =\n\t| { readonly status: \"recovered\"; readonly revision: number; readonly shrunk: JsonValue }\n\t| {\n\t\t\treadonly status: \"not_recoverable\";\n\t\t\treadonly errorClass: ProviderErrorClassV1;\n\t\t\treadonly rawMessage: string;\n\t\t\treadonly hint: string;\n\t  }\n\t| {\n\t\t\treadonly status: \"projection_failed\";\n\t\t\treadonly errorClass: ProviderErrorClassV1;\n\t\t\treadonly rawMessage: string;\n\t\t\treadonly reason: string;\n\t  }\n\t| {\n\t\t\treadonly status: \"stale\";\n\t\t\treadonly currentRevision: number;\n\t\t\treadonly errorClass: ProviderErrorClassV1;\n\t\t\treadonly rawMessage: string;\n\t  };\n\nexport interface OverflowRecoveryV1 {\n\tclassify(error: unknown): ProviderErrorClassificationV1;\n\trecover(input: {\n\t\treadonly operationId: string;\n\t\treadonly error: unknown;\n\t\treadonly shrink: (classification: ProviderErrorClassificationV1) => JsonValue;\n\t}): OverflowRecoveryOutcomeV1;\n}\n\nconst CLASSIFICATION_TABLE: readonly (readonly [ProviderErrorClassV1, readonly string[]])[] = [\n\t[\n\t\t\"context_overflow\",\n\t\t[\"context length\", \"maximum context\", \"context window\", \"token limit\", \"too many tokens\", \"overflow\"],\n\t],\n\t[\"rate_limit\", [\"rate limit\", \"429\", \"too many requests\"]],\n\t[\"auth\", [\"401\", \"403\", \"unauthorized\", \"forbidden\", \"invalid api key\"]],\n\t[\"transient\", [\"timeout\", \"econnreset\", \"econnrefused\", \"socket hang up\", \"502\", \"503\"]],\n];\n\nexport function createOverflowRecovery(options: {\n\treadonly coordinator: HostCheckpointCoordinatorV1;\n}): OverflowRecoveryV1 {\n\tconst coordinator = options.coordinator;\n\n\tconst classify = (error: unknown): ProviderErrorClassificationV1 => {\n\t\tconst rawName =\n\t\t\terror instanceof Error\n\t\t\t\t? error.name\n\t\t\t\t: typeof error === \"object\" && error !== null && \"name\" in error\n\t\t\t\t\t? String((error as { name: unknown }).name)\n\t\t\t\t\t: \"unknown\";\n\t\tconst rawMessage = error instanceof Error ? error.message : String(error);\n\t\tconst haystack = `${rawName} ${rawMessage}`.toLowerCase();\n\t\tfor (const [errorClass, patterns] of CLASSIFICATION_TABLE) {\n\t\t\tif (patterns.some((pattern) => haystack.includes(pattern))) {\n\t\t\t\treturn { errorClass, rawMessage, rawName };\n\t\t\t}\n\t\t}\n\t\treturn { errorClass: \"unknown\", rawMessage, rawName };\n\t};\n\n\treturn {\n\t\tclassify,\n\t\trecover({ operationId, error, shrink }) {\n\t\t\tconst classification = classify(error);\n\t\t\tif (classification.errorClass !== \"context_overflow\") {\n\t\t\t\treturn {\n\t\t\t\t\tstatus: \"not_recoverable\",\n\t\t\t\t\terrorClass: classification.errorClass,\n\t\t\t\t\trawMessage: classification.rawMessage,\n\t\t\t\t\thint: \"Only context overflow is recoverable here; rate-limit retry belongs to 2A.4\",\n\t\t\t\t};\n\t\t\t}\n\t\t\tconst staged = coordinator.stage({\n\t\t\t\toperationId,\n\t\t\t\texpectedRevision: coordinator.currentRevision,\n\t\t\t\tpayload: null,\n\t\t\t});\n\t\t\tif (staged.status === \"stale\") {\n\t\t\t\treturn {\n\t\t\t\t\tstatus: \"stale\",\n\t\t\t\t\tcurrentRevision: staged.currentRevision,\n\t\t\t\t\terrorClass: classification.errorClass,\n\t\t\t\t\trawMessage: classification.rawMessage,\n\t\t\t\t};\n\t\t\t}\n\t\t\tif (staged.status === \"duplicate\") {\n\t\t\t\treturn { status: \"recovered\", revision: staged.revision, shrunk: { duplicate: true } };\n\t\t\t}\n\t\t\tlet shrunk: JsonValue;\n\t\t\ttry {\n\t\t\t\tshrunk = shrink(classification);\n\t\t\t} catch (shrinkError) {\n\t\t\t\tcoordinator.cancelStage(staged.staged.token);\n\t\t\t\treturn {\n\t\t\t\t\tstatus: \"projection_failed\",\n\t\t\t\t\terrorClass: classification.errorClass,\n\t\t\t\t\trawMessage: classification.rawMessage,\n\t\t\t\t\treason: shrinkError instanceof Error ? shrinkError.message : String(shrinkError),\n\t\t\t\t};\n\t\t\t}\n\t\t\tconst outcome = coordinator.commitStage({ token: staged.staged.token, apply: () => undefined });\n\t\t\tif (outcome.status === \"stale\") {\n\t\t\t\treturn {\n\t\t\t\t\tstatus: \"stale\",\n\t\t\t\t\tcurrentRevision: outcome.currentRevision,\n\t\t\t\t\terrorClass: classification.errorClass,\n\t\t\t\t\trawMessage: classification.rawMessage,\n\t\t\t\t};\n\t\t\t}\n\t\t\tif (outcome.status === \"committed\") {\n\t\t\t\treturn { status: \"recovered\", revision: outcome.revision, shrunk };\n\t\t\t}\n\t\t\treturn {\n\t\t\t\tstatus: \"projection_failed\",\n\t\t\t\terrorClass: classification.errorClass,\n\t\t\t\trawMessage: classification.rawMessage,\n\t\t\t\treason: `Unexpected checkpoint outcome: ${outcome.status}`,\n\t\t\t};\n\t\t},\n\t};\n}\n"]}

package/dist/host/overflow-recovery.js

@@ -0,0 +1,89 @@
+const CLASSIFICATION_TABLE = [
+    [
+        "context_overflow",
+        ["context length", "maximum context", "context window", "token limit", "too many tokens", "overflow"],
+    ],
+    ["rate_limit", ["rate limit", "429", "too many requests"]],
+    ["auth", ["401", "403", "unauthorized", "forbidden", "invalid api key"]],
+    ["transient", ["timeout", "econnreset", "econnrefused", "socket hang up", "502", "503"]],
+];
+export function createOverflowRecovery(options) {
+    const coordinator = options.coordinator;
+    const classify = (error) => {
+        const rawName = error instanceof Error
+            ? error.name
+            : typeof error === "object" && error !== null && "name" in error
+                ? String(error.name)
+                : "unknown";
+        const rawMessage = error instanceof Error ? error.message : String(error);
+        const haystack = `${rawName} ${rawMessage}`.toLowerCase();
+        for (const [errorClass, patterns] of CLASSIFICATION_TABLE) {
+            if (patterns.some((pattern) => haystack.includes(pattern))) {
+                return { errorClass, rawMessage, rawName };
+            }
+        }
+        return { errorClass: "unknown", rawMessage, rawName };
+    };
+    return {
+        classify,
+        recover({ operationId, error, shrink }) {
+            const classification = classify(error);
+            if (classification.errorClass !== "context_overflow") {
+                return {
+                    status: "not_recoverable",
+                    errorClass: classification.errorClass,
+                    rawMessage: classification.rawMessage,
+                    hint: "Only context overflow is recoverable here; rate-limit retry belongs to 2A.4",
+                };
+            }
+            const staged = coordinator.stage({
+                operationId,
+                expectedRevision: coordinator.currentRevision,
+                payload: null,
+            });
+            if (staged.status === "stale") {
+                return {
+                    status: "stale",
+                    currentRevision: staged.currentRevision,
+                    errorClass: classification.errorClass,
+                    rawMessage: classification.rawMessage,
+                };
+            }
+            if (staged.status === "duplicate") {
+                return { status: "recovered", revision: staged.revision, shrunk: { duplicate: true } };
+            }
+            let shrunk;
+            try {
+                shrunk = shrink(classification);
+            }
+            catch (shrinkError) {
+                coordinator.cancelStage(staged.staged.token);
+                return {
+                    status: "projection_failed",
+                    errorClass: classification.errorClass,
+                    rawMessage: classification.rawMessage,
+                    reason: shrinkError instanceof Error ? shrinkError.message : String(shrinkError),
+                };
+            }
+            const outcome = coordinator.commitStage({ token: staged.staged.token, apply: () => undefined });
+            if (outcome.status === "stale") {
+                return {
+                    status: "stale",
+                    currentRevision: outcome.currentRevision,
+                    errorClass: classification.errorClass,
+                    rawMessage: classification.rawMessage,
+                };
+            }
+            if (outcome.status === "committed") {
+                return { status: "recovered", revision: outcome.revision, shrunk };
+            }
+            return {
+                status: "projection_failed",
+                errorClass: classification.errorClass,
+                rawMessage: classification.rawMessage,
+                reason: `Unexpected checkpoint outcome: ${outcome.status}`,
+            };
+        },
+    };
+}
+//# sourceMappingURL=overflow-recovery.js.map

package/dist/host/overflow-recovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"overflow-recovery.js","sourceRoot":"","sources":["../../src/host/overflow-recovery.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Provider overflow recovery (2A.3b) — classifies provider errors, offers a\n * recovery entry point for context overflow, and keeps the original error\n * traceable through every outcome.\n *\n * Classification is a deterministic pattern table (context overflow,\n * rate limit, auth, transient, unknown). Only context overflow is\n * recoverable in this slice; other classes are answered `not_recoverable`\n * with the classification attached (rate-limit retry belongs to 2A.4).\n * The recovery path shrinks the payload through a caller callback and\n * commits via the 2A.1 checkpoint; a failing shrink is a structured\n * `projection_failed` — and EVERY outcome carries the raw provider error\n * message, so nothing about the original failure is ever lost. Summary\n * retry is 2A.4a; tree/branch migration stays out of scope.\n */\nimport type { JsonValue } from \"@agent-forge/ai\";\nimport type { HostCheckpointCoordinatorV1 } from \"./checkpoint-commit.ts\";\n\nexport type ProviderErrorClassV1 = \"context_overflow\" | \"rate_limit\" | \"auth\" | \"transient\" | \"unknown\";\n\nexport interface ProviderErrorClassificationV1 {\n\treadonly errorClass: ProviderErrorClassV1;\n\treadonly rawMessage: string;\n\treadonly rawName: string;\n}\n\nexport type OverflowRecoveryOutcomeV1 =\n\t| { readonly status: \"recovered\"; readonly revision: number; readonly shrunk: JsonValue }\n\t| {\n\t\t\treadonly status: \"not_recoverable\";\n\t\t\treadonly errorClass: ProviderErrorClassV1;\n\t\t\treadonly rawMessage: string;\n\t\t\treadonly hint: string;\n\t  }\n\t| {\n\t\t\treadonly status: \"projection_failed\";\n\t\t\treadonly errorClass: ProviderErrorClassV1;\n\t\t\treadonly rawMessage: string;\n\t\t\treadonly reason: string;\n\t  }\n\t| {\n\t\t\treadonly status: \"stale\";\n\t\t\treadonly currentRevision: number;\n\t\t\treadonly errorClass: ProviderErrorClassV1;\n\t\t\treadonly rawMessage: string;\n\t  };\n\nexport interface OverflowRecoveryV1 {\n\tclassify(error: unknown): ProviderErrorClassificationV1;\n\trecover(input: {\n\t\treadonly operationId: string;\n\t\treadonly error: unknown;\n\t\treadonly shrink: (classification: ProviderErrorClassificationV1) => JsonValue;\n\t}): OverflowRecoveryOutcomeV1;\n}\n\nconst CLASSIFICATION_TABLE: readonly (readonly [ProviderErrorClassV1, readonly string[]])[] = [\n\t[\n\t\t\"context_overflow\",\n\t\t[\"context length\", \"maximum context\", \"context window\", \"token limit\", \"too many tokens\", \"overflow\"],\n\t],\n\t[\"rate_limit\", [\"rate limit\", \"429\", \"too many requests\"]],\n\t[\"auth\", [\"401\", \"403\", \"unauthorized\", \"forbidden\", \"invalid api key\"]],\n\t[\"transient\", [\"timeout\", \"econnreset\", \"econnrefused\", \"socket hang up\", \"502\", \"503\"]],\n];\n\nexport function createOverflowRecovery(options: {\n\treadonly coordinator: HostCheckpointCoordinatorV1;\n}): OverflowRecoveryV1 {\n\tconst coordinator = options.coordinator;\n\n\tconst classify = (error: unknown): ProviderErrorClassificationV1 => {\n\t\tconst rawName =\n\t\t\terror instanceof Error\n\t\t\t\t? error.name\n\t\t\t\t: typeof error === \"object\" && error !== null && \"name\" in error\n\t\t\t\t\t? String((error as { name: unknown }).name)\n\t\t\t\t\t: \"unknown\";\n\t\tconst rawMessage = error instanceof Error ? error.message : String(error);\n\t\tconst haystack = `${rawName} ${rawMessage}`.toLowerCase();\n\t\tfor (const [errorClass, patterns] of CLASSIFICATION_TABLE) {\n\t\t\tif (patterns.some((pattern) => haystack.includes(pattern))) {\n\t\t\t\treturn { errorClass, rawMessage, rawName };\n\t\t\t}\n\t\t}\n\t\treturn { errorClass: \"unknown\", rawMessage, rawName };\n\t};\n\n\treturn {\n\t\tclassify,\n\t\trecover({ operationId, error, shrink }) {\n\t\t\tconst classification = classify(error);\n\t\t\tif (classification.errorClass !== \"context_overflow\") {\n\t\t\t\treturn {\n\t\t\t\t\tstatus: \"not_recoverable\",\n\t\t\t\t\terrorClass: classification.errorClass,\n\t\t\t\t\trawMessage: classification.rawMessage,\n\t\t\t\t\thint: \"Only context overflow is recoverable here; rate-limit retry belongs to 2A.4\",\n\t\t\t\t};\n\t\t\t}\n\t\t\tconst staged = coordinator.stage({\n\t\t\t\toperationId,\n\t\t\t\texpectedRevision: coordinator.currentRevision,\n\t\t\t\tpayload: null,\n\t\t\t});\n\t\t\tif (staged.status === \"stale\") {\n\t\t\t\treturn {\n\t\t\t\t\tstatus: \"stale\",\n\t\t\t\t\tcurrentRevision: staged.currentRevision,\n\t\t\t\t\terrorClass: classification.errorClass,\n\t\t\t\t\trawMessage: classification.rawMessage,\n\t\t\t\t};\n\t\t\t}\n\t\t\tif (staged.status === \"duplicate\") {\n\t\t\t\treturn { status: \"recovered\", revision: staged.revision, shrunk: { duplicate: true } };\n\t\t\t}\n\t\t\tlet shrunk: JsonValue;\n\t\t\ttry {\n\t\t\t\tshrunk = shrink(classification);\n\t\t\t} catch (shrinkError) {\n\t\t\t\tcoordinator.cancelStage(staged.staged.token);\n\t\t\t\treturn {\n\t\t\t\t\tstatus: \"projection_failed\",\n\t\t\t\t\terrorClass: classification.errorClass,\n\t\t\t\t\trawMessage: classification.rawMessage,\n\t\t\t\t\treason: shrinkError instanceof Error ? shrinkError.message : String(shrinkError),\n\t\t\t\t};\n\t\t\t}\n\t\t\tconst outcome = coordinator.commitStage({ token: staged.staged.token, apply: () => undefined });\n\t\t\tif (outcome.status === \"stale\") {\n\t\t\t\treturn {\n\t\t\t\t\tstatus: \"stale\",\n\t\t\t\t\tcurrentRevision: outcome.currentRevision,\n\t\t\t\t\terrorClass: classification.errorClass,\n\t\t\t\t\trawMessage: classification.rawMessage,\n\t\t\t\t};\n\t\t\t}\n\t\t\tif (outcome.status === \"committed\") {\n\t\t\t\treturn { status: \"recovered\", revision: outcome.revision, shrunk };\n\t\t\t}\n\t\t\treturn {\n\t\t\t\tstatus: \"projection_failed\",\n\t\t\t\terrorClass: classification.errorClass,\n\t\t\t\trawMessage: classification.rawMessage,\n\t\t\t\treason: `Unexpected checkpoint outcome: ${outcome.status}`,\n\t\t\t};\n\t\t},\n\t};\n}\n"]}

package/dist/host/retry-common.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Shared retry kernel (2A.4a + 2A.4b) — the policy bounds, the attempt-trace
+ * record, and the one backoff formula that the summary retry executor and the
+ * Agent retry scheduler must agree on. Terminal-state semantics (checkpoint
+ * CAS, failure classification, cancellation, duplicate suppression) stay in
+ * each facade on purpose: this module decides nothing about retrying.
+ */
+/** Wait/limit bounds shared by every retry policy in the host layer. */
+export interface RetryWaitPolicyV1 {
+    readonly attemptLimit: number;
+    readonly baseWaitMs: number;
+    readonly maxWaitMs: number;
+}
+/**
+ * One recorded attempt. `retryable` is only written by classifiers that
+ * distinguish retryable from terminal failures; executors without a
+ * classification leave it absent.
+ */
+export interface RetryAttemptRecordV1 {
+    readonly attempt: number;
+    readonly at: number;
+    readonly ok: boolean;
+    readonly failure?: string;
+    readonly retryable?: boolean;
+    readonly waitedMs: number;
+}
+/** Exponential backoff `baseWaitMs × 2^(attempt-1)` capped by `maxWaitMs`. */
+export declare function retryBackoffMs(policy: RetryWaitPolicyV1, attempt: number): number;
+//# sourceMappingURL=retry-common.d.ts.map

package/dist/host/retry-common.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry-common.d.ts","sourceRoot":"","sources":["../../src/host/retry-common.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,wEAAwE;AACxE,MAAM,WAAW,iBAAiB;IACjC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC3B;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACpC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC1B;AAED,+EAA8E;AAC9E,wBAAgB,cAAc,CAAC,MAAM,EAAE,iBAAiB,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAEjF","sourcesContent":["/**\n * Shared retry kernel (2A.4a + 2A.4b) — the policy bounds, the attempt-trace\n * record, and the one backoff formula that the summary retry executor and the\n * Agent retry scheduler must agree on. Terminal-state semantics (checkpoint\n * CAS, failure classification, cancellation, duplicate suppression) stay in\n * each facade on purpose: this module decides nothing about retrying.\n */\n\n/** Wait/limit bounds shared by every retry policy in the host layer. */\nexport interface RetryWaitPolicyV1 {\n\treadonly attemptLimit: number;\n\treadonly baseWaitMs: number;\n\treadonly maxWaitMs: number;\n}\n\n/**\n * One recorded attempt. `retryable` is only written by classifiers that\n * distinguish retryable from terminal failures; executors without a\n * classification leave it absent.\n */\nexport interface RetryAttemptRecordV1 {\n\treadonly attempt: number;\n\treadonly at: number;\n\treadonly ok: boolean;\n\treadonly failure?: string;\n\treadonly retryable?: boolean;\n\treadonly waitedMs: number;\n}\n\n/** Exponential backoff `baseWaitMs × 2^(attempt-1)` capped by `maxWaitMs`. */\nexport function retryBackoffMs(policy: RetryWaitPolicyV1, attempt: number): number {\n\treturn Math.min(policy.baseWaitMs * 2 ** (attempt - 1), policy.maxWaitMs);\n}\n"]}

package/dist/host/retry-common.js

@@ -0,0 +1,12 @@
+/**
+ * Shared retry kernel (2A.4a + 2A.4b) — the policy bounds, the attempt-trace
+ * record, and the one backoff formula that the summary retry executor and the
+ * Agent retry scheduler must agree on. Terminal-state semantics (checkpoint
+ * CAS, failure classification, cancellation, duplicate suppression) stay in
+ * each facade on purpose: this module decides nothing about retrying.
+ */
+/** Exponential backoff `baseWaitMs × 2^(attempt-1)` capped by `maxWaitMs`. */
+export function retryBackoffMs(policy, attempt) {
+    return Math.min(policy.baseWaitMs * 2 ** (attempt - 1), policy.maxWaitMs);
+}
+//# sourceMappingURL=retry-common.js.map

package/dist/host/retry-common.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry-common.js","sourceRoot":"","sources":["../../src/host/retry-common.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAuBH,+EAA8E;AAC9E,MAAM,UAAU,cAAc,CAAC,MAAyB,EAAE,OAAe,EAAU;IAClF,OAAO,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,UAAU,GAAG,CAAC,IAAI,CAAC,OAAO,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC;AAAA,CAC1E","sourcesContent":["/**\n * Shared retry kernel (2A.4a + 2A.4b) — the policy bounds, the attempt-trace\n * record, and the one backoff formula that the summary retry executor and the\n * Agent retry scheduler must agree on. Terminal-state semantics (checkpoint\n * CAS, failure classification, cancellation, duplicate suppression) stay in\n * each facade on purpose: this module decides nothing about retrying.\n */\n\n/** Wait/limit bounds shared by every retry policy in the host layer. */\nexport interface RetryWaitPolicyV1 {\n\treadonly attemptLimit: number;\n\treadonly baseWaitMs: number;\n\treadonly maxWaitMs: number;\n}\n\n/**\n * One recorded attempt. `retryable` is only written by classifiers that\n * distinguish retryable from terminal failures; executors without a\n * classification leave it absent.\n */\nexport interface RetryAttemptRecordV1 {\n\treadonly attempt: number;\n\treadonly at: number;\n\treadonly ok: boolean;\n\treadonly failure?: string;\n\treadonly retryable?: boolean;\n\treadonly waitedMs: number;\n}\n\n/** Exponential backoff `baseWaitMs × 2^(attempt-1)` capped by `maxWaitMs`. */\nexport function retryBackoffMs(policy: RetryWaitPolicyV1, attempt: number): number {\n\treturn Math.min(policy.baseWaitMs * 2 ** (attempt - 1), policy.maxWaitMs);\n}\n"]}

package/dist/host/session-event-translation.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Session event translation (3.5b) — converts the AgentSessionEvent stream
+ * into host events (2.6b) so hosts can project and route them through a
+ * channel adapter without knowing session internals.
+ *
+ * Mapping:
+ * - tool_execution_start -> tool_call (callId carries the session toolCallId)
+ * - tool_execution_end   -> tool_result (ok = !isError, detail = result summary)
+ * - auto_retry_end (failure) -> error; a successful retry carries no diagnostic
+ * - everything else -> no host event
+ *
+ * message_update is deliberately not translated: streaming granularity cannot
+ * identify the turn-final answer (text_end also fires for text blocks that
+ * precede tool calls), and deltas must never reach stdout. In print mode the
+ * stdout contract stays owned by the existing final-output path, so skipping
+ * message_update keeps stdout byte-identical by construction.
+ */
+import type { AgentSessionEvent } from "../core/agent-session.ts";
+import type { HostEventV1 } from "./output-projection.ts";
+/**
+ * Translate one session event into zero or more host events sharing `traceId`.
+ * The returned events are always well-formed (known kinds, non-empty traceId
+ * required by the caller), so the downstream projection cannot reject them.
+ */
+export declare function translateSessionEvent(event: AgentSessionEvent, traceId: string): HostEventV1[];
+//# sourceMappingURL=session-event-translation.d.ts.map

package/dist/host/session-event-translation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-event-translation.d.ts","sourceRoot":"","sources":["../../src/host/session-event-translation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAuB1D;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,iBAAiB,EAAE,OAAO,EAAE,MAAM,GAAG,WAAW,EAAE,CAiC9F","sourcesContent":["/**\n * Session event translation (3.5b) — converts the AgentSessionEvent stream\n * into host events (2.6b) so hosts can project and route them through a\n * channel adapter without knowing session internals.\n *\n * Mapping:\n * - tool_execution_start -> tool_call (callId carries the session toolCallId)\n * - tool_execution_end   -> tool_result (ok = !isError, detail = result summary)\n * - auto_retry_end (failure) -> error; a successful retry carries no diagnostic\n * - everything else -> no host event\n *\n * message_update is deliberately not translated: streaming granularity cannot\n * identify the turn-final answer (text_end also fires for text blocks that\n * precede tool calls), and deltas must never reach stdout. In print mode the\n * stdout contract stays owned by the existing final-output path, so skipping\n * message_update keeps stdout byte-identical by construction.\n */\nimport type { AgentSessionEvent } from \"../core/agent-session.ts\";\nimport type { HostEventV1 } from \"./output-projection.ts\";\n\n/** Upper bound for tool result summaries; longer output is truncated. */\nconst DETAIL_MAX_LENGTH = 200;\n\nfunction truncateDetail(text: string): string {\n\treturn text.length > DETAIL_MAX_LENGTH ? `${text.slice(0, DETAIL_MAX_LENGTH)}…` : text;\n}\n\n/** Deterministic, single-line summary of a tool result for diagnostics. */\nfunction summarizeDetail(value: unknown): string | undefined {\n\tif (typeof value === \"string\") {\n\t\treturn value.length === 0 ? undefined : truncateDetail(value);\n\t}\n\tif (value === undefined) return undefined;\n\ttry {\n\t\treturn truncateDetail(JSON.stringify(value) ?? String(value));\n\t} catch {\n\t\t// Unserializable tool output (e.g. circular structures); keep a readable fallback.\n\t\treturn truncateDetail(String(value));\n\t}\n}\n\n/**\n * Translate one session event into zero or more host events sharing `traceId`.\n * The returned events are always well-formed (known kinds, non-empty traceId\n * required by the caller), so the downstream projection cannot reject them.\n */\nexport function translateSessionEvent(event: AgentSessionEvent, traceId: string): HostEventV1[] {\n\tconst at = Date.now();\n\tswitch (event.type) {\n\t\tcase \"tool_execution_start\":\n\t\t\treturn [{ kind: \"tool_call\", traceId, at, callId: event.toolCallId, toolName: event.toolName }];\n\t\tcase \"tool_execution_end\": {\n\t\t\tconst detail = summarizeDetail(event.result);\n\t\t\treturn [\n\t\t\t\t{\n\t\t\t\t\tkind: \"tool_result\",\n\t\t\t\t\ttraceId,\n\t\t\t\t\tat,\n\t\t\t\t\tcallId: event.toolCallId,\n\t\t\t\t\ttoolName: event.toolName,\n\t\t\t\t\tok: !event.isError,\n\t\t\t\t\t...(detail === undefined ? {} : { detail }),\n\t\t\t\t},\n\t\t\t];\n\t\t}\n\t\tcase \"auto_retry_end\":\n\t\t\tif (event.success) return [];\n\t\t\treturn [\n\t\t\t\t{\n\t\t\t\t\tkind: \"error\",\n\t\t\t\t\ttraceId,\n\t\t\t\t\tat,\n\t\t\t\t\tname: \"AutoRetryError\",\n\t\t\t\t\tmessage: event.finalError ?? `Auto retry failed at attempt ${event.attempt}`,\n\t\t\t\t},\n\t\t\t];\n\t\tdefault:\n\t\t\treturn [];\n\t}\n}\n"]}

package/dist/host/session-event-translation.js

@@ -0,0 +1,61 @@
+/** Upper bound for tool result summaries; longer output is truncated. */
+const DETAIL_MAX_LENGTH = 200;
+function truncateDetail(text) {
+    return text.length > DETAIL_MAX_LENGTH ? `${text.slice(0, DETAIL_MAX_LENGTH)}…` : text;
+}
+/** Deterministic, single-line summary of a tool result for diagnostics. */
+function summarizeDetail(value) {
+    if (typeof value === "string") {
+        return value.length === 0 ? undefined : truncateDetail(value);
+    }
+    if (value === undefined)
+        return undefined;
+    try {
+        return truncateDetail(JSON.stringify(value) ?? String(value));
+    }
+    catch {
+        // Unserializable tool output (e.g. circular structures); keep a readable fallback.
+        return truncateDetail(String(value));
+    }
+}
+/**
+ * Translate one session event into zero or more host events sharing `traceId`.
+ * The returned events are always well-formed (known kinds, non-empty traceId
+ * required by the caller), so the downstream projection cannot reject them.
+ */
+export function translateSessionEvent(event, traceId) {
+    const at = Date.now();
+    switch (event.type) {
+        case "tool_execution_start":
+            return [{ kind: "tool_call", traceId, at, callId: event.toolCallId, toolName: event.toolName }];
+        case "tool_execution_end": {
+            const detail = summarizeDetail(event.result);
+            return [
+                {
+                    kind: "tool_result",
+                    traceId,
+                    at,
+                    callId: event.toolCallId,
+                    toolName: event.toolName,
+                    ok: !event.isError,
+                    ...(detail === undefined ? {} : { detail }),
+                },
+            ];
+        }
+        case "auto_retry_end":
+            if (event.success)
+                return [];
+            return [
+                {
+                    kind: "error",
+                    traceId,
+                    at,
+                    name: "AutoRetryError",
+                    message: event.finalError ?? `Auto retry failed at attempt ${event.attempt}`,
+                },
+            ];
+        default:
+            return [];
+    }
+}
+//# sourceMappingURL=session-event-translation.js.map

package/dist/host/session-event-translation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-event-translation.js","sourceRoot":"","sources":["../../src/host/session-event-translation.ts"],"names":[],"mappings":"AAoBA,yEAAyE;AACzE,MAAM,iBAAiB,GAAG,GAAG,CAAC;AAE9B,SAAS,cAAc,CAAC,IAAY,EAAU;IAC7C,OAAO,IAAI,CAAC,MAAM,GAAG,iBAAiB,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,iBAAiB,CAAC,KAAG,CAAC,CAAC,CAAC,IAAI,CAAC;AAAA,CACvF;AAED,2EAA2E;AAC3E,SAAS,eAAe,CAAC,KAAc,EAAsB;IAC5D,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC/B,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;IAC/D,CAAC;IACD,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC1C,IAAI,CAAC;QACJ,OAAO,cAAc,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IAC/D,CAAC;IAAC,MAAM,CAAC;QACR,mFAAmF;QACnF,OAAO,cAAc,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IACtC,CAAC;AAAA,CACD;AAED;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAwB,EAAE,OAAe,EAAiB;IAC/F,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACtB,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;QACpB,KAAK,sBAAsB;YAC1B,OAAO,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,CAAC,UAAU,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC;QACjG,KAAK,oBAAoB,EAAE,CAAC;YAC3B,MAAM,MAAM,GAAG,eAAe,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;YAC7C,OAAO;gBACN;oBACC,IAAI,EAAE,aAAa;oBACnB,OAAO;oBACP,EAAE;oBACF,MAAM,EAAE,KAAK,CAAC,UAAU;oBACxB,QAAQ,EAAE,KAAK,CAAC,QAAQ;oBACxB,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO;oBAClB,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC;iBAC3C;aACD,CAAC;QACH,CAAC;QACD,KAAK,gBAAgB;YACpB,IAAI,KAAK,CAAC,OAAO;gBAAE,OAAO,EAAE,CAAC;YAC7B,OAAO;gBACN;oBACC,IAAI,EAAE,OAAO;oBACb,OAAO;oBACP,EAAE;oBACF,IAAI,EAAE,gBAAgB;oBACtB,OAAO,EAAE,KAAK,CAAC,UAAU,IAAI,gCAAgC,KAAK,CAAC,OAAO,EAAE;iBAC5E;aACD,CAAC;QACH;YACC,OAAO,EAAE,CAAC;IACZ,CAAC;AAAA,CACD","sourcesContent":["/**\n * Session event translation (3.5b) — converts the AgentSessionEvent stream\n * into host events (2.6b) so hosts can project and route them through a\n * channel adapter without knowing session internals.\n *\n * Mapping:\n * - tool_execution_start -> tool_call (callId carries the session toolCallId)\n * - tool_execution_end   -> tool_result (ok = !isError, detail = result summary)\n * - auto_retry_end (failure) -> error; a successful retry carries no diagnostic\n * - everything else -> no host event\n *\n * message_update is deliberately not translated: streaming granularity cannot\n * identify the turn-final answer (text_end also fires for text blocks that\n * precede tool calls), and deltas must never reach stdout. In print mode the\n * stdout contract stays owned by the existing final-output path, so skipping\n * message_update keeps stdout byte-identical by construction.\n */\nimport type { AgentSessionEvent } from \"../core/agent-session.ts\";\nimport type { HostEventV1 } from \"./output-projection.ts\";\n\n/** Upper bound for tool result summaries; longer output is truncated. */\nconst DETAIL_MAX_LENGTH = 200;\n\nfunction truncateDetail(text: string): string {\n\treturn text.length > DETAIL_MAX_LENGTH ? `${text.slice(0, DETAIL_MAX_LENGTH)}…` : text;\n}\n\n/** Deterministic, single-line summary of a tool result for diagnostics. */\nfunction summarizeDetail(value: unknown): string | undefined {\n\tif (typeof value === \"string\") {\n\t\treturn value.length === 0 ? undefined : truncateDetail(value);\n\t}\n\tif (value === undefined) return undefined;\n\ttry {\n\t\treturn truncateDetail(JSON.stringify(value) ?? String(value));\n\t} catch {\n\t\t// Unserializable tool output (e.g. circular structures); keep a readable fallback.\n\t\treturn truncateDetail(String(value));\n\t}\n}\n\n/**\n * Translate one session event into zero or more host events sharing `traceId`.\n * The returned events are always well-formed (known kinds, non-empty traceId\n * required by the caller), so the downstream projection cannot reject them.\n */\nexport function translateSessionEvent(event: AgentSessionEvent, traceId: string): HostEventV1[] {\n\tconst at = Date.now();\n\tswitch (event.type) {\n\t\tcase \"tool_execution_start\":\n\t\t\treturn [{ kind: \"tool_call\", traceId, at, callId: event.toolCallId, toolName: event.toolName }];\n\t\tcase \"tool_execution_end\": {\n\t\t\tconst detail = summarizeDetail(event.result);\n\t\t\treturn [\n\t\t\t\t{\n\t\t\t\t\tkind: \"tool_result\",\n\t\t\t\t\ttraceId,\n\t\t\t\t\tat,\n\t\t\t\t\tcallId: event.toolCallId,\n\t\t\t\t\ttoolName: event.toolName,\n\t\t\t\t\tok: !event.isError,\n\t\t\t\t\t...(detail === undefined ? {} : { detail }),\n\t\t\t\t},\n\t\t\t];\n\t\t}\n\t\tcase \"auto_retry_end\":\n\t\t\tif (event.success) return [];\n\t\t\treturn [\n\t\t\t\t{\n\t\t\t\t\tkind: \"error\",\n\t\t\t\t\ttraceId,\n\t\t\t\t\tat,\n\t\t\t\t\tname: \"AutoRetryError\",\n\t\t\t\t\tmessage: event.finalError ?? `Auto retry failed at attempt ${event.attempt}`,\n\t\t\t\t},\n\t\t\t];\n\t\tdefault:\n\t\t\treturn [];\n\t}\n}\n"]}

package/dist/host/summary-retry.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Summary retry policy/executor (2A.4a) — deterministic retry of a single
+ * summary operation with full attempt traceability.
+ *
+ * Retry policy: exponential backoff `baseMs × 2^(failure-1)` capped by
+ * `maxWaitMs`, at most `attemptLimit` attempts. Every attempt (success or
+ * failure) is recorded with its sequence number, timestamp, failure reason,
+ * and the wait that followed it; the outcome records the committed
+ * revision, so attempts, operation, revision, waits, and the terminal state
+ * are all traceable. Sleeps are injected (default: no-op) keeping the
+ * executor deterministic. The general Agent retry scheduler is 2A.4b;
+ * tree/branch migration stays out of scope.
+ *
+ * Policy bounds, the attempt-trace record, and the backoff formula come from
+ * the shared retry kernel (`retry-common.ts`); this facade owns only the
+ * checkpoint-CAS semantics and the policy validation below.
+ */
+import type { JsonValue } from "@agent-forge/ai";
+import type { HostCheckpointCoordinatorV1 } from "./checkpoint-commit.ts";
+import type { RetryAttemptRecordV1, RetryWaitPolicyV1 } from "./retry-common.ts";
+export interface SummaryRetryPolicyV1 extends RetryWaitPolicyV1 {
+    readonly policyId: string;
+}
+export type SummaryAttemptRecordV1 = RetryAttemptRecordV1;
+export type SummaryRetryOutcomeV1 = {
+    readonly status: "succeeded";
+    readonly operationId: string;
+    readonly revision: number;
+    readonly summary: JsonValue;
+    readonly attempts: readonly SummaryAttemptRecordV1[];
+} | {
+    readonly status: "exhausted";
+    readonly operationId: string;
+    readonly attempts: readonly SummaryAttemptRecordV1[];
+} | {
+    readonly status: "stale";
+    readonly operationId: string;
+    readonly currentRevision: number;
+    readonly attempts: readonly SummaryAttemptRecordV1[];
+};
+export interface SummaryRetryExecutorV1 {
+    execute(input: {
+        readonly operationId: string;
+        readonly summarize: (attempt: number) => JsonValue;
+    }): SummaryRetryOutcomeV1;
+}
+export declare function createSummaryRetryExecutor(options: {
+    readonly coordinator: HostCheckpointCoordinatorV1;
+    readonly policy: SummaryRetryPolicyV1;
+    readonly now?: () => number;
+    /** Injected sleep (deterministic tests pass a recorder or a no-op). */
+    readonly sleep?: (ms: number) => void;
+}): SummaryRetryExecutorV1;
+//# sourceMappingURL=summary-retry.d.ts.map

package/dist/host/summary-retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"summary-retry.d.ts","sourceRoot":"","sources":["../../src/host/summary-retry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,wBAAwB,CAAC;AAC1E,OAAO,KAAK,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAGjF,MAAM,WAAW,oBAAqB,SAAQ,iBAAiB;IAC9D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,MAAM,sBAAsB,GAAG,oBAAoB,CAAC;AAE1D,MAAM,MAAM,qBAAqB,GAC9B;IACA,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,SAAS,sBAAsB,EAAE,CAAC;CACpD,GACD;IACA,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,SAAS,sBAAsB,EAAE,CAAC;CACpD,GACD;IACA,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE,SAAS,sBAAsB,EAAE,CAAC;CACpD,CAAC;AAEL,MAAM,WAAW,sBAAsB;IACtC,OAAO,CAAC,KAAK,EAAE;QACd,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;QAC7B,QAAQ,CAAC,SAAS,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,SAAS,CAAC;KACnD,GAAG,qBAAqB,CAAC;CAC1B;AAED,wBAAgB,0BAA0B,CAAC,OAAO,EAAE;IACnD,QAAQ,CAAC,WAAW,EAAE,2BAA2B,CAAC;IAClD,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;IACtC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IAC5B,uEAAuE;IACvE,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;CACtC,GAAG,sBAAsB,CA8DzB","sourcesContent":["/**\n * Summary retry policy/executor (2A.4a) — deterministic retry of a single\n * summary operation with full attempt traceability.\n *\n * Retry policy: exponential backoff `baseMs × 2^(failure-1)` capped by\n * `maxWaitMs`, at most `attemptLimit` attempts. Every attempt (success or\n * failure) is recorded with its sequence number, timestamp, failure reason,\n * and the wait that followed it; the outcome records the committed\n * revision, so attempts, operation, revision, waits, and the terminal state\n * are all traceable. Sleeps are injected (default: no-op) keeping the\n * executor deterministic. The general Agent retry scheduler is 2A.4b;\n * tree/branch migration stays out of scope.\n *\n * Policy bounds, the attempt-trace record, and the backoff formula come from\n * the shared retry kernel (`retry-common.ts`); this facade owns only the\n * checkpoint-CAS semantics and the policy validation below.\n */\nimport type { JsonValue } from \"@agent-forge/ai\";\nimport type { HostCheckpointCoordinatorV1 } from \"./checkpoint-commit.ts\";\nimport type { RetryAttemptRecordV1, RetryWaitPolicyV1 } from \"./retry-common.ts\";\nimport { retryBackoffMs } from \"./retry-common.ts\";\n\nexport interface SummaryRetryPolicyV1 extends RetryWaitPolicyV1 {\n\treadonly policyId: string;\n}\n\nexport type SummaryAttemptRecordV1 = RetryAttemptRecordV1;\n\nexport type SummaryRetryOutcomeV1 =\n\t| {\n\t\t\treadonly status: \"succeeded\";\n\t\t\treadonly operationId: string;\n\t\t\treadonly revision: number;\n\t\t\treadonly summary: JsonValue;\n\t\t\treadonly attempts: readonly SummaryAttemptRecordV1[];\n\t  }\n\t| {\n\t\t\treadonly status: \"exhausted\";\n\t\t\treadonly operationId: string;\n\t\t\treadonly attempts: readonly SummaryAttemptRecordV1[];\n\t  }\n\t| {\n\t\t\treadonly status: \"stale\";\n\t\t\treadonly operationId: string;\n\t\t\treadonly currentRevision: number;\n\t\t\treadonly attempts: readonly SummaryAttemptRecordV1[];\n\t  };\n\nexport interface SummaryRetryExecutorV1 {\n\texecute(input: {\n\t\treadonly operationId: string;\n\t\treadonly summarize: (attempt: number) => JsonValue;\n\t}): SummaryRetryOutcomeV1;\n}\n\nexport function createSummaryRetryExecutor(options: {\n\treadonly coordinator: HostCheckpointCoordinatorV1;\n\treadonly policy: SummaryRetryPolicyV1;\n\treadonly now?: () => number;\n\t/** Injected sleep (deterministic tests pass a recorder or a no-op). */\n\treadonly sleep?: (ms: number) => void;\n}): SummaryRetryExecutorV1 {\n\tconst coordinator = options.coordinator;\n\tconst policy = options.policy;\n\tconst now = options.now ?? (() => 0);\n\tconst sleep = options.sleep ?? (() => undefined);\n\n\tif (policy.attemptLimit < 1) throw new Error(\"Summary retry attemptLimit must be at least 1\");\n\tif (policy.baseWaitMs < 0 || policy.maxWaitMs < policy.baseWaitMs) {\n\t\tthrow new Error(\"Summary retry wait bounds are invalid\");\n\t}\n\n\treturn {\n\t\texecute({ operationId, summarize }) {\n\t\t\tconst attempts: SummaryAttemptRecordV1[] = [];\n\t\t\tfor (let attempt = 1; attempt <= policy.attemptLimit; attempt += 1) {\n\t\t\t\tconst at = now();\n\t\t\t\tconst staged = coordinator.stage({\n\t\t\t\t\toperationId: `${operationId}#${attempt}`,\n\t\t\t\t\texpectedRevision: coordinator.currentRevision,\n\t\t\t\t\tpayload: null,\n\t\t\t\t});\n\t\t\t\tif (staged.status === \"stale\") {\n\t\t\t\t\treturn { status: \"stale\", operationId, currentRevision: staged.currentRevision, attempts };\n\t\t\t\t}\n\t\t\t\tif (staged.status === \"duplicate\") {\n\t\t\t\t\treturn {\n\t\t\t\t\t\tstatus: \"succeeded\",\n\t\t\t\t\t\toperationId,\n\t\t\t\t\t\trevision: staged.revision,\n\t\t\t\t\t\tsummary: { duplicate: true },\n\t\t\t\t\t\tattempts,\n\t\t\t\t\t};\n\t\t\t\t}\n\t\t\t\tlet summary: JsonValue;\n\t\t\t\ttry {\n\t\t\t\t\tsummary = summarize(attempt);\n\t\t\t\t} catch (error) {\n\t\t\t\t\tcoordinator.cancelStage(staged.staged.token);\n\t\t\t\t\tconst waitedMs = retryBackoffMs(policy, attempt);\n\t\t\t\t\tattempts.push({\n\t\t\t\t\t\tattempt,\n\t\t\t\t\t\tat,\n\t\t\t\t\t\tok: false,\n\t\t\t\t\t\tfailure: error instanceof Error ? error.message : String(error),\n\t\t\t\t\t\twaitedMs,\n\t\t\t\t\t});\n\t\t\t\t\tif (attempt < policy.attemptLimit) sleep(waitedMs);\n\t\t\t\t\tcontinue;\n\t\t\t\t}\n\t\t\t\tconst outcome = coordinator.commitStage({ token: staged.staged.token, apply: () => undefined });\n\t\t\t\tif (outcome.status === \"stale\") {\n\t\t\t\t\tattempts.push({ attempt, at, ok: true, waitedMs: 0 });\n\t\t\t\t\treturn { status: \"stale\", operationId, currentRevision: outcome.currentRevision, attempts };\n\t\t\t\t}\n\t\t\t\tif (outcome.status === \"committed\") {\n\t\t\t\t\tattempts.push({ attempt, at, ok: true, waitedMs: 0 });\n\t\t\t\t\treturn { status: \"succeeded\", operationId, revision: outcome.revision, summary, attempts };\n\t\t\t\t}\n\t\t\t}\n\t\t\treturn { status: \"exhausted\", operationId, attempts };\n\t\t},\n\t};\n}\n"]}

package/dist/host/summary-retry.js

@@ -0,0 +1,66 @@
+import { retryBackoffMs } from "./retry-common.js";
+export function createSummaryRetryExecutor(options) {
+    const coordinator = options.coordinator;
+    const policy = options.policy;
+    const now = options.now ?? (() => 0);
+    const sleep = options.sleep ?? (() => undefined);
+    if (policy.attemptLimit < 1)
+        throw new Error("Summary retry attemptLimit must be at least 1");
+    if (policy.baseWaitMs < 0 || policy.maxWaitMs < policy.baseWaitMs) {
+        throw new Error("Summary retry wait bounds are invalid");
+    }
+    return {
+        execute({ operationId, summarize }) {
+            const attempts = [];
+            for (let attempt = 1; attempt <= policy.attemptLimit; attempt += 1) {
+                const at = now();
+                const staged = coordinator.stage({
+                    operationId: `${operationId}#${attempt}`,
+                    expectedRevision: coordinator.currentRevision,
+                    payload: null,
+                });
+                if (staged.status === "stale") {
+                    return { status: "stale", operationId, currentRevision: staged.currentRevision, attempts };
+                }
+                if (staged.status === "duplicate") {
+                    return {
+                        status: "succeeded",
+                        operationId,
+                        revision: staged.revision,
+                        summary: { duplicate: true },
+                        attempts,
+                    };
+                }
+                let summary;
+                try {
+                    summary = summarize(attempt);
+                }
+                catch (error) {
+                    coordinator.cancelStage(staged.staged.token);
+                    const waitedMs = retryBackoffMs(policy, attempt);
+                    attempts.push({
+                        attempt,
+                        at,
+                        ok: false,
+                        failure: error instanceof Error ? error.message : String(error),
+                        waitedMs,
+                    });
+                    if (attempt < policy.attemptLimit)
+                        sleep(waitedMs);
+                    continue;
+                }
+                const outcome = coordinator.commitStage({ token: staged.staged.token, apply: () => undefined });
+                if (outcome.status === "stale") {
+                    attempts.push({ attempt, at, ok: true, waitedMs: 0 });
+                    return { status: "stale", operationId, currentRevision: outcome.currentRevision, attempts };
+                }
+                if (outcome.status === "committed") {
+                    attempts.push({ attempt, at, ok: true, waitedMs: 0 });
+                    return { status: "succeeded", operationId, revision: outcome.revision, summary, attempts };
+                }
+            }
+            return { status: "exhausted", operationId, attempts };
+        },
+    };
+}
+//# sourceMappingURL=summary-retry.js.map

package/dist/host/summary-retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"summary-retry.js","sourceRoot":"","sources":["../../src/host/summary-retry.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Summary retry policy/executor (2A.4a) — deterministic retry of a single\n * summary operation with full attempt traceability.\n *\n * Retry policy: exponential backoff `baseMs × 2^(failure-1)` capped by\n * `maxWaitMs`, at most `attemptLimit` attempts. Every attempt (success or\n * failure) is recorded with its sequence number, timestamp, failure reason,\n * and the wait that followed it; the outcome records the committed\n * revision, so attempts, operation, revision, waits, and the terminal state\n * are all traceable. Sleeps are injected (default: no-op) keeping the\n * executor deterministic. The general Agent retry scheduler is 2A.4b;\n * tree/branch migration stays out of scope.\n *\n * Policy bounds, the attempt-trace record, and the backoff formula come from\n * the shared retry kernel (`retry-common.ts`); this facade owns only the\n * checkpoint-CAS semantics and the policy validation below.\n */\nimport type { JsonValue } from \"@agent-forge/ai\";\nimport type { HostCheckpointCoordinatorV1 } from \"./checkpoint-commit.ts\";\nimport type { RetryAttemptRecordV1, RetryWaitPolicyV1 } from \"./retry-common.ts\";\nimport { retryBackoffMs } from \"./retry-common.ts\";\n\nexport interface SummaryRetryPolicyV1 extends RetryWaitPolicyV1 {\n\treadonly policyId: string;\n}\n\nexport type SummaryAttemptRecordV1 = RetryAttemptRecordV1;\n\nexport type SummaryRetryOutcomeV1 =\n\t| {\n\t\t\treadonly status: \"succeeded\";\n\t\t\treadonly operationId: string;\n\t\t\treadonly revision: number;\n\t\t\treadonly summary: JsonValue;\n\t\t\treadonly attempts: readonly SummaryAttemptRecordV1[];\n\t  }\n\t| {\n\t\t\treadonly status: \"exhausted\";\n\t\t\treadonly operationId: string;\n\t\t\treadonly attempts: readonly SummaryAttemptRecordV1[];\n\t  }\n\t| {\n\t\t\treadonly status: \"stale\";\n\t\t\treadonly operationId: string;\n\t\t\treadonly currentRevision: number;\n\t\t\treadonly attempts: readonly SummaryAttemptRecordV1[];\n\t  };\n\nexport interface SummaryRetryExecutorV1 {\n\texecute(input: {\n\t\treadonly operationId: string;\n\t\treadonly summarize: (attempt: number) => JsonValue;\n\t}): SummaryRetryOutcomeV1;\n}\n\nexport function createSummaryRetryExecutor(options: {\n\treadonly coordinator: HostCheckpointCoordinatorV1;\n\treadonly policy: SummaryRetryPolicyV1;\n\treadonly now?: () => number;\n\t/** Injected sleep (deterministic tests pass a recorder or a no-op). */\n\treadonly sleep?: (ms: number) => void;\n}): SummaryRetryExecutorV1 {\n\tconst coordinator = options.coordinator;\n\tconst policy = options.policy;\n\tconst now = options.now ?? (() => 0);\n\tconst sleep = options.sleep ?? (() => undefined);\n\n\tif (policy.attemptLimit < 1) throw new Error(\"Summary retry attemptLimit must be at least 1\");\n\tif (policy.baseWaitMs < 0 || policy.maxWaitMs < policy.baseWaitMs) {\n\t\tthrow new Error(\"Summary retry wait bounds are invalid\");\n\t}\n\n\treturn {\n\t\texecute({ operationId, summarize }) {\n\t\t\tconst attempts: SummaryAttemptRecordV1[] = [];\n\t\t\tfor (let attempt = 1; attempt <= policy.attemptLimit; attempt += 1) {\n\t\t\t\tconst at = now();\n\t\t\t\tconst staged = coordinator.stage({\n\t\t\t\t\toperationId: `${operationId}#${attempt}`,\n\t\t\t\t\texpectedRevision: coordinator.currentRevision,\n\t\t\t\t\tpayload: null,\n\t\t\t\t});\n\t\t\t\tif (staged.status === \"stale\") {\n\t\t\t\t\treturn { status: \"stale\", operationId, currentRevision: staged.currentRevision, attempts };\n\t\t\t\t}\n\t\t\t\tif (staged.status === \"duplicate\") {\n\t\t\t\t\treturn {\n\t\t\t\t\t\tstatus: \"succeeded\",\n\t\t\t\t\t\toperationId,\n\t\t\t\t\t\trevision: staged.revision,\n\t\t\t\t\t\tsummary: { duplicate: true },\n\t\t\t\t\t\tattempts,\n\t\t\t\t\t};\n\t\t\t\t}\n\t\t\t\tlet summary: JsonValue;\n\t\t\t\ttry {\n\t\t\t\t\tsummary = summarize(attempt);\n\t\t\t\t} catch (error) {\n\t\t\t\t\tcoordinator.cancelStage(staged.staged.token);\n\t\t\t\t\tconst waitedMs = retryBackoffMs(policy, attempt);\n\t\t\t\t\tattempts.push({\n\t\t\t\t\t\tattempt,\n\t\t\t\t\t\tat,\n\t\t\t\t\t\tok: false,\n\t\t\t\t\t\tfailure: error instanceof Error ? error.message : String(error),\n\t\t\t\t\t\twaitedMs,\n\t\t\t\t\t});\n\t\t\t\t\tif (attempt < policy.attemptLimit) sleep(waitedMs);\n\t\t\t\t\tcontinue;\n\t\t\t\t}\n\t\t\t\tconst outcome = coordinator.commitStage({ token: staged.staged.token, apply: () => undefined });\n\t\t\t\tif (outcome.status === \"stale\") {\n\t\t\t\t\tattempts.push({ attempt, at, ok: true, waitedMs: 0 });\n\t\t\t\t\treturn { status: \"stale\", operationId, currentRevision: outcome.currentRevision, attempts };\n\t\t\t\t}\n\t\t\t\tif (outcome.status === \"committed\") {\n\t\t\t\t\tattempts.push({ attempt, at, ok: true, waitedMs: 0 });\n\t\t\t\t\treturn { status: \"succeeded\", operationId, revision: outcome.revision, summary, attempts };\n\t\t\t\t}\n\t\t\t}\n\t\t\treturn { status: \"exhausted\", operationId, attempts };\n\t\t},\n\t};\n}\n"]}