omk-agent-core 0.98.2 → 0.98.4

package/dist/effects/effect-transitions.js

@@ -0,0 +1,148 @@
+/**
+ * Legal phase moves for one effect. Pure and total: every command either
+ * yields the next phase (plus the reason code the journal should record) or a
+ * classified violation, and nothing here touches the chain, a clock, or I/O.
+ *
+ * The table encodes the two rules the plan refuses to compromise on:
+ *
+ * - `commit_unknown` is only ever left by inspection, compensation, an
+ *   explicit abandonment, or — for `pure`/`idempotent` semantics alone — a
+ *   replay. An `opaque`, `inspectable`, or `compensatable` effect whose commit
+ *   is unknown cannot be re-dispatched (`unsafe_replay`).
+ * - Terminal phases are final. An acknowledged effect cannot be reopened, so a
+ *   late duplicate observation after recovery cannot resurrect it.
+ */
+import { EffectJournalViolation, TERMINAL_EFFECT_PHASES, } from "./effect-types.js";
+const REPLAY_SAFE_SEMANTICS = ["pure", "idempotent"];
+export function isTerminalEffectPhase(phase) {
+    return TERMINAL_EFFECT_PHASES.includes(phase);
+}
+export function isReplaySafe(semantics) {
+    return REPLAY_SAFE_SEMANTICS.includes(semantics);
+}
+function move(phase, reasonCode) {
+    return { ok: true, value: { phase, reasonCode } };
+}
+function invalid(record, command) {
+    return {
+        ok: false,
+        error: new EffectJournalViolation("invalid_transition", `Effect ${record.effectId} cannot ${command.type} from phase ${record.phase}`, record.effectId),
+    };
+}
+function reduceObserve(record, command) {
+    if (record.phase !== "dispatched")
+        return invalid(record, command);
+    switch (command.observation) {
+        case "committed":
+            return move("observed_committed", command.reasonCode ?? "effect.observed_committed");
+        case "not_committed":
+            return move("observed_not_committed", command.reasonCode ?? "effect.observed_not_committed");
+        case "unknown":
+            return move("commit_unknown", command.reasonCode ?? "effect.commit_unknown");
+    }
+}
+function reduceRedispatch(record, command) {
+    if (record.phase === "observed_not_committed")
+        return move("dispatched", "effect.retry_not_committed");
+    if (record.phase !== "commit_unknown")
+        return invalid(record, command);
+    if (isReplaySafe(record.semantics))
+        return move("dispatched", "effect.replay_safe");
+    return {
+        ok: false,
+        error: new EffectJournalViolation("unsafe_replay", `Effect ${record.effectId} has ${record.semantics} semantics and an unknown commit; blind replay is forbidden`, record.effectId),
+    };
+}
+function reduceCompensateBegin(record, command) {
+    if (record.phase !== "observed_committed" && record.phase !== "commit_unknown")
+        return invalid(record, command);
+    if (record.compensationDescriptor === undefined) {
+        return {
+            ok: false,
+            error: new EffectJournalViolation("missing_descriptor", `Effect ${record.effectId} declares no compensation descriptor`, record.effectId),
+        };
+    }
+    return move("compensating", "effect.compensation_started");
+}
+/** Abandonment is an explicit decision (waiver or operator) and must carry its reason. */
+function reduceAbandon(record, command) {
+    const allowed = ["prepared", "observed_not_committed", "commit_unknown", "compensating"];
+    if (!allowed.includes(record.phase))
+        return invalid(record, command);
+    if (command.reasonCode.trim().length === 0) {
+        return {
+            ok: false,
+            error: new EffectJournalViolation("invalid_record", `Abandoning effect ${record.effectId} requires a reason code`, record.effectId),
+        };
+    }
+    return move("abandoned", command.reasonCode);
+}
+/**
+ * Every phase the effect may legally move to next, derived from the same
+ * rules as `reduceEffectPhase`. Replaying a persisted journal uses this to
+ * validate a stored record without reconstructing the command that made it.
+ */
+export function legalNextPhases(record) {
+    switch (record.phase) {
+        case "prepared":
+            return ["dispatched", "abandoned"];
+        case "dispatched":
+            return ["observed_committed", "observed_not_committed", "commit_unknown"];
+        case "observed_committed":
+            return record.compensationDescriptor === undefined ? ["acknowledged"] : ["acknowledged", "compensating"];
+        case "observed_not_committed":
+            return ["dispatched", "abandoned"];
+        case "commit_unknown": {
+            const phases = ["observed_committed", "observed_not_committed", "abandoned"];
+            if (record.compensationDescriptor !== undefined)
+                phases.push("compensating");
+            if (isReplaySafe(record.semantics))
+                phases.push("dispatched");
+            return phases;
+        }
+        case "compensating":
+            return ["compensated", "commit_unknown", "abandoned"];
+        case "acknowledged":
+        case "compensated":
+        case "abandoned":
+            return [];
+    }
+}
+/** Next phase for `command` applied to the effect's latest record. */
+export function reduceEffectPhase(record, command) {
+    if (isTerminalEffectPhase(record.phase))
+        return invalid(record, command);
+    switch (command.type) {
+        case "dispatch":
+            return record.phase === "prepared" ? move("dispatched", "effect.dispatched") : invalid(record, command);
+        case "observe":
+            return reduceObserve(record, command);
+        case "acknowledge":
+            return record.phase === "observed_committed"
+                ? move("acknowledged", "effect.acknowledged")
+                : invalid(record, command);
+        case "resolve_unknown":
+            if (record.phase !== "commit_unknown")
+                return invalid(record, command);
+            return command.inspection === "committed"
+                ? move("observed_committed", "effect.inspection_committed")
+                : move("observed_not_committed", "effect.inspection_not_committed");
+        case "redispatch":
+            return reduceRedispatch(record, command);
+        case "compensate_begin":
+            return reduceCompensateBegin(record, command);
+        case "compensate_end":
+            if (record.phase !== "compensating")
+                return invalid(record, command);
+            return command.result === "compensated"
+                ? move("compensated", "effect.compensated")
+                : move("commit_unknown", "effect.compensation_unknown");
+        case "abandon":
+            return reduceAbandon(record, command);
+        default: {
+            const unknownCommand = command;
+            throw new EffectJournalViolation("invalid_transition", `Unknown effect command ${String(unknownCommand)}`);
+        }
+    }
+}
+//# sourceMappingURL=effect-transitions.js.map

