@retinue/agentkit 0.1.0

package/dist/hitl/service.d.ts

@@ -0,0 +1,221 @@
+/**
+ * Human-in-the-loop services — `docs/04-durable-runtime-and-hitl.md` → Questions & Approvals.
+ *
+ * `ask`/`request` persist a durable interaction (surviving restart/deploy) and pause the run into
+ * `waiting-for-question` / `waiting-for-approval`. `answer`/`decide` record the outcome idempotently
+ * and queue the continuation exactly once — a duplicate call is a safe no-op, so a run never resumes
+ * twice. An approval stores the exact normalized tool name + input. The `ApprovalGate` makes the
+ * approval unbypassable: a policy-classified tool cannot execute directly without either a standing
+ * grant or a one-time approval a human has decided and the runtime has claimed.
+ *
+ * **This file is the *what*, not the *when*.** Requesting, deciding and gating live here; the run path
+ * that raises an approval on a refusal and executes the stored input on resumption is
+ * `./approved-execution.ts`, and the engine calls it (`../agents/engine.ts`). That path did not
+ * exist until the loop was wired, and this docstring described a resumption nothing performed.
+ */
+import type { ExecutionContext } from "../core/context.js";
+import type { QuestionAnswer } from "../core/content-parts.js";
+import type { ConversationId, InteractionId, RunId, TenantId } from "../core/ids.js";
+import { AgentPlatformError } from "../core/errors.js";
+import type { ApprovalGrantStore, InteractionStore, RunStore } from "../persistence/index.js";
+import type { JobDispatcher } from "../runtime/index.js";
+import type { ApprovalDecision, ApprovalGrant, PendingApproval, PendingQuestion } from "./index.js";
+type Clock = () => string;
+type IdFactory = () => string;
+/**
+ * One question the agent asks a person.
+ *
+ * `options` + `multiple` + `allowOther` cover the three shapes a UI actually needs: pick one, pick several, or
+ * write your own — and any combination. Previously only `options` existed, so a client could not tell a choice
+ * from a hint and had to guess.
+ */
+export type QuestionSpec = {
+    readonly key: string;
+    readonly prompt: string;
+    /** Suggested answers. Absent means free text only. */
+    readonly options?: readonly string[];
+    /** More than one may be chosen. A multi-select answer is an array. */
+    readonly multiple?: boolean;
+    /** An answer not on the list is accepted. Defaults to true when there are no options, false when there are. */
+    readonly allowOther?: boolean;
+};
+/** Re-exported from `core`, where it lives so the port and this service can share it without a cycle. */
+export type { QuestionAnswer } from "../core/content-parts.js";
+export declare const createQuestionService: (deps: {
+    readonly interactions: InteractionStore;
+    readonly dispatcher: JobDispatcher;
+    /**
+     * The run store, so answering can put the run back to `queued` (#144).
+     *
+     * Optional only so an existing caller keeps compiling; without it the resume enqueues a run the worker cannot
+     * claim, and the run waits forever. See `resumeRun` below.
+     */
+    readonly runs?: RunStore;
+    readonly clock?: Clock;
+    readonly idFactory?: IdFactory;
+}) => {
+    /**
+     * Persist a pending question. The run is paused into `waiting-for-question` by the worker.
+     *
+     * That last sentence was aspirational until #163: the worker does pause on a `question.requested` event,
+     * but nothing emitted one, so a tool that called `ask` had its question stored and the run ran on to
+     * completion. See `questionPending` below for the signal that closes the loop.
+     */
+    ask(context: ExecutionContext, runId: RunId, questions: readonly QuestionSpec[]): Promise<PendingQuestion>;
+    /**
+     * The question a run is parked on, or null — the read side of `answer` (#163).
+     *
+     * The service had `ask` and `answer` and no way to *look at* what was asked, so the only client that could
+     * render a picker was one that had also raised the question and kept it in memory. A worker raises it and a
+     * browser renders it, which are different processes; the browser had the interaction id from the event and
+     * nothing else, and drew an empty text box.
+     */
+    pending(input: {
+        tenantId: TenantId;
+        runId: RunId;
+    }): Promise<PendingQuestion | null>;
+    /**
+     * The answer a resumed run has to tell the model about — #163.
+     *
+     * Returns null when nothing was asked, or when the answer was already part of an earlier turn's history:
+     * both mean "say nothing new". The engine calls this on resume, the way it calls `approvals.resume`.
+     */
+    answered(input: {
+        tenantId: TenantId;
+        runId: RunId;
+    }): Promise<PendingQuestion | null>;
+    /**
+     * Record answers and queue the continuation — exactly once. A second answer to the same
+     * interaction is a no-op and does NOT re-enqueue, so the run never resumes twice.
+     */
+    answer(input: TenantScopeInput & {
+        interactionId: InteractionId;
+        runId: RunId;
+        answers: Readonly<Record<string, QuestionAnswer>>;
+    }): Promise<{
+        resumed: boolean;
+    }>;
+};
+type TenantScopeInput = {
+    tenantId: TenantId;
+};
+export type ApprovalRequest = {
+    readonly toolName: string;
+    readonly normalizedInput: unknown;
+    readonly riskCategory: string;
+    readonly summary: string;
+    readonly estimatedCostMinorUnits?: number;
+    readonly expiresAt: string;
+    readonly idempotencyKey: string;
+};
+/**
+ * Decisions that authorize the approved call to run.
+ *
+ * A whitelist rather than `!== "deny"`: a decision added later — a deferral, an escalation — would
+ * read as permission under the negative form, which is the wrong direction to be wrong in.
+ */
+export declare const ALLOW_DECISIONS: readonly ["allow-once", "allow-conversation", "allow-always"];
+export declare const isAllowDecision: (decision: ApprovalDecision | undefined) => boolean;
+export declare const createApprovalService: (deps: {
+    readonly interactions: InteractionStore;
+    readonly grants: ApprovalGrantStore;
+    readonly dispatcher: JobDispatcher;
+    /** As on `createQuestionService`: without it the resumed run is never claimable. See `resumeRun`. */
+    readonly runs?: RunStore;
+    readonly clock?: Clock;
+    readonly idFactory?: IdFactory;
+}) => {
+    /** Persist a pending approval storing the exact normalized tool + input. Run pauses to waiting. */
+    request(context: ExecutionContext, runId: RunId, req: ApprovalRequest): Promise<PendingApproval>;
+    /**
+     * The approval a run is parked on, or null — the read side of `decide` (#163).
+     *
+     * Same reasoning as `pending` on the question service: the worker raises it, a browser renders it, and the
+     * browser had only the interaction id from the event. Without this the card could not name the tool it was
+     * asking about, and an approval prompt that says "run a tool?" is one people learn to click through.
+     */
+    pending(input: {
+        tenantId: TenantId;
+        runId: RunId;
+    }): Promise<PendingApproval | null>;
+    /**
+     * Record a decision (once), issue a standing grant for allow-conversation/allow-always, and queue
+     * the continuation exactly once. The resumed run executes the *stored* normalized input from the
+     * pending approval — never a regenerated one; see `./approved-execution.ts`.
+     *
+     * `allow-once` deliberately issues **no grant**. A grant is standing by definition, so minting one
+     * for a one-time decision would hand over authority the human did not give. Its single execution is
+     * claimed off the interaction instead (`InteractionStore.claimApproval`).
+     */
+    decide(input: TenantScopeInput & {
+        interactionId: InteractionId;
+        runId: RunId;
+        conversationId?: ConversationId;
+        decision: ApprovalDecision;
+    }): Promise<{
+        resumed: boolean;
+        grant?: ApprovalGrant;
+    }>;
+};
+/**
+ * A single approved execution, presented at the moment of the call.
+ *
+ * The ticket is just the interaction id, and it is **not** a credential — the gate below verifies it
+ * against the stored interaction rather than believing it. That is deliberate: the alternative to a
+ * ticket was issuing a grant for `allow-once`, and a grant is standing by definition, so a one-time
+ * decision would have silently become a permanent one.
+ *
+ * Per-call rather than carried on the `ExecutionContext`: a context is reused for every call in a
+ * turn, so an approval living on it would authorise all of them.
+ */
+export type OneTimeApproval = {
+    readonly interactionId: InteractionId | string;
+};
+/**
+ * The gate that makes approval unbypassable. A policy-classified tool (`approvalPolicy` other than
+ * `never`, or an external/destructive effect under `policy`) may only execute directly when a
+ * standing grant covers it, or when the call presents a one-time approval a human has decided and the
+ * runtime has claimed.
+ *
+ * Both paths fail closed. A tool with no grant and no ticket is refused; a ticket presented with no
+ * `interactions` store to check it against is refused too, because an unwired dependency must never
+ * be the reason something was allowed.
+ */
+export declare const createApprovalGate: (deps: {
+    readonly grants: ApprovalGrantStore;
+    /**
+     * Where one-time approvals are verified. Optional so a caller that only uses standing grants need
+     * not wire it — with it absent, every ticket is refused rather than trusted.
+     */
+    readonly interactions?: InteractionStore;
+    readonly clock?: Clock;
+}) => {
+    isAllowed(context: ExecutionContext, tool: {
+        readonly name: string;
+        readonly category: string;
+        readonly approvalPolicy: "never" | "policy" | "always";
+    }, oneTime?: OneTimeApproval): Promise<boolean>;
+};
+export type ApprovalGate = ReturnType<typeof createApprovalGate>;
+/**
+ * The signal a tool raises to park its run on a question — #163.
+ *
+ * A tool cannot pause a run by itself, and it must not block waiting for a person: a delegate that awaited a
+ * human reply would hold a worker slot for as long as someone takes to read, which is the entire thing the
+ * durable runtime exists to avoid. So the tool stores the question, throws this, and returns control.
+ *
+ * The engine recognises the `question_pending` code, tells the model the run is parked, and emits
+ * `question.requested` — the event the worker turns into `waiting-for-question`. Exactly the path an approval
+ * takes, which is the point: the two halves of "ask a human something" should not work differently.
+ *
+ * Thrown rather than returned because it has to survive the tool registry, which flattens a delegate's throw
+ * into a `ToolResult` error. A distinguishing code is what makes that flattening lossless.
+ */
+export declare const questionPending: (question: {
+    readonly id: InteractionId;
+}) => AgentPlatformError;
+/** True when a refusal is a parked question rather than a failure. Used by the engine; exported for hosts. */
+export declare const isQuestionPending: (error: {
+    readonly code: string;
+}) => boolean;
+//# sourceMappingURL=service.d.ts.map

