@kashscript/hudhud 0.1.0

package/dist/runtime/dispatcher.js

@@ -0,0 +1,66 @@
+// ============================================================================
+// @kashscript/hudhud/runtime — NeuronToolDispatcher
+// ----------------------------------------------------------------------------
+// The seam where neuron's DAGExecutor reaches the host's real MCP tool
+// transport, with the accountability append done INLINE on the awaited dispatch
+// path. Neuron's `onEvent` is synchronous fire-and-forget (no back-pressure) —
+// so the signed ledger row is appended HERE, inside the awaited `dispatch`, so
+// a failed append fails the node and the run can never observe an unrecorded
+// tool result. Ported from the oreoasis-core-host engine (M5); telemetry dropped.
+// ============================================================================
+import { ToolDispatchError } from "@kashscript/neuron/kernel";
+export class NeuronToolDispatcher {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** Resolve a tool name to its manifest, or null when unbound. */
+    resolve(toolName) {
+        return this.deps.bindings.get(toolName)?.manifest ?? null;
+    }
+    /** Execute one tool call: resolve binding → real transport → (on JSON-RPC
+     *  error) EXECUTOR_FAILED (no row) → INLINE signed ledger append → return. */
+    async dispatch(input) {
+        const toolName = input.tool.name;
+        const binding = this.deps.bindings.get(toolName);
+        if (binding === undefined) {
+            throw new ToolDispatchError(`NeuronToolDispatcher: no binding registered for tool '${toolName}' (dagNodeId=${input.dagNodeId})`, "TOOL_NOT_FOUND");
+        }
+        const mcpToolName = binding.mcpToolName ?? toolName;
+        const transport = await this.deps.mcpClientPool.executeMcpToolCall(binding.mcpEndpointUrl, mcpToolName, input.parameters);
+        if (!transport.ok) {
+            // audit r1 F8: a money-moving tool can fail AFTER a partial side-effect, so
+            // record the FAILED dispatch on the signed ledger BEFORE throwing — every
+            // dispatch (success or application-error) leaves an accountable row.
+            await this.deps.forensicLedger.appendActorTransition({
+                sessionId: this.deps.sessionId,
+                payloadMutation: {
+                    event: "tool.failed",
+                    tool: toolName,
+                    dagNodeId: input.dagNodeId,
+                    jsonRpcId: transport.jsonRpcId,
+                    errorCode: String(transport.error.code),
+                    errorMessage: transport.error.message,
+                },
+            });
+            throw new ToolDispatchError(`NeuronToolDispatcher: MCP tool '${mcpToolName}' returned a JSON-RPC error (code=${transport.error.code}): ${transport.error.message}`, "EXECUTOR_FAILED");
+        }
+        // INLINE accountability append — BEFORE returning. A throw here fails the
+        // node (the executor awaits us), so no unrecorded result can be observed.
+        await this.deps.forensicLedger.appendActorTransition({
+            sessionId: this.deps.sessionId,
+            payloadMutation: {
+                event: "tool.dispatch",
+                tool: toolName,
+                dagNodeId: input.dagNodeId,
+                jsonRpcId: transport.jsonRpcId,
+                result: transport.result,
+            },
+        });
+        return {
+            output: transport.result,
+            cost: { usdMicros: input.tool.costHint.usdMicros, latencyMs: transport.latencyMs },
+        };
+    }
+}
+//# sourceMappingURL=dispatcher.js.map