package/dist/effects/effect-transitions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"effect-transitions.js","sourceRoot":"","sources":["../../src/effects/effect-transitions.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Legal phase moves for one effect. Pure and total: every command either\n * yields the next phase (plus the reason code the journal should record) or a\n * classified violation, and nothing here touches the chain, a clock, or I/O.\n *\n * The table encodes the two rules the plan refuses to compromise on:\n *\n * - `commit_unknown` is only ever left by inspection, compensation, an\n *   explicit abandonment, or — for `pure`/`idempotent` semantics alone — a\n *   replay. An `opaque`, `inspectable`, or `compensatable` effect whose commit\n *   is unknown cannot be re-dispatched (`unsafe_replay`).\n * - Terminal phases are final. An acknowledged effect cannot be reopened, so a\n *   late duplicate observation after recovery cannot resurrect it.\n */\n\nimport {\n\ttype EffectCommand,\n\ttype EffectJournalResult,\n\tEffectJournalViolation,\n\ttype EffectPhase,\n\ttype EffectRecord,\n\ttype EffectSemantics,\n\tTERMINAL_EFFECT_PHASES,\n} from \"./effect-types.ts\";\n\nexport interface EffectPhaseMove {\n\treadonly phase: EffectPhase;\n\treadonly reasonCode: string;\n}\n\ntype MoveResult = EffectJournalResult<EffectPhaseMove>;\n\nconst REPLAY_SAFE_SEMANTICS: readonly EffectSemantics[] = [\"pure\", \"idempotent\"];\n\nexport function isTerminalEffectPhase(phase: EffectPhase): boolean {\n\treturn TERMINAL_EFFECT_PHASES.includes(phase);\n}\n\nexport function isReplaySafe(semantics: EffectSemantics): boolean {\n\treturn REPLAY_SAFE_SEMANTICS.includes(semantics);\n}\n\nfunction move(phase: EffectPhase, reasonCode: string): MoveResult {\n\treturn { ok: true, value: { phase, reasonCode } };\n}\n\nfunction invalid(record: EffectRecord, command: EffectCommand): MoveResult {\n\treturn {\n\t\tok: false,\n\t\terror: new EffectJournalViolation(\n\t\t\t\"invalid_transition\",\n\t\t\t`Effect ${record.effectId} cannot ${command.type} from phase ${record.phase}`,\n\t\t\trecord.effectId,\n\t\t),\n\t};\n}\n\nfunction reduceObserve(record: EffectRecord, command: Extract<EffectCommand, { type: \"observe\" }>): MoveResult {\n\tif (record.phase !== \"dispatched\") return invalid(record, command);\n\tswitch (command.observation) {\n\t\tcase \"committed\":\n\t\t\treturn move(\"observed_committed\", command.reasonCode ?? \"effect.observed_committed\");\n\t\tcase \"not_committed\":\n\t\t\treturn move(\"observed_not_committed\", command.reasonCode ?? \"effect.observed_not_committed\");\n\t\tcase \"unknown\":\n\t\t\treturn move(\"commit_unknown\", command.reasonCode ?? \"effect.commit_unknown\");\n\t}\n}\n\nfunction reduceRedispatch(record: EffectRecord, command: Extract<EffectCommand, { type: \"redispatch\" }>): MoveResult {\n\tif (record.phase === \"observed_not_committed\") return move(\"dispatched\", \"effect.retry_not_committed\");\n\tif (record.phase !== \"commit_unknown\") return invalid(record, command);\n\tif (isReplaySafe(record.semantics)) return move(\"dispatched\", \"effect.replay_safe\");\n\treturn {\n\t\tok: false,\n\t\terror: new EffectJournalViolation(\n\t\t\t\"unsafe_replay\",\n\t\t\t`Effect ${record.effectId} has ${record.semantics} semantics and an unknown commit; blind replay is forbidden`,\n\t\t\trecord.effectId,\n\t\t),\n\t};\n}\n\nfunction reduceCompensateBegin(\n\trecord: EffectRecord,\n\tcommand: Extract<EffectCommand, { type: \"compensate_begin\" }>,\n): MoveResult {\n\tif (record.phase !== \"observed_committed\" && record.phase !== \"commit_unknown\") return invalid(record, command);\n\tif (record.compensationDescriptor === undefined) {\n\t\treturn {\n\t\t\tok: false,\n\t\t\terror: new EffectJournalViolation(\n\t\t\t\t\"missing_descriptor\",\n\t\t\t\t`Effect ${record.effectId} declares no compensation descriptor`,\n\t\t\t\trecord.effectId,\n\t\t\t),\n\t\t};\n\t}\n\treturn move(\"compensating\", \"effect.compensation_started\");\n}\n\n/** Abandonment is an explicit decision (waiver or operator) and must carry its reason. */\nfunction reduceAbandon(record: EffectRecord, command: Extract<EffectCommand, { type: \"abandon\" }>): MoveResult {\n\tconst allowed: readonly EffectPhase[] = [\"prepared\", \"observed_not_committed\", \"commit_unknown\", \"compensating\"];\n\tif (!allowed.includes(record.phase)) return invalid(record, command);\n\tif (command.reasonCode.trim().length === 0) {\n\t\treturn {\n\t\t\tok: false,\n\t\t\terror: new EffectJournalViolation(\n\t\t\t\t\"invalid_record\",\n\t\t\t\t`Abandoning effect ${record.effectId} requires a reason code`,\n\t\t\t\trecord.effectId,\n\t\t\t),\n\t\t};\n\t}\n\treturn move(\"abandoned\", command.reasonCode);\n}\n\n/**\n * Every phase the effect may legally move to next, derived from the same\n * rules as `reduceEffectPhase`. Replaying a persisted journal uses this to\n * validate a stored record without reconstructing the command that made it.\n */\nexport function legalNextPhases(record: EffectRecord): readonly EffectPhase[] {\n\tswitch (record.phase) {\n\t\tcase \"prepared\":\n\t\t\treturn [\"dispatched\", \"abandoned\"];\n\t\tcase \"dispatched\":\n\t\t\treturn [\"observed_committed\", \"observed_not_committed\", \"commit_unknown\"];\n\t\tcase \"observed_committed\":\n\t\t\treturn record.compensationDescriptor === undefined ? [\"acknowledged\"] : [\"acknowledged\", \"compensating\"];\n\t\tcase \"observed_not_committed\":\n\t\t\treturn [\"dispatched\", \"abandoned\"];\n\t\tcase \"commit_unknown\": {\n\t\t\tconst phases: EffectPhase[] = [\"observed_committed\", \"observed_not_committed\", \"abandoned\"];\n\t\t\tif (record.compensationDescriptor !== undefined) phases.push(\"compensating\");\n\t\t\tif (isReplaySafe(record.semantics)) phases.push(\"dispatched\");\n\t\t\treturn phases;\n\t\t}\n\t\tcase \"compensating\":\n\t\t\treturn [\"compensated\", \"commit_unknown\", \"abandoned\"];\n\t\tcase \"acknowledged\":\n\t\tcase \"compensated\":\n\t\tcase \"abandoned\":\n\t\t\treturn [];\n\t}\n}\n\n/** Next phase for `command` applied to the effect's latest record. */\nexport function reduceEffectPhase(\n\trecord: EffectRecord,\n\tcommand: Exclude<EffectCommand, { type: \"prepare\" }>,\n): MoveResult {\n\tif (isTerminalEffectPhase(record.phase)) return invalid(record, command);\n\tswitch (command.type) {\n\t\tcase \"dispatch\":\n\t\t\treturn record.phase === \"prepared\" ? move(\"dispatched\", \"effect.dispatched\") : invalid(record, command);\n\t\tcase \"observe\":\n\t\t\treturn reduceObserve(record, command);\n\t\tcase \"acknowledge\":\n\t\t\treturn record.phase === \"observed_committed\"\n\t\t\t\t? move(\"acknowledged\", \"effect.acknowledged\")\n\t\t\t\t: invalid(record, command);\n\t\tcase \"resolve_unknown\":\n\t\t\tif (record.phase !== \"commit_unknown\") return invalid(record, command);\n\t\t\treturn command.inspection === \"committed\"\n\t\t\t\t? move(\"observed_committed\", \"effect.inspection_committed\")\n\t\t\t\t: move(\"observed_not_committed\", \"effect.inspection_not_committed\");\n\t\tcase \"redispatch\":\n\t\t\treturn reduceRedispatch(record, command);\n\t\tcase \"compensate_begin\":\n\t\t\treturn reduceCompensateBegin(record, command);\n\t\tcase \"compensate_end\":\n\t\t\tif (record.phase !== \"compensating\") return invalid(record, command);\n\t\t\treturn command.result === \"compensated\"\n\t\t\t\t? move(\"compensated\", \"effect.compensated\")\n\t\t\t\t: move(\"commit_unknown\", \"effect.compensation_unknown\");\n\t\tcase \"abandon\":\n\t\t\treturn reduceAbandon(record, command);\n\t\tdefault: {\n\t\t\tconst unknownCommand: never = command;\n\t\t\tthrow new EffectJournalViolation(\"invalid_transition\", `Unknown effect command ${String(unknownCommand)}`);\n\t\t}\n\t}\n}\n"]}