package/dist/hitl/service.js

@@ -0,0 +1,268 @@
+/**
+ * Human-in-the-loop services — `docs/04-durable-runtime-and-hitl.md` → Questions & Approvals.
+ *
+ * `ask`/`request` persist a durable interaction (surviving restart/deploy) and pause the run into
+ * `waiting-for-question` / `waiting-for-approval`. `answer`/`decide` record the outcome idempotently
+ * and queue the continuation exactly once — a duplicate call is a safe no-op, so a run never resumes
+ * twice. An approval stores the exact normalized tool name + input. The `ApprovalGate` makes the
+ * approval unbypassable: a policy-classified tool cannot execute directly without either a standing
+ * grant or a one-time approval a human has decided and the runtime has claimed.
+ *
+ * **This file is the *what*, not the *when*.** Requesting, deciding and gating live here; the run path
+ * that raises an approval on a refusal and executes the stored input on resumption is
+ * `./approved-execution.ts`, and the engine calls it (`../agents/engine.ts`). That path did not
+ * exist until the loop was wired, and this docstring described a resumption nothing performed.
+ */
+import { asId } from "../core/ids.js";
+import { AgentPlatformError } from "../core/errors.js";
+const defaults = (clock, idFactory) => ({
+    clock: clock ?? (() => new Date().toISOString()),
+    newId: idFactory ?? (() => `int-${Math.round(Math.random() * 1e9)}`),
+});
+export const createQuestionService = (deps) => {
+    const { clock, newId } = defaults(deps.clock, deps.idFactory);
+    return {
+        /**
+         * Persist a pending question. The run is paused into `waiting-for-question` by the worker.
+         *
+         * That last sentence was aspirational until #163: the worker does pause on a `question.requested` event,
+         * but nothing emitted one, so a tool that called `ask` had its question stored and the run ran on to
+         * completion. See `questionPending` below for the signal that closes the loop.
+         */
+        async ask(context, runId, questions) {
+            const question = {
+                id: asId(newId()),
+                tenantId: context.tenantId,
+                runId,
+                questions,
+                createdAt: clock(),
+            };
+            await deps.interactions.createQuestion({ tenantId: context.tenantId, question });
+            return question;
+        },
+        /**
+         * The question a run is parked on, or null — the read side of `answer` (#163).
+         *
+         * The service had `ask` and `answer` and no way to *look at* what was asked, so the only client that could
+         * render a picker was one that had also raised the question and kept it in memory. A worker raises it and a
+         * browser renders it, which are different processes; the browser had the interaction id from the event and
+         * nothing else, and drew an empty text box.
+         */
+        async pending(input) {
+            return deps.interactions.findPendingQuestion({ tenantId: input.tenantId, runId: input.runId });
+        },
+        /**
+         * The answer a resumed run has to tell the model about — #163.
+         *
+         * Returns null when nothing was asked, or when the answer was already part of an earlier turn's history:
+         * both mean "say nothing new". The engine calls this on resume, the way it calls `approvals.resume`.
+         */
+        async answered(input) {
+            return deps.interactions.findAnsweredQuestion({ tenantId: input.tenantId, runId: input.runId });
+        },
+        /**
+         * Record answers and queue the continuation — exactly once. A second answer to the same
+         * interaction is a no-op and does NOT re-enqueue, so the run never resumes twice.
+         */
+        async answer(input) {
+            const { alreadyResolved } = await deps.interactions.answerQuestion({
+                tenantId: input.tenantId,
+                interactionId: input.interactionId,
+                answers: input.answers,
+                at: clock(),
+            });
+            if (alreadyResolved)
+                return { resumed: false };
+            await resumeRun(deps, { tenantId: input.tenantId, runId: input.runId, at: clock() });
+            return { resumed: true };
+        },
+    };
+};
+/**
+ * Put a paused run back on the queue — status *then* job.
+ *
+ * **A bug the load harness found (#144).** `decide` and `answer` used to enqueue and nothing else. But
+ * `RunStore.claim` accepts only `queued` or a `running` run with an expired lease, and pausing a run for a human
+ * leaves it in `waiting-for-approval` — so the enqueued job was handed to a worker, the claim matched no row, the
+ * run was skipped, and it waited forever. Sixty-five of a hundred and sixty runs in one load step, silently.
+ *
+ * It survived because the unit tests assert `resumed: true` and that a job was enqueued, which was exactly true
+ * and not the same as the run resuming. Only driving a real worker against a real store showed it.
+ *
+ * The transition comes **first**: enqueueing before it lets a worker pick the job up while the run is still
+ * paused, fail the claim, and drop the only job that would have resumed it.
+ *
+ * `workerId` is the actor's name rather than a worker's. `transition` guards on `claimedBy`, and pausing a run
+ * releases the claim — so the field is unconstrained here and the honest value is who is doing this.
+ */
+const resumeRun = async (deps, input) => {
+    await deps.runs?.transition({
+        tenantId: input.tenantId,
+        id: input.runId,
+        workerId: "hitl",
+        to: "queued",
+        now: input.at,
+    });
+    await deps.dispatcher.enqueueRun({ tenantId: input.tenantId, runId: input.runId });
+};
+/**
+ * Decisions that authorize the approved call to run.
+ *
+ * A whitelist rather than `!== "deny"`: a decision added later — a deferral, an escalation — would
+ * read as permission under the negative form, which is the wrong direction to be wrong in.
+ */
+export const ALLOW_DECISIONS = ["allow-once", "allow-conversation", "allow-always"];
+export const isAllowDecision = (decision) => decision !== undefined && ALLOW_DECISIONS.includes(decision);
+const grantScopeFor = (decision) => decision === "allow-conversation" ? "conversation" : decision === "allow-always" ? "tenant" : null;
+export const createApprovalService = (deps) => {
+    const { clock, newId } = defaults(deps.clock, deps.idFactory);
+    return {
+        /** Persist a pending approval storing the exact normalized tool + input. Run pauses to waiting. */
+        async request(context, runId, req) {
+            const approval = {
+                id: asId(newId()),
+                tenantId: context.tenantId,
+                runId,
+                toolName: req.toolName,
+                normalizedInput: req.normalizedInput,
+                riskCategory: req.riskCategory,
+                summary: req.summary,
+                ...(req.estimatedCostMinorUnits === undefined ? {} : { estimatedCostMinorUnits: req.estimatedCostMinorUnits }),
+                expiresAt: req.expiresAt,
+                idempotencyKey: req.idempotencyKey,
+            };
+            await deps.interactions.createApproval({ tenantId: context.tenantId, approval });
+            return approval;
+        },
+        /**
+         * The approval a run is parked on, or null — the read side of `decide` (#163).
+         *
+         * Same reasoning as `pending` on the question service: the worker raises it, a browser renders it, and the
+         * browser had only the interaction id from the event. Without this the card could not name the tool it was
+         * asking about, and an approval prompt that says "run a tool?" is one people learn to click through.
+         */
+        async pending(input) {
+            return deps.interactions.findPendingApproval({ tenantId: input.tenantId, runId: input.runId });
+        },
+        /**
+         * Record a decision (once), issue a standing grant for allow-conversation/allow-always, and queue
+         * the continuation exactly once. The resumed run executes the *stored* normalized input from the
+         * pending approval — never a regenerated one; see `./approved-execution.ts`.
+         *
+         * `allow-once` deliberately issues **no grant**. A grant is standing by definition, so minting one
+         * for a one-time decision would hand over authority the human did not give. Its single execution is
+         * claimed off the interaction instead (`InteractionStore.claimApproval`).
+         */
+        async decide(input) {
+            const { approval, alreadyResolved } = await deps.interactions.decideApproval({
+                tenantId: input.tenantId,
+                interactionId: input.interactionId,
+                decision: input.decision,
+                at: clock(),
+            });
+            if (alreadyResolved)
+                return { resumed: false };
+            let grant;
+            const scope = grantScopeFor(input.decision);
+            // A conversation-scoped grant needs a conversationId; without one, skip the standing grant
+            // (the run still resumes once) rather than silently widening it to the whole tenant.
+            if (scope && !(scope === "conversation" && input.conversationId === undefined)) {
+                grant = {
+                    id: asId(newId()),
+                    tenantId: input.tenantId,
+                    scope,
+                    toolNameOrCategory: approval.toolName,
+                    ...(scope === "conversation" && input.conversationId !== undefined ? { conversationId: input.conversationId } : {}),
+                    grantedAt: clock(),
+                };
+                await deps.grants.grant({ tenantId: input.tenantId, grant });
+            }
+            // Both allow and deny queue a continuation; the resumed engine reads the decision and acts.
+            await resumeRun(deps, { tenantId: input.tenantId, runId: input.runId, at: clock() });
+            return grant ? { resumed: true, grant } : { resumed: true };
+        },
+    };
+};
+/**
+ * The gate that makes approval unbypassable. A policy-classified tool (`approvalPolicy` other than
+ * `never`, or an external/destructive effect under `policy`) may only execute directly when a
+ * standing grant covers it, or when the call presents a one-time approval a human has decided and the
+ * runtime has claimed.
+ *
+ * Both paths fail closed. A tool with no grant and no ticket is refused; a ticket presented with no
+ * `interactions` store to check it against is refused too, because an unwired dependency must never
+ * be the reason something was allowed.
+ */
+export const createApprovalGate = (deps) => {
+    const clock = deps.clock ?? (() => new Date().toISOString());
+    /**
+     * Whether this ticket really authorises *this* call.
+     *
+     * Every clause is a way the loop could otherwise be widened, and each is checked against what was
+     * stored at request time rather than against anything the caller supplied:
+     *
+     * - the interaction exists in this tenant — a forged or foreign id authorises nothing;
+     * - it belongs to this run, so a ticket cannot be carried into another run;
+     * - the decision is an allow — a denial can never read as permission;
+     * - the tool is the one the human saw, so an approval for `publish` cannot run `delete`;
+     * - it has been claimed. The claim is the at-most-once counter (`InteractionStore.claimApproval`),
+     *   and requiring it here is what keeps a merely *decided* approval from being executable by
+     *   anything that has not first taken the single execution it grants.
+     */
+    const oneTimeAllows = async (context, tool, oneTime) => {
+        if (!deps.interactions)
+            return false;
+        const approval = await deps.interactions.findApproval({
+            tenantId: context.tenantId,
+            interactionId: asId(String(oneTime.interactionId)),
+        });
+        if (!approval)
+            return false;
+        if (approval.runId !== context.runId)
+            return false;
+        if (approval.toolName !== tool.name)
+            return false;
+        if (!isAllowDecision(approval.decision))
+            return false;
+        return approval.consumedAt !== undefined;
+    };
+    return {
+        async isAllowed(context, tool, oneTime) {
+            if (tool.approvalPolicy === "never")
+                return true;
+            const now = clock();
+            const conversationId = context.conversationId;
+            const scope = { tenantId: context.tenantId, now, ...(conversationId ? { conversationId } : {}) };
+            const byName = await deps.grants.findActive({ ...scope, toolNameOrCategory: tool.name });
+            if (byName)
+                return true;
+            const byCategory = await deps.grants.findActive({ ...scope, toolNameOrCategory: tool.category });
+            if (byCategory)
+                return true;
+            return oneTime === undefined ? false : oneTimeAllows(context, tool, oneTime);
+        },
+    };
+};
+/**
+ * The signal a tool raises to park its run on a question — #163.
+ *
+ * A tool cannot pause a run by itself, and it must not block waiting for a person: a delegate that awaited a
+ * human reply would hold a worker slot for as long as someone takes to read, which is the entire thing the
+ * durable runtime exists to avoid. So the tool stores the question, throws this, and returns control.
+ *
+ * The engine recognises the `question_pending` code, tells the model the run is parked, and emits
+ * `question.requested` — the event the worker turns into `waiting-for-question`. Exactly the path an approval
+ * takes, which is the point: the two halves of "ask a human something" should not work differently.
+ *
+ * Thrown rather than returned because it has to survive the tool registry, which flattens a delegate's throw
+ * into a `ToolResult` error. A distinguishing code is what makes that flattening lossless.
+ */
+export const questionPending = (question) => new AgentPlatformError({
+    code: "question_pending",
+    message: "A question has been put to the person. The run is paused; do not retry or guess an answer.",
+    retryable: false,
+    details: { interactionId: question.id },
+});
+/** True when a refusal is a parked question rather than a failure. Used by the engine; exported for hosts. */
+export const isQuestionPending = (error) => error.code === "question_pending";
+//# sourceMappingURL=service.js.map