package/dist/runtime/dispatcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatcher.js","sourceRoot":"","sources":["../../src/runtime/dispatcher.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,oDAAoD;AACpD,+EAA+E;AAC/E,uEAAuE;AACvE,gFAAgF;AAChF,+EAA+E;AAC/E,+EAA+E;AAC/E,6EAA6E;AAC7E,kFAAkF;AAClF,+EAA+E;AAE/E,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAsB9D,MAAM,OAAO,oBAAoB;IACF;IAA7B,YAA6B,IAA8B;QAA9B,SAAI,GAAJ,IAAI,CAA0B;IAAG,CAAC;IAE/D,iEAAiE;IACjE,OAAO,CAAC,QAAgB;QACtB,OAAO,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,QAAQ,IAAI,IAAI,CAAC;IAC5D,CAAC;IAED;kFAC8E;IAC9E,KAAK,CAAC,QAAQ,CAAC,KAAoB;QACjC,MAAM,QAAQ,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC;QACjC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACjD,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC1B,MAAM,IAAI,iBAAiB,CACzB,yDAAyD,QAAQ,gBAAgB,KAAK,CAAC,SAAS,GAAG,EACnG,gBAAgB,CACjB,CAAC;QACJ,CAAC;QAED,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,QAAQ,CAAC;QACpD,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,kBAAkB,CAAC,OAAO,CAAC,cAAc,EAAE,WAAW,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;QAE1H,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,CAAC;YAClB,4EAA4E;YAC5E,0EAA0E;YAC1E,qEAAqE;YACrE,MAAM,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC,qBAAqB,CAAC;gBACnD,SAAS,EAAE,IAAI,CAAC,IAAI,CAAC,SAAS;gBAC9B,eAAe,EAAE;oBACf,KAAK,EAAE,aAAa;oBACpB,IAAI,EAAE,QAAQ;oBACd,SAAS,EAAE,KAAK,CAAC,SAAS;oBAC1B,SAAS,EAAE,SAAS,CAAC,SAAS;oBAC9B,SAAS,EAAE,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC;oBACvC,YAAY,EAAE,SAAS,CAAC,KAAK,CAAC,OAAO;iBACtC;aACF,CAAC,CAAC;YACH,MAAM,IAAI,iBAAiB,CACzB,mCAAmC,WAAW,qCAAqC,SAAS,CAAC,KAAK,CAAC,IAAI,MAAM,SAAS,CAAC,KAAK,CAAC,OAAO,EAAE,EACtI,iBAAiB,CAClB,CAAC;QACJ,CAAC;QAED,0EAA0E;QAC1E,0EAA0E;QAC1E,MAAM,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC,qBAAqB,CAAC;YACnD,SAAS,EAAE,IAAI,CAAC,IAAI,CAAC,SAAS;YAC9B,eAAe,EAAE;gBACf,KAAK,EAAE,eAAe;gBACtB,IAAI,EAAE,QAAQ;gBACd,SAAS,EAAE,KAAK,CAAC,SAAS;gBAC1B,SAAS,EAAE,SAAS,CAAC,SAAS;gBAC9B,MAAM,EAAE,SAAS,CAAC,MAAM;aACzB;SACF,CAAC,CAAC;QAEH,OAAO;YACL,MAAM,EAAE,SAAS,CAAC,MAAM;YACxB,IAAI,EAAE,EAAE,SAAS,EAAE,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,SAAS,EAAE,SAAS,EAAE,SAAS,CAAC,SAAS,EAAE;SACnF,CAAC;IACJ,CAAC;CACF"}

package/dist/runtime/escalation.d.ts