package/dist/effects/effect-types.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Effect Journal V2 vocabulary: the durable identity and phase model for every
+ * side effect a harness operation performs.
+ *
+ * A side effect is not a tool result. The tool result says what the tool
+ * reported; the effect record says what the runtime committed to before,
+ * during, and after the action, so that after a crash the question "did it
+ * happen?" has one of three honest answers — committed, not committed, or
+ * unknown — instead of being overwritten by a retry.
+ *
+ * This module imports nothing and declares no behaviour. Legal phase moves
+ * live in `effect-transitions.ts`, the hash-chained journal in
+ * `effect-journal.ts`, recovery in `effect-recovery.ts`.
+ */
+export declare const EFFECT_RECORD_SCHEMA_VERSION: 2;
+/** The hash a journal's first record chains to. */
+export declare const EFFECT_JOURNAL_GENESIS_HASH: string;
+/**
+ * What the runtime may assume about re-executing the effect.
+ *
+ * | semantics       | automatic recovery                                |
+ * | --------------- | ------------------------------------------------- |
+ * | `pure`          | re-execute freely                                 |
+ * | `idempotent`    | re-execute with the same idempotency key           |
+ * | `inspectable`   | inspect the target, then decide                   |
+ * | `compensatable` | run the declared compensation                     |
+ * | `opaque`        | never re-execute automatically; operator decides  |
+ */
+export type EffectSemantics = "pure" | "idempotent" | "inspectable" | "compensatable" | "opaque";
+export type EffectPhase = "prepared" | "dispatched" | "observed_committed" | "observed_not_committed" | "commit_unknown" | "acknowledged" | "compensating" | "compensated" | "abandoned";
+/** Phases after which the journal accepts no further transition for the effect. */
+export declare const TERMINAL_EFFECT_PHASES: readonly EffectPhase[];
+/** Phases whose external outcome is not yet known; a verified verdict needs this set empty. */
+export declare const UNCERTAIN_EFFECT_PHASES: readonly EffectPhase[];
+export interface EffectInspectionDescriptor {
+    readonly kind: string;
+    readonly targetDigest?: string;
+    readonly parameters?: Readonly<Record<string, string>>;
+}
+export interface EffectCompensationDescriptor {
+    readonly kind: string;
+    readonly parameters?: Readonly<Record<string, string>>;
+}
+/** Who performs the effect, under which operation, attempt, lane epoch, and process incarnation. */
+export interface EffectIdentity {
+    readonly effectId: string;
+    readonly operationId: string;
+    readonly attemptId: string;
+    readonly laneId?: string;
+    readonly laneEpoch?: number;
+    readonly processIncarnation: string;
+}
+/** What the effect intends to do, committed before dispatch and constant for the effect's lifetime. */
+export interface EffectIntent {
+    readonly semantics: EffectSemantics;
+    readonly capabilityDigest: string;
+    readonly intentDigest: string;
+    readonly idempotencyKey?: string;
+    readonly inspectDescriptor?: EffectInspectionDescriptor;
+    readonly compensationDescriptor?: EffectCompensationDescriptor;
+}
+/** One hash-chained journal entry: the effect's identity, intent, and phase at `sequence`. */
+export interface EffectRecord extends EffectIdentity, EffectIntent {
+    readonly schemaVersion: typeof EFFECT_RECORD_SCHEMA_VERSION;
+    readonly phase: EffectPhase;
+    readonly sequence: number;
+    readonly timestamp: string;
+    readonly reasonCode?: string;
+    readonly previousRecordHash: string;
+    readonly recordHash: string;
+}
+export type EffectObservation = "committed" | "not_committed" | "unknown";
+export type EffectCommand = {
+    readonly type: "prepare";
+    readonly identity: EffectIdentity;
+    readonly intent: EffectIntent;
+    readonly timestamp: string;
+} | {
+    readonly type: "dispatch";
+    readonly effectId: string;
+    readonly timestamp: string;
+} | {
+    readonly type: "observe";
+    readonly effectId: string;
+    readonly observation: EffectObservation;
+    readonly timestamp: string;
+    readonly reasonCode?: string;
+} | {
+    readonly type: "acknowledge";
+    readonly effectId: string;
+    readonly timestamp: string;
+} | {
+    readonly type: "resolve_unknown";
+    readonly effectId: string;
+    readonly inspection: "committed" | "not_committed";
+    readonly timestamp: string;
+} | {
+    readonly type: "redispatch";
+    readonly effectId: string;
+    readonly timestamp: string;
+} | {
+    readonly type: "compensate_begin";
+    readonly effectId: string;
+    readonly timestamp: string;
+} | {
+    readonly type: "compensate_end";
+    readonly effectId: string;
+    readonly result: "compensated" | "unknown";
+    readonly timestamp: string;
+} | {
+    readonly type: "abandon";
+    readonly effectId: string;
+    readonly reasonCode: string;
+    readonly timestamp: string;
+};
+export type EffectViolationCode = "unknown_effect" | "duplicate_effect" | "invalid_transition" | "unsafe_replay" | "missing_descriptor" | "identity_mismatch" | "sequence_violation" | "chain_break" | "hash_mismatch" | "invalid_record";
+export declare class EffectJournalViolation extends Error {
+    readonly code: EffectViolationCode;
+    readonly effectId?: string;
+    constructor(code: EffectViolationCode, message: string, effectId?: string);
+}
+export type EffectJournalResult<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly error: EffectJournalViolation;
+};
+/** Latest record per effect plus the chain head; the whole thing is plain data. */
+export interface EffectJournalState {
+    readonly headHash: string;
+    readonly lastSequence: number;
+    readonly effects: Readonly<Record<string, EffectRecord>>;
+}
+//# sourceMappingURL=effect-types.d.ts.map