package/dist/idempotency/index.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Idempotency contract — `docs/04-durable-runtime-and-hitl.md`. **Frozen v1.**
+ *
+ * Every external/destructive tool call carries a key derived from tenant + run + tool-call
+ * identity. A resumed or retried call returns the original result instead of repeating the side
+ * effect — the pairing that makes Claude-style retries safe.
+ */
+import type { RunId, TenantId, ToolCallId } from "../core/ids.js";
+declare const brand: unique symbol;
+export type IdempotencyKey = string & {
+    readonly [brand]: "IdempotencyKey";
+};
+/**
+ * Pure and deterministic: the same (tenant, run, tool-call) always yields the same key, so a
+ * retry of the same logical call collides with its first attempt.
+ */
+export declare const deriveIdempotencyKey: (input: {
+    readonly tenantId: TenantId;
+    readonly runId: RunId;
+    readonly toolCallId: ToolCallId;
+}) => IdempotencyKey;
+/**
+ * A stable string for a value.
+ *
+ * Object keys are sorted, because `{a, b}` and `{b, a}` are the same arguments and must not produce
+ * two keys — the whole point of a key is that an identical call collides with itself.
+ */
+export declare const canonicalizeArgs: (value: unknown) => string;
+/**
+ * The key for a call the runtime identifies by its **arguments** rather than by a provider tool-call
+ * id (`docs/04` → Approvals, Idempotency).
+ *
+ * A resumed approval has no tool-call id to derive from: the call it executes came off a stored
+ * interaction, not out of a model stream. Two properties matter, and they pull in opposite directions.
+ * It is **run-scoped**, so "publish this" today and the same call next week do not collide — a key
+ * shared across runs would return the first result and never publish the second. And it is
+ * **argument-derived**, so within one run the same logical call collides with itself: the model
+ * re-asking for a publish it already asked for finds the same approval and the same stored result,
+ * rather than a second approval and a second publish.
+ *
+ * Derive it from *normalised* arguments. A schema that lowercases a channel would otherwise give one
+ * logical call two keys, and the second would not see the first's result.
+ */
+export declare const deriveCallIdempotencyKey: (input: {
+    readonly tenantId: TenantId;
+    readonly runId: RunId;
+    readonly toolName: string;
+    readonly args: unknown;
+}) => IdempotencyKey;
+/** Wraps a stored result so a repeated call can return it without re-executing. */
+export type IdempotentResult<T> = {
+    readonly key: IdempotencyKey;
+    /** True on the first execution; false when the stored result is returned. */
+    readonly firstSeen: boolean;
+    readonly result: T;
+};
+/** Persists and returns prior results by key. Adapter lands with persistence (#17+). */
+export interface IdempotencyStore {
+    get<T>(input: {
+        tenantId: TenantId;
+        key: IdempotencyKey;
+    }): Promise<IdempotentResult<T> | null>;
+    put<T>(input: {
+        tenantId: TenantId;
+        key: IdempotencyKey;
+        result: T;
+    }): Promise<void>;
+}
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/idempotency/index.js