@@ -0,0 +1,98 @@
+import type { SignedActionEnvelope, ToolCall } from "@kashscript/neuron/handshake";
+import type { ExceptionClassificationInput, ExceptionClassificationRecord, ExceptionClassificationStore } from "../exception";
+import type { LedgerStore } from "../ledger/store";
+import type { ForensicLedgerService } from "../ledger/writer";
+export type EscalationErrorCode = "AGENT_DID_INVALID" | "OPERATOR_DID_INVALID" | "AGENT_OPERATOR_NOT_DISTINCT" | "RESUME_ALREADY_CLAIMED";
+export declare class EscalationError extends Error {
+    readonly code: EscalationErrorCode;
+    readonly detail: Readonly<Record<string, unknown>>;
+    constructor(code: EscalationErrorCode, message: string, detail?: Readonly<Record<string, unknown>>);
+}
+export interface BuildHumanApprovalEnvelopeInput {
+    readonly pendingCall: ToolCall;
+    readonly dagId: string;
+    readonly blueprintId: string;
+    /** The AGENT identity — the host's own key. `did` is the ledger DID (the
+     *  signature `kid`); `publicKey` derives the schema-valid challenge binding. */
+    readonly agent: {
+        readonly did: string;
+        readonly privateKey: Uint8Array;
+        readonly publicKey: Uint8Array;
+    };
+    /** The OPERATOR identity — the SEPARATE human key. */
+    readonly operator: {
+        readonly did: string;
+        readonly privateKey: Uint8Array;
+        readonly publicKey: Uint8Array;
+    };
+    readonly ttlMs?: number;
+}
+/**
+ * Build the two-key `SignedActionEnvelope` that authorizes a resume of a
+ * restricted tool. The two signature `kid`s DIFFER by construction (agent vs
+ * operator), so forging human judgment would require the operator private key.
+ */
+export declare function buildHumanApprovalEnvelope(input: BuildHumanApprovalEnvelopeInput): Promise<SignedActionEnvelope>;
+export interface AppendOperatorSignoffInput {
+    readonly forensicLedger: ForensicLedgerService;
+    readonly ledgerStore: LedgerStore;
+    readonly sessionId: string;
+    readonly operator: {
+        readonly did: string;
+        readonly privateKey: Uint8Array;
+    };
+    readonly escalation: {
+        readonly suspendedStepId: string;
+        readonly toolName: string;
+        readonly escalationId?: string;
+    };
+    /** MANDATORY classification (required `failureClass`, no "unclassified"). */
+    readonly classification: ExceptionClassificationInput;
+    readonly exceptionClassificationStore: ExceptionClassificationStore;
+}
+/**
+ * Append a SIGNED ledger row recording the operator's sign-off (OPERATOR key,
+ * actorClass OPERATOR_ADMIN) + persist the signed exception classification.
+ * The mandatory `failureClass` gate fails-fast before any row is written.
+ */
+export declare function appendOperatorSignoff(input: AppendOperatorSignoffInput): Promise<{
+    stepIndex: number;
+    classification: ExceptionClassificationRecord;
+}>;
+export interface VerifyApprovalEnvelopeInput {
+    readonly envelope: SignedActionEnvelope;
+    /** The AGENT public key (the host's own key) that attested the challenge. */
+    readonly agentPublicKey: Uint8Array;
+    /** The OPERATOR public key — the SEPARATE human key the host cannot mint. */
+    readonly operatorPublicKey: Uint8Array;
+    /** If given, the envelope's proposed tool MUST equal this (bind to the suspended call). */
+    readonly expectedToolName?: string;
+    /** If given, the challenge must not be expired at this wall-clock (ms since epoch). */
+    readonly nowMs?: number;
+}
+export type ApprovalVerificationReason = "MISSING_SIGNATURE_KID" | "KEYS_NOT_DISTINCT" | "TOOL_MISMATCH" | "WRONG_DST" | "EXPIRED" | "AGENT_ATTESTATION_INVALID" | "OPERATOR_SIGNATURE_INVALID";
+export interface ApprovalVerification {
+    readonly ok: boolean;
+    readonly reason: ApprovalVerificationReason | null;
+}
+/**
+ * CRYPTOGRAPHICALLY verify a two-key human-approval envelope before a suspended
+ * run may resume (audit r1 F1). The security-critical check is the OPERATOR
+ * (invoker) signature over `stripDerivedFields(challenge)` under a key the host
+ * does NOT hold — so the host cannot forge human judgment by merely PRESENTING an
+ * envelope. Also re-checks: the AGENT attestation, the two kids differ, the DST is
+ * the handshake DST, the proposed tool matches, and (optionally) the challenge
+ * has not expired. Returns `{ok:false, reason}` on any failure — never throws.
+ */
+export declare function verifyApprovalEnvelope(input: VerifyApprovalEnvelopeInput): Promise<ApprovalVerification>;
+/** One-way claim guard — an escalation/resume key may be claimed AT MOST ONCE,
+ *  so a retried resume can't double-execute a money-moving tool. In-memory
+ *  (single process); a durable CAS is a venture concern. */
+export declare class ResumeGuard {
+    private readonly claimed;
+    /** Claim `escalationKey`. Throws `EscalationError("RESUME_ALREADY_CLAIMED")`
+     *  if already claimed — the throw is the defense. */
+    claim(escalationKey: string): void;
+    isClaimed(escalationKey: string): boolean;
+}
+//# sourceMappingURL=escalation.d.ts.map

package/dist/runtime/escalation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"escalation.d.ts","sourceRoot":"","sources":["../../src/runtime/escalation.ts"],"names":[],"mappings":"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"}

package/dist/runtime/escalation.js