package/dist/effects/effect-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"effect-types.d.ts","sourceRoot":"","sources":["../../src/effects/effect-types.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Effect Journal V2 vocabulary: the durable identity and phase model for every\n * side effect a harness operation performs.\n *\n * A side effect is not a tool result. The tool result says what the tool\n * reported; the effect record says what the runtime committed to before,\n * during, and after the action, so that after a crash the question \"did it\n * happen?\" has one of three honest answers — committed, not committed, or\n * unknown — instead of being overwritten by a retry.\n *\n * This module imports nothing and declares no behaviour. Legal phase moves\n * live in `effect-transitions.ts`, the hash-chained journal in\n * `effect-journal.ts`, recovery in `effect-recovery.ts`.\n */\n\nexport const EFFECT_RECORD_SCHEMA_VERSION = 2 as const;\n\n/** The hash a journal's first record chains to. */\nexport const EFFECT_JOURNAL_GENESIS_HASH = \"0\".repeat(64);\n\n/**\n * What the runtime may assume about re-executing the effect.\n *\n * | semantics       | automatic recovery                                |\n * | --------------- | ------------------------------------------------- |\n * | `pure`          | re-execute freely                                 |\n * | `idempotent`    | re-execute with the same idempotency key           |\n * | `inspectable`   | inspect the target, then decide                   |\n * | `compensatable` | run the declared compensation                     |\n * | `opaque`        | never re-execute automatically; operator decides  |\n */\nexport type EffectSemantics = \"pure\" | \"idempotent\" | \"inspectable\" | \"compensatable\" | \"opaque\";\n\nexport type EffectPhase =\n\t| \"prepared\"\n\t| \"dispatched\"\n\t| \"observed_committed\"\n\t| \"observed_not_committed\"\n\t| \"commit_unknown\"\n\t| \"acknowledged\"\n\t| \"compensating\"\n\t| \"compensated\"\n\t| \"abandoned\";\n\n/** Phases after which the journal accepts no further transition for the effect. */\nexport const TERMINAL_EFFECT_PHASES: readonly EffectPhase[] = [\"acknowledged\", \"compensated\", \"abandoned\"];\n\n/** Phases whose external outcome is not yet known; a verified verdict needs this set empty. */\nexport const UNCERTAIN_EFFECT_PHASES: readonly EffectPhase[] = [\"dispatched\", \"commit_unknown\", \"compensating\"];\n\nexport interface EffectInspectionDescriptor {\n\treadonly kind: string;\n\treadonly targetDigest?: string;\n\treadonly parameters?: Readonly<Record<string, string>>;\n}\n\nexport interface EffectCompensationDescriptor {\n\treadonly kind: string;\n\treadonly parameters?: Readonly<Record<string, string>>;\n}\n\n/** Who performs the effect, under which operation, attempt, lane epoch, and process incarnation. */\nexport interface EffectIdentity {\n\treadonly effectId: string;\n\treadonly operationId: string;\n\treadonly attemptId: string;\n\treadonly laneId?: string;\n\treadonly laneEpoch?: number;\n\treadonly processIncarnation: string;\n}\n\n/** What the effect intends to do, committed before dispatch and constant for the effect's lifetime. */\nexport interface EffectIntent {\n\treadonly semantics: EffectSemantics;\n\treadonly capabilityDigest: string;\n\treadonly intentDigest: string;\n\treadonly idempotencyKey?: string;\n\treadonly inspectDescriptor?: EffectInspectionDescriptor;\n\treadonly compensationDescriptor?: EffectCompensationDescriptor;\n}\n\n/** One hash-chained journal entry: the effect's identity, intent, and phase at `sequence`. */\nexport interface EffectRecord extends EffectIdentity, EffectIntent {\n\treadonly schemaVersion: typeof EFFECT_RECORD_SCHEMA_VERSION;\n\treadonly phase: EffectPhase;\n\treadonly sequence: number;\n\treadonly timestamp: string;\n\treadonly reasonCode?: string;\n\treadonly previousRecordHash: string;\n\treadonly recordHash: string;\n}\n\nexport type EffectObservation = \"committed\" | \"not_committed\" | \"unknown\";\n\nexport type EffectCommand =\n\t| {\n\t\t\treadonly type: \"prepare\";\n\t\t\treadonly identity: EffectIdentity;\n\t\t\treadonly intent: EffectIntent;\n\t\t\treadonly timestamp: string;\n\t  }\n\t| { readonly type: \"dispatch\"; readonly effectId: string; readonly timestamp: string }\n\t| {\n\t\t\treadonly type: \"observe\";\n\t\t\treadonly effectId: string;\n\t\t\treadonly observation: EffectObservation;\n\t\t\treadonly timestamp: string;\n\t\t\treadonly reasonCode?: string;\n\t  }\n\t| { readonly type: \"acknowledge\"; readonly effectId: string; readonly timestamp: string }\n\t| {\n\t\t\treadonly type: \"resolve_unknown\";\n\t\t\treadonly effectId: string;\n\t\t\treadonly inspection: \"committed\" | \"not_committed\";\n\t\t\treadonly timestamp: string;\n\t  }\n\t| { readonly type: \"redispatch\"; readonly effectId: string; readonly timestamp: string }\n\t| { readonly type: \"compensate_begin\"; readonly effectId: string; readonly timestamp: string }\n\t| {\n\t\t\treadonly type: \"compensate_end\";\n\t\t\treadonly effectId: string;\n\t\t\treadonly result: \"compensated\" | \"unknown\";\n\t\t\treadonly timestamp: string;\n\t  }\n\t| { readonly type: \"abandon\"; readonly effectId: string; readonly reasonCode: string; readonly timestamp: string };\n\nexport type EffectViolationCode =\n\t| \"unknown_effect\"\n\t| \"duplicate_effect\"\n\t| \"invalid_transition\"\n\t| \"unsafe_replay\"\n\t| \"missing_descriptor\"\n\t| \"identity_mismatch\"\n\t| \"sequence_violation\"\n\t| \"chain_break\"\n\t| \"hash_mismatch\"\n\t| \"invalid_record\";\n\nexport class EffectJournalViolation extends Error {\n\tpublic readonly code: EffectViolationCode;\n\tpublic readonly effectId?: string;\n\n\tconstructor(code: EffectViolationCode, message: string, effectId?: string) {\n\t\tsuper(message);\n\t\tthis.name = \"EffectJournalViolation\";\n\t\tthis.code = code;\n\t\tthis.effectId = effectId;\n\t}\n}\n\nexport type EffectJournalResult<T> =\n\t| { readonly ok: true; readonly value: T }\n\t| { readonly ok: false; readonly error: EffectJournalViolation };\n\n/** Latest record per effect plus the chain head; the whole thing is plain data. */\nexport interface EffectJournalState {\n\treadonly headHash: string;\n\treadonly lastSequence: number;\n\treadonly effects: Readonly<Record<string, EffectRecord>>;\n}\n"]}

