omk-agent-core 0.98.1 → 0.98.3

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,14 +1,14 @@
 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;
     private session;
     private readonly sessionFacade;
-    private phase;
-    private runAbortController?;
-    private runPromise?;
-    private pendingSessionWrites;
+    private readonly lifecycle;
+    private readonly sessionWrites;
     private model;
     private thinkingLevel;
     private systemPrompt;
@@ -24,14 +24,25 @@ export declare class AgentHarness<TSkill extends Skill = Skill, TPromptTemplate
     private followUpQueueMode;
     private nextTurnQueue;
     private handlers;
+    private readonly subscribers;
+    private readonly deferredCommands;
     constructor(options: AgentHarnessOptions<TSkill, TPromptTemplate, TTool>);
     private emitOwn;
     private emitAny;
+    /** Fail closed when an awaited listener tries to wait on its own operation. */
+    private rejectCurrentOperationSelfWait;
     private emitHook;
     private emitBeforeProviderRequest;
     private emitBeforeProviderPayload;
     private emitQueueUpdate;
-    private startRunPromise;
+    /**
+     * Facade write-gate vocabulary mapped from lifecycle state. `settling` maps
+     * to "idle": the queue is drained by the settlement finalizer first, and
+     * listener writes persist after it through the coordinator tail.
+     */
+    private currentPhase;
+    private persistConfigChange;
+    private runOperation;
     private createTurnState;
     private createContext;
     private createStreamFn;
@@ -39,10 +50,10 @@ export declare class AgentHarness<TSkill extends Skill = Skill, TPromptTemplate
     private createLoopConfig;
     private validateUniqueNames;
     private validateToolNames;
-    private flushPendingSessionWrites;
     private handleAgentEvent;
     private emitRunFailure;
     private executeTurn;
+    private runAttempt;
     private executeAgentRun;
     private recoverContextOverflow;
     prompt(text: string, options?: {
@@ -50,6 +61,12 @@ export declare class AgentHarness<TSkill extends Skill = Skill, TPromptTemplate
     }): Promise<AssistantMessage>;
     skill(name: string, additionalInstructions?: string): Promise<AssistantMessage>;
     promptFromTemplate(name: string, args?: string[]): Promise<AssistantMessage>;
+    /**
+     * Steering and follow-up input is consumed only by a running agent attempt.
+     * A structural operation (`compact`, `navigateTree`) runs none, so accepting
+     * input there would silently inject it into an unrelated later prompt.
+     */
+    private expectQueueConsumer;
     steer(text: string, options?: {
         images?: ImageContent[];
     }): Promise<void>;
@@ -86,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;