@@ -0,0 +1,188 @@
+// ============================================================================
+// @kashscript/hudhud/runtime — escalation: two-key suspend/resume
+// ----------------------------------------------------------------------------
+// When an autonomous run reaches a RESTRICTED tool it SUSPENDS; a human must
+// sign off before it may RESUME. Two artifacts make "the host cannot forge
+// human judgment" literally true:
+//   1. buildHumanApprovalEnvelope — the TWO-KEY envelope: the AGENT key (which
+//      the host holds) attests the proposed action; a SEPARATE OPERATOR key
+//      signs the challenge. The host cannot mint the invoker signature.
+//   2. appendOperatorSignoff — a SIGNED ledger row on the OPERATOR key
+//      (actorClass OPERATOR_ADMIN) + the mandatory exception classification;
+//      forensicConsistencyScan re-verifies it.
+//   3. ResumeGuard — a one-way claim() so a retried resume can't re-fire a tool.
+// Ported from the oreoasis-core-host engine (M5); telemetry dropped, ledger +
+// exception + neuron/handshake reused.
+// ============================================================================
+import { deriveDid, signEvent, verifyEvent } from "@kashscript/identity-core";
+import { KASH_DID_PATTERN, signLedgerBlock } from "@kashscript/attest";
+import { PermissionGate, assembleEnvelope, stripDerivedFields, } from "@kashscript/neuron/handshake";
+import { NEURON_DST } from "@kashscript/neuron/schemas";
+import { assertFailureClass, buildSignedClassification, } from "../exception";
+import { resolvePreviousBlockHash } from "../ledger/store";
+export class EscalationError extends Error {
+    code;
+    detail;
+    constructor(code, message, detail = {}) {
+        super(`[${code}] ${message}`);
+        this.name = "EscalationError";
+        this.code = code;
+        this.detail = Object.freeze({ ...detail });
+    }
+}
+/** Coerce a 64-hex-ish id to the neuron schema's `0x`-prefixed lowercase-hex form. */
+function asSha256Hex(s) {
+    const lower = s.toLowerCase();
+    const hex = lower.startsWith("0x") ? lower.slice(2) : lower;
+    return `0x${hex}`;
+}
+/** Derive the real `did:kash:` binding for a public key (schema-valid DID). */
+function deriveKashDid(publicKey) {
+    return deriveDid(publicKey);
+}
+/**
+ * Build the two-key `SignedActionEnvelope` that authorizes a resume of a
+ * restricted tool. The two signature `kid`s DIFFER by construction (agent vs
+ * operator), so forging human judgment would require the operator private key.
+ */
+export async function buildHumanApprovalEnvelope(input) {
+    if (!KASH_DID_PATTERN.test(input.agent.did)) {
+        throw new EscalationError("AGENT_DID_INVALID", "agent.did must be a valid did:kash identifier");
+    }
+    if (!KASH_DID_PATTERN.test(input.operator.did)) {
+        throw new EscalationError("OPERATOR_DID_INVALID", "operator.did must be a valid did:kash identifier");
+    }
+    if (input.agent.did === input.operator.did) {
+        throw new EscalationError("AGENT_OPERATOR_NOT_DISTINCT", "agent.did and operator.did must differ — the two-key guarantee requires a SEPARATE operator key");
+    }
+    // 1. AGENT attests the challenge body (proves the agent proposed it).
+    const attest = async (body) => {
+        const signed = await signEvent({}, body, input.agent.privateKey, { dst: NEURON_DST.HANDSHAKE, encoding: "hex", kid: input.agent.did });
+        return { alg: "ed25519", sig: signed.sig, dst: NEURON_DST.HANDSHAKE, encoding: "hex", kid: input.agent.did };
+    };
+    const gate = new PermissionGate();
+    const challenge = await gate.buildChallenge(input.pendingCall, {
+        agentId: deriveKashDid(input.agent.publicKey),
+        invokerId: deriveKashDid(input.operator.publicKey),
+        blueprintId: asSha256Hex(input.blueprintId),
+    }, attest, { dagId: asSha256Hex(input.dagId), ...(input.ttlMs !== undefined ? { ttlMs: input.ttlMs } : {}) });
+    // 2. OPERATOR signs the SAME stripped body with the SEPARATE key.
+    const operatorSigned = await signEvent({}, stripDerivedFields(challenge), input.operator.privateKey, {
+        dst: NEURON_DST.HANDSHAKE,
+        encoding: "hex",
+        kid: input.operator.did,
+    });
+    const invokerSignature = {
+        alg: "ed25519",
+        sig: operatorSigned.sig,
+        dst: NEURON_DST.HANDSHAKE,
+        encoding: "hex",
+        kid: input.operator.did,
+    };
+    return assembleEnvelope(challenge, invokerSignature);
+}
+/**
+ * Append a SIGNED ledger row recording the operator's sign-off (OPERATOR key,
+ * actorClass OPERATOR_ADMIN) + persist the signed exception classification.
+ * The mandatory `failureClass` gate fails-fast before any row is written.
+ */
+export async function appendOperatorSignoff(input) {
+    if (!KASH_DID_PATTERN.test(input.operator.did)) {
+        throw new EscalationError("OPERATOR_DID_INVALID", "operator.did must be a valid did:kash identifier");
+    }
+    assertFailureClass(input.classification.failureClass);
+    const payloadMutation = {
+        event: "escalation.signoff",
+        suspendedStepId: input.escalation.suspendedStepId,
+        tool: input.escalation.toolName,
+        failureClass: input.classification.failureClass,
+        failureTag: input.classification.failureTag,
+    };
+    const { previousBlockHash, nextStepIndex } = await resolvePreviousBlockHash(input.ledgerStore, input.sessionId);
+    const signature = await signLedgerBlock({ sessionId: input.sessionId, stepIndex: nextStepIndex, actorDid: input.operator.did, previousBlockHash, payloadMutation }, input.operator.privateKey);
+    const block = await input.forensicLedger.appendTransitionLog({
+        sessionId: input.sessionId,
+        stepIndex: nextStepIndex,
+        actorDid: input.operator.did,
+        actorClass: "OPERATOR_ADMIN",
+        payloadMutation,
+        signature,
+    });
+    const classification = await buildSignedClassification(input.classification, input.operator, {
+        escalationId: input.escalation.escalationId ?? null,
+        signoffLedgerStepIndex: block.stepIndex,
+    });
+    await input.exceptionClassificationStore.append(classification);
+    return { stepIndex: block.stepIndex, classification };
+}
+function toSignedEvent(body, sig) {
+    // The envelope's signatures were minted with `encoding: "hex"` + a `kid`; the
+    // neuron type marks both optional, so default them for identity-core's verifier.
+    return {
+        header: {},
+        body,
+        signature: { alg: sig.alg, sig: sig.sig, dst: sig.dst, encoding: sig.encoding ?? "hex", kid: sig.kid ?? "" },
+    };
+}
+/**
+ * CRYPTOGRAPHICALLY verify a two-key human-approval envelope before a suspended
+ * run may resume (audit r1 F1). The security-critical check is the OPERATOR
+ * (invoker) signature over `stripDerivedFields(challenge)` under a key the host
+ * does NOT hold — so the host cannot forge human judgment by merely PRESENTING an
+ * envelope. Also re-checks: the AGENT attestation, the two kids differ, the DST is
+ * the handshake DST, the proposed tool matches, and (optionally) the challenge
+ * has not expired. Returns `{ok:false, reason}` on any failure — never throws.
+ */
+export async function verifyApprovalEnvelope(input) {
+    const { envelope, agentPublicKey, operatorPublicKey } = input;
+    const challenge = envelope.challenge;
+    const agentAttestation = challenge.agentAttestation;
+    const invokerSignature = envelope.invokerSignature;
+    const agentKid = agentAttestation?.kid;
+    const invokerKid = invokerSignature?.kid;
+    if (typeof agentKid !== "string" || typeof invokerKid !== "string")
+        return { ok: false, reason: "MISSING_SIGNATURE_KID" };
+    // Two-key: the operator key is SEPARATE from the agent key the host holds.
+    if (agentKid === invokerKid)
+        return { ok: false, reason: "KEYS_NOT_DISTINCT" };
+    if (input.expectedToolName !== undefined && challenge.proposedAction.toolName !== input.expectedToolName) {
+        return { ok: false, reason: "TOOL_MISMATCH" };
+    }
+    if (agentAttestation.dst !== NEURON_DST.HANDSHAKE || invokerSignature.dst !== NEURON_DST.HANDSHAKE) {
+        return { ok: false, reason: "WRONG_DST" };
+    }
+    if (input.nowMs !== undefined) {
+        const expiresMs = Date.parse(challenge.expiresAt);
+        if (Number.isFinite(expiresMs) && input.nowMs > expiresMs)
+            return { ok: false, reason: "EXPIRED" };
+    }
+    const signable = stripDerivedFields(challenge);
+    const agentOk = await verifyEvent(toSignedEvent(signable, agentAttestation), agentPublicKey);
+    if (!agentOk)
+        return { ok: false, reason: "AGENT_ATTESTATION_INVALID" };
+    // SECURITY-CRITICAL: the operator signed the SAME stripped body with the key
+    // the host cannot mint. This is what makes "the host cannot forge human
+    // judgment" literally true at RESUME time (not just at build time).
+    const operatorOk = await verifyEvent(toSignedEvent(signable, invokerSignature), operatorPublicKey);
+    if (!operatorOk)
+        return { ok: false, reason: "OPERATOR_SIGNATURE_INVALID" };
+    return { ok: true, reason: null };
+}
+/** One-way claim guard — an escalation/resume key may be claimed AT MOST ONCE,
+ *  so a retried resume can't double-execute a money-moving tool. In-memory
+ *  (single process); a durable CAS is a venture concern. */
+export class ResumeGuard {
+    claimed = new Set();
+    /** Claim `escalationKey`. Throws `EscalationError("RESUME_ALREADY_CLAIMED")`
+     *  if already claimed — the throw is the defense. */
+    claim(escalationKey) {
+        if (this.claimed.has(escalationKey)) {
+            throw new EscalationError("RESUME_ALREADY_CLAIMED", `resume key '${escalationKey}' was already claimed — refusing to re-execute`, { escalationKey });
+        }
+        this.claimed.add(escalationKey);
+    }
+    isClaimed(escalationKey) {
+        return this.claimed.has(escalationKey);
+    }
+}
+//# sourceMappingURL=escalation.js.map