package/dist/effects/effect-types.js

@@ -0,0 +1,32 @@
+/**
+ * Effect Journal V2 vocabulary: the durable identity and phase model for every
+ * side effect a harness operation performs.
+ *
+ * A side effect is not a tool result. The tool result says what the tool
+ * reported; the effect record says what the runtime committed to before,
+ * during, and after the action, so that after a crash the question "did it
+ * happen?" has one of three honest answers — committed, not committed, or
+ * unknown — instead of being overwritten by a retry.
+ *
+ * This module imports nothing and declares no behaviour. Legal phase moves
+ * live in `effect-transitions.ts`, the hash-chained journal in
+ * `effect-journal.ts`, recovery in `effect-recovery.ts`.
+ */
+export const EFFECT_RECORD_SCHEMA_VERSION = 2;
+/** The hash a journal's first record chains to. */
+export const EFFECT_JOURNAL_GENESIS_HASH = "0".repeat(64);
+/** Phases after which the journal accepts no further transition for the effect. */
+export const TERMINAL_EFFECT_PHASES = ["acknowledged", "compensated", "abandoned"];
+/** Phases whose external outcome is not yet known; a verified verdict needs this set empty. */
+export const UNCERTAIN_EFFECT_PHASES = ["dispatched", "commit_unknown", "compensating"];
+export class EffectJournalViolation extends Error {
+    code;
+    effectId;
+    constructor(code, message, effectId) {
+        super(message);
+        this.name = "EffectJournalViolation";
+        this.code = code;
+        this.effectId = effectId;
+    }
+}
+//# sourceMappingURL=effect-types.js.map