@@ -0,0 +1,59 @@
+/**
+ * Idempotency contract — `docs/04-durable-runtime-and-hitl.md`. **Frozen v1.**
+ *
+ * Every external/destructive tool call carries a key derived from tenant + run + tool-call
+ * identity. A resumed or retried call returns the original result instead of repeating the side
+ * effect — the pairing that makes Claude-style retries safe.
+ */
+const brand = Symbol("IdempotencyKey");
+/**
+ * Pure and deterministic: the same (tenant, run, tool-call) always yields the same key, so a
+ * retry of the same logical call collides with its first attempt.
+ */
+export const deriveIdempotencyKey = (input) => `${input.tenantId}:${input.runId}:${input.toolCallId}`;
+/**
+ * A stable string for a value.
+ *
+ * Object keys are sorted, because `{a, b}` and `{b, a}` are the same arguments and must not produce
+ * two keys — the whole point of a key is that an identical call collides with itself.
+ */
+export const canonicalizeArgs = (value) => {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value) ?? "null";
+    if (Array.isArray(value))
+        return `[${value.map(canonicalizeArgs).join(",")}]`;
+    const entries = Object.entries(value)
+        .filter(([, v]) => v !== undefined)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${canonicalizeArgs(v)}`).join(",")}}`;
+};
+/** FNV-1a over the canonical form. Bounds the key's length without needing a crypto dependency. */
+const fnv1a = (text) => {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < text.length; i += 1) {
+        hash ^= text.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193) >>> 0;
+    }
+    return hash.toString(16).padStart(8, "0");
+};
+/**
+ * The key for a call the runtime identifies by its **arguments** rather than by a provider tool-call
+ * id (`docs/04` → Approvals, Idempotency).
+ *
+ * A resumed approval has no tool-call id to derive from: the call it executes came off a stored
+ * interaction, not out of a model stream. Two properties matter, and they pull in opposite directions.
+ * It is **run-scoped**, so "publish this" today and the same call next week do not collide — a key
+ * shared across runs would return the first result and never publish the second. And it is
+ * **argument-derived**, so within one run the same logical call collides with itself: the model
+ * re-asking for a publish it already asked for finds the same approval and the same stored result,
+ * rather than a second approval and a second publish.
+ *
+ * Derive it from *normalised* arguments. A schema that lowercases a channel would otherwise give one
+ * logical call two keys, and the second would not see the first's result.
+ */
+export const deriveCallIdempotencyKey = (input) => deriveIdempotencyKey({
+    tenantId: input.tenantId,
+    runId: input.runId,
+    toolCallId: `${input.toolName}:${fnv1a(canonicalizeArgs(input.args))}`,
+});
+//# sourceMappingURL=index.js.map