package/dist/runtime/escalation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"escalation.js","sourceRoot":"","sources":["../../src/runtime/escalation.ts"],"names":[],"mappings":"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"}

package/dist/runtime/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./dispatcher";
+export * from "./runner";
+export * from "./escalation";
+export type { ToolManifest, TaskDAG, AgenticSpec } from "@kashscript/neuron/schemas";
+export type { LLMProvider, DispatchInput, DispatchResult, StepOutcome } from "@kashscript/neuron/kernel";
+export type { SignedActionEnvelope, ToolCall } from "@kashscript/neuron/handshake";
+//# sourceMappingURL=index.d.ts.map

package/dist/runtime/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/runtime/index.ts"],"names":[],"mappings":"AAMA,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAG7B,YAAY,EAAE,YAAY,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AACrF,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AACzG,YAAY,EAAE,oBAAoB,EAAE,QAAQ,EAAE,MAAM,8BAA8B,CAAC"}

package/dist/runtime/index.js

@@ -0,0 +1,9 @@
+// @kashscript/hudhud/runtime — the accountable execution runtime: the neuron
+// tool dispatcher (inline signed ledger append per tool call), the work-item
+// runner (owns the neuron DAGExecutor lifecycle), and the two-key escalation
+// mechanic. Ventures import hudhud + define tool bindings; they never touch raw
+// neuron (ECOSYSTEM #12). The SPI types ventures implement are re-exported here.
+export * from "./dispatcher";
+export * from "./runner";
+export * from "./escalation";
+//# sourceMappingURL=index.js.map