package/dist/effects/effect-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"effect-types.js","sourceRoot":"","sources":["../../src/effects/effect-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAU,CAAC;AAEvD,mDAAmD;AACnD,MAAM,CAAC,MAAM,2BAA2B,GAAG,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;AA0B1D,mFAAmF;AACnF,MAAM,CAAC,MAAM,sBAAsB,GAA2B,CAAC,cAAc,EAAE,aAAa,EAAE,WAAW,CAAC,CAAC;AAE3G,+FAA+F;AAC/F,MAAM,CAAC,MAAM,uBAAuB,GAA2B,CAAC,YAAY,EAAE,gBAAgB,EAAE,cAAc,CAAC,CAAC;AA0FhH,MAAM,OAAO,sBAAuB,SAAQ,KAAK;IAChC,IAAI,CAAsB;IAC1B,QAAQ,CAAU;IAElC,YAAY,IAAyB,EAAE,OAAe,EAAE,QAAiB,EAAE;QAC1E,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;QACrC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAAA,CACzB;CACD","sourcesContent":["/**\n * Effect Journal V2 vocabulary: the durable identity and phase model for every\n * side effect a harness operation performs.\n *\n * A side effect is not a tool result. The tool result says what the tool\n * reported; the effect record says what the runtime committed to before,\n * during, and after the action, so that after a crash the question \"did it\n * happen?\" has one of three honest answers — committed, not committed, or\n * unknown — instead of being overwritten by a retry.\n *\n * This module imports nothing and declares no behaviour. Legal phase moves\n * live in `effect-transitions.ts`, the hash-chained journal in\n * `effect-journal.ts`, recovery in `effect-recovery.ts`.\n */\n\nexport const EFFECT_RECORD_SCHEMA_VERSION = 2 as const;\n\n/** The hash a journal's first record chains to. */\nexport const EFFECT_JOURNAL_GENESIS_HASH = \"0\".repeat(64);\n\n/**\n * What the runtime may assume about re-executing the effect.\n *\n * | semantics       | automatic recovery                                |\n * | --------------- | ------------------------------------------------- |\n * | `pure`          | re-execute freely                                 |\n * | `idempotent`    | re-execute with the same idempotency key           |\n * | `inspectable`   | inspect the target, then decide                   |\n * | `compensatable` | run the declared compensation                     |\n * | `opaque`        | never re-execute automatically; operator decides  |\n */\nexport type EffectSemantics = \"pure\" | \"idempotent\" | \"inspectable\" | \"compensatable\" | \"opaque\";\n\nexport type EffectPhase =\n\t| \"prepared\"\n\t| \"dispatched\"\n\t| \"observed_committed\"\n\t| \"observed_not_committed\"\n\t| \"commit_unknown\"\n\t| \"acknowledged\"\n\t| \"compensating\"\n\t| \"compensated\"\n\t| \"abandoned\";\n\n/** Phases after which the journal accepts no further transition for the effect. */\nexport const TERMINAL_EFFECT_PHASES: readonly EffectPhase[] = [\"acknowledged\", \"compensated\", \"abandoned\"];\n\n/** Phases whose external outcome is not yet known; a verified verdict needs this set empty. */\nexport const UNCERTAIN_EFFECT_PHASES: readonly EffectPhase[] = [\"dispatched\", \"commit_unknown\", \"compensating\"];\n\nexport interface EffectInspectionDescriptor {\n\treadonly kind: string;\n\treadonly targetDigest?: string;\n\treadonly parameters?: Readonly<Record<string, string>>;\n}\n\nexport interface EffectCompensationDescriptor {\n\treadonly kind: string;\n\treadonly parameters?: Readonly<Record<string, string>>;\n}\n\n/** Who performs the effect, under which operation, attempt, lane epoch, and process incarnation. */\nexport interface EffectIdentity {\n\treadonly effectId: string;\n\treadonly operationId: string;\n\treadonly attemptId: string;\n\treadonly laneId?: string;\n\treadonly laneEpoch?: number;\n\treadonly processIncarnation: string;\n}\n\n/** What the effect intends to do, committed before dispatch and constant for the effect's lifetime. */\nexport interface EffectIntent {\n\treadonly semantics: EffectSemantics;\n\treadonly capabilityDigest: string;\n\treadonly intentDigest: string;\n\treadonly idempotencyKey?: string;\n\treadonly inspectDescriptor?: EffectInspectionDescriptor;\n\treadonly compensationDescriptor?: EffectCompensationDescriptor;\n}\n\n/** One hash-chained journal entry: the effect's identity, intent, and phase at `sequence`. */\nexport interface EffectRecord extends EffectIdentity, EffectIntent {\n\treadonly schemaVersion: typeof EFFECT_RECORD_SCHEMA_VERSION;\n\treadonly phase: EffectPhase;\n\treadonly sequence: number;\n\treadonly timestamp: string;\n\treadonly reasonCode?: string;\n\treadonly previousRecordHash: string;\n\treadonly recordHash: string;\n}\n\nexport type EffectObservation = \"committed\" | \"not_committed\" | \"unknown\";\n\nexport type EffectCommand =\n\t| {\n\t\t\treadonly type: \"prepare\";\n\t\t\treadonly identity: EffectIdentity;\n\t\t\treadonly intent: EffectIntent;\n\t\t\treadonly timestamp: string;\n\t  }\n\t| { readonly type: \"dispatch\"; readonly effectId: string; readonly timestamp: string }\n\t| {\n\t\t\treadonly type: \"observe\";\n\t\t\treadonly effectId: string;\n\t\t\treadonly observation: EffectObservation;\n\t\t\treadonly timestamp: string;\n\t\t\treadonly reasonCode?: string;\n\t  }\n\t| { readonly type: \"acknowledge\"; readonly effectId: string; readonly timestamp: string }\n\t| {\n\t\t\treadonly type: \"resolve_unknown\";\n\t\t\treadonly effectId: string;\n\t\t\treadonly inspection: \"committed\" | \"not_committed\";\n\t\t\treadonly timestamp: string;\n\t  }\n\t| { readonly type: \"redispatch\"; readonly effectId: string; readonly timestamp: string }\n\t| { readonly type: \"compensate_begin\"; readonly effectId: string; readonly timestamp: string }\n\t| {\n\t\t\treadonly type: \"compensate_end\";\n\t\t\treadonly effectId: string;\n\t\t\treadonly result: \"compensated\" | \"unknown\";\n\t\t\treadonly timestamp: string;\n\t  }\n\t| { readonly type: \"abandon\"; readonly effectId: string; readonly reasonCode: string; readonly timestamp: string };\n\nexport type EffectViolationCode =\n\t| \"unknown_effect\"\n\t| \"duplicate_effect\"\n\t| \"invalid_transition\"\n\t| \"unsafe_replay\"\n\t| \"missing_descriptor\"\n\t| \"identity_mismatch\"\n\t| \"sequence_violation\"\n\t| \"chain_break\"\n\t| \"hash_mismatch\"\n\t| \"invalid_record\";\n\nexport class EffectJournalViolation extends Error {\n\tpublic readonly code: EffectViolationCode;\n\tpublic readonly effectId?: string;\n\n\tconstructor(code: EffectViolationCode, message: string, effectId?: string) {\n\t\tsuper(message);\n\t\tthis.name = \"EffectJournalViolation\";\n\t\tthis.code = code;\n\t\tthis.effectId = effectId;\n\t}\n}\n\nexport type EffectJournalResult<T> =\n\t| { readonly ok: true; readonly value: T }\n\t| { readonly ok: false; readonly error: EffectJournalViolation };\n\n/** Latest record per effect plus the chain head; the whole thing is plain data. */\nexport interface EffectJournalState {\n\treadonly headHash: string;\n\treadonly lastSequence: number;\n\treadonly effects: Readonly<Record<string, EffectRecord>>;\n}\n"]}

package/dist/harness/abort-delivery.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Pure abort-delivery vocabulary, extracted from `AgentHarness`.
+ *
+ * Aborting has two halves that callers need separately: delivering the signal
+ * (safe from anywhere, including an operation's own callbacks, because it never
+ * waits) and waiting for the target's settlement (which a callback of that same
+ * operation must never do — settlement awaits the callback). Keeping the refusal
+ * table and the delivery description here means the oversized harness module only
+ * gains thin delegation, and the rules stay testable without a harness instance.
+ */
+import type { HarnessAbortCapture } from "./operation-lifecycle-controller.ts";
+import type { HarnessLifecycleState } from "./operation-lifecycle-types.ts";
+/** What one abort-signal delivery did, without waiting for anything. */
+export interface AbortSignalDeliveryResult {
+    /** The operation the signal targeted, when one was active or settling. */
+    readonly operationId?: string;
+    /** True only when the abort signal was newly delivered to that operation. */
+    readonly signalDelivered: boolean;
+    /** True when the target was already settling, so no signal could be delivered. */
+    readonly alreadySettling: boolean;
+}
+/** Throw when the active operation is one that refuses an abort. */
+export declare function assertAbortAllowed(snapshot: Readonly<HarnessLifecycleState>): void;
+/** Describe one captured abort delivery for a public, wait-free result. */
+export declare function describeAbortDelivery(capture: HarnessAbortCapture): AbortSignalDeliveryResult;
+//# sourceMappingURL=abort-delivery.d.ts.map

package/dist/harness/abort-delivery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"abort-delivery.d.ts","sourceRoot":"","sources":["../../src/harness/abort-delivery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qCAAqC,CAAC;AAC/E,OAAO,KAAK,EAAE,qBAAqB,EAAwB,MAAM,gCAAgC,CAAC;AAElG,wEAAwE;AACxE,MAAM,WAAW,yBAAyB;IACzC,0EAA0E;IAC1E,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,6EAA6E;IAC7E,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC,kFAAkF;IAClF,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;CAClC;AAWD,oEAAoE;AACpE,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,QAAQ,CAAC,qBAAqB,CAAC,GAAG,IAAI,CAIlF;AAED,2EAA2E;AAC3E,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,mBAAmB,GAAG,yBAAyB,CAM7F","sourcesContent":["/**\n * Pure abort-delivery vocabulary, extracted from `AgentHarness`.\n *\n * Aborting has two halves that callers need separately: delivering the signal\n * (safe from anywhere, including an operation's own callbacks, because it never\n * waits) and waiting for the target's settlement (which a callback of that same\n * operation must never do — settlement awaits the callback). Keeping the refusal\n * table and the delivery description here means the oversized harness module only\n * gains thin delegation, and the rules stay testable without a harness instance.\n */\n\nimport { AgentHarnessError } from \"./errors.ts\";\nimport type { HarnessAbortCapture } from \"./operation-lifecycle-controller.ts\";\nimport type { HarnessLifecycleState, HarnessOperationKind } from \"./operation-lifecycle-types.ts\";\n\n/** What one abort-signal delivery did, without waiting for anything. */\nexport interface AbortSignalDeliveryResult {\n\t/** The operation the signal targeted, when one was active or settling. */\n\treadonly operationId?: string;\n\t/** True only when the abort signal was newly delivered to that operation. */\n\treadonly signalDelivered: boolean;\n\t/** True when the target was already settling, so no signal could be delivered. */\n\treadonly alreadySettling: boolean;\n}\n\n/**\n * Operations that refuse an abort: cancelling them mid-flight would leave their\n * work half-applied, so the caller gets an explicit `invalid_state` instead.\n */\nconst ABORT_REFUSED_OPERATIONS: ReadonlyMap<HarnessOperationKind, string> = new Map([\n\t[\"manual_compaction\", \"Cannot abort during compaction\"],\n\t[\"tree_navigation\", \"Cannot abort during branch_summary\"],\n]);\n\n/** Throw when the active operation is one that refuses an abort. */\nexport function assertAbortAllowed(snapshot: Readonly<HarnessLifecycleState>): void {\n\tif (snapshot.tag !== \"active\") return;\n\tconst refused = ABORT_REFUSED_OPERATIONS.get(snapshot.operation.kind);\n\tif (refused !== undefined) throw new AgentHarnessError(\"invalid_state\", refused);\n}\n\n/** Describe one captured abort delivery for a public, wait-free result. */\nexport function describeAbortDelivery(capture: HarnessAbortCapture): AbortSignalDeliveryResult {\n\treturn {\n\t\t...(capture.target === undefined ? {} : { operationId: capture.target.operation.operationId }),\n\t\tsignalDelivered: capture.signalDelivered,\n\t\talreadySettling: capture.target !== undefined && !capture.signalDelivered,\n\t};\n}\n"]}

package/dist/harness/abort-delivery.js

@@ -0,0 +1,36 @@
+/**
+ * Pure abort-delivery vocabulary, extracted from `AgentHarness`.
+ *
+ * Aborting has two halves that callers need separately: delivering the signal
+ * (safe from anywhere, including an operation's own callbacks, because it never
+ * waits) and waiting for the target's settlement (which a callback of that same
+ * operation must never do — settlement awaits the callback). Keeping the refusal
+ * table and the delivery description here means the oversized harness module only
+ * gains thin delegation, and the rules stay testable without a harness instance.
+ */
+import { AgentHarnessError } from "./errors.js";
+/**
+ * Operations that refuse an abort: cancelling them mid-flight would leave their
+ * work half-applied, so the caller gets an explicit `invalid_state` instead.
+ */
+const ABORT_REFUSED_OPERATIONS = new Map([
+    ["manual_compaction", "Cannot abort during compaction"],
+    ["tree_navigation", "Cannot abort during branch_summary"],
+]);
+/** Throw when the active operation is one that refuses an abort. */
+export function assertAbortAllowed(snapshot) {
+    if (snapshot.tag !== "active")
+        return;
+    const refused = ABORT_REFUSED_OPERATIONS.get(snapshot.operation.kind);
+    if (refused !== undefined)
+        throw new AgentHarnessError("invalid_state", refused);
+}
+/** Describe one captured abort delivery for a public, wait-free result. */
+export function describeAbortDelivery(capture) {
+    return {
+        ...(capture.target === undefined ? {} : { operationId: capture.target.operation.operationId }),
+        signalDelivered: capture.signalDelivered,
+        alreadySettling: capture.target !== undefined && !capture.signalDelivered,
+    };
+}
+//# sourceMappingURL=abort-delivery.js.map