package/dist/runtime/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/runtime/index.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,6EAA6E;AAC7E,6EAA6E;AAC7E,gFAAgF;AAChF,iFAAiF;AAEjF,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC"}

package/dist/runtime/runner.d.ts

@@ -0,0 +1,78 @@
+import type { LLMProvider, StepOutcome } from "@kashscript/neuron/kernel";
+import type { SignedActionEnvelope, ToolCall } from "@kashscript/neuron/handshake";
+import type { AgenticSpec, ResourceQuotas, TaskDAG } from "@kashscript/neuron/schemas";
+import type { McpClientPoolManager } from "../mcp";
+import type { ForensicLedgerService } from "../ledger/writer";
+import type { NeuronToolBinding } from "./dispatcher";
+import type { ResumeGuard } from "./escalation";
+export type { NeuronToolBinding } from "./dispatcher";
+/** The three TERMINAL delivery statuses a single executor run can produce. */
+export type RunTerminalStatus = "DELIVERED" | "ESCALATED" | "FAILED";
+export interface RunBudget {
+    readonly maxToolCalls?: number;
+    readonly maxWallClockMs?: number;
+    readonly costCeilingUsdMicros?: number;
+}
+export interface WorkItemRunInput {
+    readonly sessionId: string;
+    readonly dag: TaskDAG;
+    readonly bindings: ReadonlyMap<string, NeuronToolBinding>;
+    readonly llm?: LLMProvider;
+    readonly budget?: RunBudget;
+}
+export interface WorkItemRunResult {
+    readonly status: RunTerminalStatus;
+    readonly outcome: Record<string, unknown>;
+    readonly escalation?: {
+        readonly suspendedStepId: string;
+        readonly pendingToolName?: string;
+        readonly pendingCall?: ToolCall;
+        readonly priorOutputs: ReadonlyMap<string, unknown>;
+    };
+    readonly failure?: {
+        readonly failedStepId: string;
+        readonly reason: string;
+    };
+    readonly stepOutcomes: readonly StepOutcome[];
+}
+export interface WorkItemResumeInput {
+    readonly sessionId: string;
+    readonly dag: TaskDAG;
+    readonly bindings: ReadonlyMap<string, NeuronToolBinding>;
+    readonly priorOutputs: ReadonlyMap<string, unknown>;
+    readonly envelope: SignedActionEnvelope;
+    /** The AGENT public key (host's own key) that attested the challenge. */
+    readonly agentPublicKey: Uint8Array;
+    /** The OPERATOR public key — the SEPARATE human key that signed off. */
+    readonly operatorPublicKey: Uint8Array;
+    /** Optional one-way replay guard; the resume is claimed under the challenge nonce. */
+    readonly resumeGuard?: ResumeGuard;
+    /** Optional wall-clock (ms) — when given, an expired challenge is rejected. */
+    readonly nowMs?: number;
+    readonly llm?: LLMProvider;
+    readonly budget?: RunBudget;
+}
+export interface WorkItemRunnerDeps {
+    readonly mcpClientPool: McpClientPoolManager;
+    readonly forensicLedger: ForensicLedgerService;
+}
+export declare class WorkItemRunner {
+    private readonly deps;
+    constructor(deps: WorkItemRunnerDeps);
+    run(input: WorkItemRunInput): Promise<WorkItemRunResult>;
+    /** Resume a previously-ESCALATED run with the human-approved envelope. audit r1
+     *  F1/F9: the envelope is CRYPTOGRAPHICALLY verified (two-key: operator signature
+     *  under a key the host cannot mint) and the resume is claimed once under the
+     *  challenge nonce — a run can never resume on envelope PRESENCE alone. */
+    resume(input: WorkItemResumeInput): Promise<WorkItemRunResult>;
+    private executeAndMap;
+}
+/** ResourceQuotas the budgeter enforces for one run (generous defaults +
+ *  caller overrides). Branded-NSID lexicon fields are opaque placeholders the
+ *  executor never dereferences at runtime; the cast localises the brand erasure. */
+export declare function buildRunnerQuotas(budget?: RunBudget): ResourceQuotas;
+/** The placeholder AgenticSpec the ExecutionContext requires. The executor
+ *  reads it only through a Critic, which the runtime does not wire — so an
+ *  identity-only placeholder is correct. Single localised cast. */
+export declare function buildPlaceholderSpec(sessionId: string): AgenticSpec;
+//# sourceMappingURL=runner.d.ts.map