package/dist/harness/abort-delivery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"abort-delivery.js","sourceRoot":"","sources":["../../src/harness/abort-delivery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAchD;;;GAGG;AACH,MAAM,wBAAwB,GAA8C,IAAI,GAAG,CAAC;IACnF,CAAC,mBAAmB,EAAE,gCAAgC,CAAC;IACvD,CAAC,iBAAiB,EAAE,oCAAoC,CAAC;CACzD,CAAC,CAAC;AAEH,oEAAoE;AACpE,MAAM,UAAU,kBAAkB,CAAC,QAAyC,EAAQ;IACnF,IAAI,QAAQ,CAAC,GAAG,KAAK,QAAQ;QAAE,OAAO;IACtC,MAAM,OAAO,GAAG,wBAAwB,CAAC,GAAG,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IACtE,IAAI,OAAO,KAAK,SAAS;QAAE,MAAM,IAAI,iBAAiB,CAAC,eAAe,EAAE,OAAO,CAAC,CAAC;AAAA,CACjF;AAED,2EAA2E;AAC3E,MAAM,UAAU,qBAAqB,CAAC,OAA4B,EAA6B;IAC9F,OAAO;QACN,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,WAAW,EAAE,CAAC;QAC9F,eAAe,EAAE,OAAO,CAAC,eAAe;QACxC,eAAe,EAAE,OAAO,CAAC,MAAM,KAAK,SAAS,IAAI,CAAC,OAAO,CAAC,eAAe;KACzE,CAAC;AAAA,CACF","sourcesContent":["/**\n * Pure abort-delivery vocabulary, extracted from `AgentHarness`.\n *\n * Aborting has two halves that callers need separately: delivering the signal\n * (safe from anywhere, including an operation's own callbacks, because it never\n * waits) and waiting for the target's settlement (which a callback of that same\n * operation must never do — settlement awaits the callback). Keeping the refusal\n * table and the delivery description here means the oversized harness module only\n * gains thin delegation, and the rules stay testable without a harness instance.\n */\n\nimport { AgentHarnessError } from \"./errors.ts\";\nimport type { HarnessAbortCapture } from \"./operation-lifecycle-controller.ts\";\nimport type { HarnessLifecycleState, HarnessOperationKind } from \"./operation-lifecycle-types.ts\";\n\n/** What one abort-signal delivery did, without waiting for anything. */\nexport interface AbortSignalDeliveryResult {\n\t/** The operation the signal targeted, when one was active or settling. */\n\treadonly operationId?: string;\n\t/** True only when the abort signal was newly delivered to that operation. */\n\treadonly signalDelivered: boolean;\n\t/** True when the target was already settling, so no signal could be delivered. */\n\treadonly alreadySettling: boolean;\n}\n\n/**\n * Operations that refuse an abort: cancelling them mid-flight would leave their\n * work half-applied, so the caller gets an explicit `invalid_state` instead.\n */\nconst ABORT_REFUSED_OPERATIONS: ReadonlyMap<HarnessOperationKind, string> = new Map([\n\t[\"manual_compaction\", \"Cannot abort during compaction\"],\n\t[\"tree_navigation\", \"Cannot abort during branch_summary\"],\n]);\n\n/** Throw when the active operation is one that refuses an abort. */\nexport function assertAbortAllowed(snapshot: Readonly<HarnessLifecycleState>): void {\n\tif (snapshot.tag !== \"active\") return;\n\tconst refused = ABORT_REFUSED_OPERATIONS.get(snapshot.operation.kind);\n\tif (refused !== undefined) throw new AgentHarnessError(\"invalid_state\", refused);\n}\n\n/** Describe one captured abort delivery for a public, wait-free result. */\nexport function describeAbortDelivery(capture: HarnessAbortCapture): AbortSignalDeliveryResult {\n\treturn {\n\t\t...(capture.target === undefined ? {} : { operationId: capture.target.operation.operationId }),\n\t\tsignalDelivered: capture.signalDelivered,\n\t\talreadySettling: capture.target !== undefined && !capture.signalDelivered,\n\t};\n}\n"]}

package/dist/harness/agent-harness.d.ts

@@ -1,5 +1,7 @@
 import { type AssistantMessage, type ImageContent, type Model } from "omk-ai";
 import type { AgentMessage, AgentTool, QueueMode, ThinkingLevel } from "../types.ts";
+import { type AbortSignalDeliveryResult } from "./abort-delivery.ts";
+import { type CommandRef, type DeferredHarnessCommand } from "./deferred-commands.ts";
 import type { AbortResult, AgentHarnessEvent, AgentHarnessEventResultMap, AgentHarnessOptions, AgentHarnessOwnEvent, AgentHarnessResources, AgentHarnessStreamOptions, CompactResult, ExecutionEnv, HarnessSession, NavigateTreeResult, PromptTemplate, Skill } from "./types.ts";
 export declare class AgentHarness<TSkill extends Skill = Skill, TPromptTemplate extends PromptTemplate = PromptTemplate, TTool extends AgentTool = AgentTool> {
     readonly env: ExecutionEnv;
@@ -23,6 +25,7 @@ export declare class AgentHarness<TSkill extends Skill = Skill, TPromptTemplate
     private nextTurnQueue;
     private handlers;
     private readonly subscribers;
+    private readonly deferredCommands;
     constructor(options: AgentHarnessOptions<TSkill, TPromptTemplate, TTool>);
     private emitOwn;
     private emitAny;
@@ -100,6 +103,21 @@ export declare class AgentHarness<TSkill extends Skill = Skill, TPromptTemplate
     setResources(resources: AgentHarnessResources<TSkill, TPromptTemplate>): Promise<void>;
     getStreamOptions(): AgentHarnessStreamOptions;
     setStreamOptions(streamOptions: AgentHarnessStreamOptions): Promise<void>;
+    /**
+     * Deliver the abort signal to the current operation without waiting for it to
+     * settle. Safe from an operation's own callbacks: nothing here awaits
+     * settlement, so it cannot form the cycle `abort()` has to refuse.
+     */
+    requestAbort(): AbortSignalDeliveryResult;
+    /**
+     * Queue work to run once the harness is idle and return its ref immediately.
+     *
+     * This is the callback-safe way to schedule follow-up work: awaiting
+     * `waitForIdle()` or `abort()` from a callback of the operation being settled
+     * deadlocks, because settlement awaits that callback. The ref reports the
+     * command's outcome and cancels it while it is still queued.
+     */
+    runWhenIdle(command: DeferredHarnessCommand): Promise<CommandRef>;
     abort(): Promise<AbortResult>;
     waitForIdle(): Promise<void>;
     subscribe(listener: (event: AgentHarnessEvent<TSkill, TPromptTemplate>, signal?: AbortSignal) => Promise<void> | void): () => void;