package/dist/runtime/runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../src/runtime/runner.ts"],"names":[],"mappings":"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"}

package/dist/runtime/runner.js

@@ -0,0 +1,145 @@
+// ============================================================================
+// @kashscript/hudhud/runtime — WorkItemRunner
+// ----------------------------------------------------------------------------
+// The run-loop driver for ONE work-item's compiled TaskDAG: builds a
+// NeuronToolDispatcher over the session (a signed row per tool dispatch),
+// constructs a neuron DAGExecutor (dispatcher + PermissionGate + optional LLM),
+// runs the DAG, and MAPS the terminal ExecutionResult onto a delivery status
+// (DELIVERED / ESCALATED / FAILED). Pure (DAG in → status out); does not touch
+// persistence. Ported from the oreoasis-core-host engine (M5); telemetry
+// dropped, placeholder identity/lexicon names neutralized.
+// ============================================================================
+import { DAGExecutor, ResourceBudgeter } from "@kashscript/neuron/kernel";
+import { PermissionGate } from "@kashscript/neuron/handshake";
+import { NeuronToolDispatcher } from "./dispatcher";
+import { verifyApprovalEnvelope } from "./escalation";
+export class WorkItemRunner {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    async run(input) {
+        return this.executeAndMap({
+            sessionId: input.sessionId,
+            dag: input.dag,
+            bindings: input.bindings,
+            ...(input.llm ? { llm: input.llm } : {}),
+            ...(input.budget ? { budget: input.budget } : {}),
+        });
+    }
+    /** Resume a previously-ESCALATED run with the human-approved envelope. audit r1
+     *  F1/F9: the envelope is CRYPTOGRAPHICALLY verified (two-key: operator signature
+     *  under a key the host cannot mint) and the resume is claimed once under the
+     *  challenge nonce — a run can never resume on envelope PRESENCE alone. */
+    async resume(input) {
+        const toolName = input.envelope.challenge.proposedAction.toolName;
+        const verdict = await verifyApprovalEnvelope({
+            envelope: input.envelope,
+            agentPublicKey: input.agentPublicKey,
+            operatorPublicKey: input.operatorPublicKey,
+            expectedToolName: toolName,
+            ...(input.nowMs !== undefined ? { nowMs: input.nowMs } : {}),
+        });
+        if (!verdict.ok) {
+            return { status: "FAILED", outcome: {}, failure: { failedStepId: "<resume>", reason: `approval-envelope invalid: ${verdict.reason}` }, stepOutcomes: [] };
+        }
+        // F9: one-way claim keyed by the challenge nonce so a retried/at-least-once
+        // resume can't re-fire the restricted tool.
+        if (input.resumeGuard !== undefined) {
+            try {
+                input.resumeGuard.claim(input.envelope.challenge.nonce);
+            }
+            catch {
+                return { status: "FAILED", outcome: {}, failure: { failedStepId: "<resume>", reason: "resume already claimed (replay refused)" }, stepOutcomes: [] };
+            }
+        }
+        return this.executeAndMap({
+            sessionId: input.sessionId,
+            dag: input.dag,
+            bindings: input.bindings,
+            priorOutputs: input.priorOutputs,
+            envelopesByToolName: new Map([[toolName, input.envelope]]),
+            ...(input.llm ? { llm: input.llm } : {}),
+            ...(input.budget ? { budget: input.budget } : {}),
+        });
+    }
+    async executeAndMap(args) {
+        const toolDispatcher = new NeuronToolDispatcher({
+            mcpClientPool: this.deps.mcpClientPool,
+            forensicLedger: this.deps.forensicLedger,
+            sessionId: args.sessionId,
+            bindings: args.bindings,
+        });
+        // onEvent is telemetry only — the signed rows land awaited in the dispatcher.
+        const onEvent = (_e) => { };
+        const executor = new DAGExecutor({
+            toolDispatcher,
+            permissionGate: new PermissionGate(),
+            ...(args.llm ? { llm: args.llm } : {}),
+            onEvent,
+        });
+        const priorOutputs = new Map();
+        const ctx = {
+            spec: buildPlaceholderSpec(args.sessionId),
+            budgeter: new ResourceBudgeter(buildRunnerQuotas(args.budget)),
+            onNodeOutput: (stepId, output) => {
+                priorOutputs.set(stepId, output);
+            },
+            ...(args.priorOutputs ? { priorOutputs: args.priorOutputs } : {}),
+            ...(args.envelopesByToolName ? { envelopesByToolName: args.envelopesByToolName } : {}),
+        };
+        const result = await executor.execute(args.dag, ctx);
+        switch (result.kind) {
+            case "completed":
+                return { status: "DELIVERED", outcome: Object.fromEntries(result.outputs), stepOutcomes: result.outcomes };
+            case "suspended": {
+                if (result.reason === "awaiting-signature") {
+                    return {
+                        status: "ESCALATED",
+                        outcome: {},
+                        escalation: {
+                            suspendedStepId: result.stepId,
+                            ...(result.pendingCall ? { pendingCall: result.pendingCall, pendingToolName: result.pendingCall.toolName } : {}),
+                            priorOutputs,
+                        },
+                        stepOutcomes: result.outcomes,
+                    };
+                }
+                return { status: "FAILED", outcome: {}, failure: { failedStepId: result.stepId, reason: `suspended:${result.reason}` }, stepOutcomes: result.outcomes };
+            }
+            case "failed":
+                return { status: "FAILED", outcome: {}, failure: { failedStepId: result.failedStepId, reason: result.reason }, stepOutcomes: result.outcomes };
+        }
+    }
+}
+/** ResourceQuotas the budgeter enforces for one run (generous defaults +
+ *  caller overrides). Branded-NSID lexicon fields are opaque placeholders the
+ *  executor never dereferences at runtime; the cast localises the brand erasure. */
+export function buildRunnerQuotas(budget) {
+    const maxToolCalls = budget?.maxToolCalls ?? 100;
+    const maxWallClockMs = budget?.maxWallClockMs ?? 600_000;
+    const costCeilingUsdMicros = budget?.costCeilingUsdMicros ?? 1_000_000_000;
+    const nsid = (s) => s;
+    const quotas = {
+        maxStepsPerDAG: 100,
+        maxInputTokensPerStep: 100_000,
+        maxOutputTokensPerStep: 100_000,
+        maxToolCallsPerDAG: maxToolCalls,
+        maxWallClockMs,
+        judges: { threshold: 2, hallucinationCeiling: 0.5, personaCosine: 0.5, maxJudgeRetries: 1, feedbackSummariseTokens: 256 },
+        modelRouter: { costCeilingUsdMicros, latencyCeilingMs: maxWallClockMs, respectGrantTTL: false },
+        lexicons: { intent: nsid("kash.run.intent"), thought: nsid("kash.run.thought"), output: nsid("kash.run.output"), extras: [], trustedPublishers: [] },
+        compression: { granularity: "moderate", triggerThresholdFraction: 0.2, maxFactArtifactLength: 4000, maxFactArtifacts: 64, preserveEnvelopes: true },
+    };
+    return quotas;
+}
+/** The placeholder AgenticSpec the ExecutionContext requires. The executor
+ *  reads it only through a Critic, which the runtime does not wire — so an
+ *  identity-only placeholder is correct. Single localised cast. */
+export function buildPlaceholderSpec(sessionId) {
+    const spec = {
+        identity: { invoker: "did:kash:agent:kash-runtime", name: `work-item-runner:${sessionId}`, version: "0.0.0", kind: "kash-neuron-agentic-spec/1" },
+    };
+    return spec;
+}
+//# sourceMappingURL=runner.js.map