@decidio/sdk 0.1.12 → 0.2.0

package/dist/errors.js

@@ -1,18 +1,50 @@
+const RETRYABLE_STATUS = (status) => status === 408 || status === 429 || (status >= 500 && status !== 501);
+function sideEffectNote(endpoint) {
+    if (endpoint.startsWith("/agent/confirm")) {
+        return " Your action ALREADY RAN — only its report failed. Do NOT re-run it.";
+    }
+    if (endpoint.startsWith("/agent/status")) {
+        return " This call is a read, so it changed nothing; the decision itself is unaffected.";
+    }
+    return " Nothing was routed or executed.";
+}
 export class DecidioHttpError extends Error {
     status;
     endpoint;
     body;
     retryable;
     constructor(status, endpoint, body) {
-        const terminal = status === 401 || status === 403;
+        const credential = status === 401 || status === 403;
+        const retryable = !credential && RETRYABLE_STATUS(status);
         super(`[decidio] ${endpoint} refused this call (HTTP ${status})` +
-            (terminal
-                ? ` — the credential was rejected. The agent token may have expired or been revoked (re-running \`init\` for the same agent revokes the previous one). Mint a fresh one: npx @decidio/sdk init <agent-name>, then restart this process. Nothing was routed or executed.`
-                : ` — this looks transient; retrying is safe (a retry creates a NEW request and can never double-execute). Nothing was routed or executed.`));
+            (credential
+                ? ` — the credential was rejected. The agent token may have expired or been revoked (re-running \`init\` for the same agent revokes the previous one). Mint a fresh one: npx @decidio/sdk init <agent-name>, then restart this process.`
+                : retryable
+                    ? ` — this looks transient; retrying is safe (a retry creates a NEW request and can never double-execute).`
+                    : ` — the server refused the request itself, so retrying it unchanged will fail the same way. Fix the request (or the decision it names) first.`) +
+            sideEffectNote(endpoint));
         this.status = status;
         this.endpoint = endpoint;
         this.body = body;
         this.name = "DecidioHttpError";
-        this.retryable = !terminal;
+        this.retryable = retryable;
+    }
+}
+export function decisionIdProblem(raw) {
+    if (typeof raw !== "string")
+        return `it is ${raw === null ? "null" : typeof raw}, not a string`;
+    if (raw.length === 0)
+        return "it is empty";
+    if (raw.trim().length === 0)
+        return "it is only whitespace";
+    if (raw !== raw.trim())
+        return "it has leading or trailing whitespace (ids are used verbatim in URLs, filenames and audit lines — this SDK will not silently trim one)";
+    for (const ch of raw) {
+        const cp = ch.codePointAt(0);
+        if (cp < 0x20 || cp === 0x7f)
+            return "it contains control characters";
     }
+    if (raw.length > 256)
+        return `it is ${raw.length} characters long (limit 256)`;
+    return null;
 }

package/dist/evidence.d.ts

@@ -17,6 +17,25 @@ export interface EvidenceOutcome {
      *  proof VERIFIED (C3, 0.1.12 — this field used to be read off the wire and discarded, so a
      *  failed attestation was invisible to every client door). */
     executionReportVerified?: boolean;
+    /** WHY the attestation did not verify, verbatim from the gate (unknown did, expired proof,
+     *  burnt nonce, payload mismatch). It was folded into `diagnostic` prose and nowhere else, so a
+     *  caller who wanted to BRANCH on the reason — retry vs re-register vs alert — had to regex an
+     *  English sentence. Same rule as the typed HTTP errors: give callers the fact, not a string to
+     *  parse. */
+    executionReportReason?: string;
+    /** Whether re-sending this report could succeed. False for a refusal the server will repeat
+     *  (an unrecognised tier, a denied success flag); true for a transport or availability failure.
+     *  Undefined when the report WAS recorded and there is nothing to retry. */
+    confirmationRetryable?: boolean;
+    /** Whether the reported value reached durable storage, so `reconfirm()` can re-send it. On the
+     *  inline path this is false by construction — nothing is parked — which is exactly why an
+     *  inline caller needs to see the outcome at the call site rather than in a log line. */
+    reportJournalled?: boolean;
+    /** Set when the caller's `evidence` mapper (or the canonical model) rejected the return value,
+     *  so an EMPTY captured response was reported. The execution is recorded; its evidence is not.
+     *  This was previously a console.warn and nothing else — invisible to the code that could
+     *  actually fix it. */
+    evidenceError?: string;
 }
 /** The SERVER's rule for `application_confirmed`, restated here exactly as implemented so this
  *  explanation can never drift from it: the captured response must carry a RECORD ID

package/dist/evidence.js

@@ -20,19 +20,20 @@ export function describeTierGap(capturedResponse) {
     return "the report was accepted but the gate recorded a weaker tier — check that this agent's registration and signing key still match (`npx @decidio/sdk doctor`).";
 }
 export function readConfirmResponse(body, opts) {
-    const retry = opts.journalled
+    const journalled = opts.journalled ?? false;
+    const retry = journalled
         ? "re-send the report with `guard.resume.reconfirm(decisionId)` once connectivity or the service is healthy."
         : "this path journalled no report, so there is nothing to re-send from here — record the outcome from your own system, or run the action through `guard.protect`'s durable mode, where reports ARE journalled and `reconfirm` can replay them.";
     const b = body;
     if (!b || b.ok !== true || typeof b.confirmation !== "string") {
-        return { reportRecorded: false, executionConfirmed: false, diagnostic: `the gate answered 2xx but named no evidence tier — the execution report is NOT recorded. Your action DID run; ${retry}` };
+        return { reportRecorded: false, executionConfirmed: false, confirmationRetryable: true, reportJournalled: journalled, diagnostic: `the gate answered 2xx but named no evidence tier — the execution report is NOT recorded. Your action DID run; ${retry}` };
     }
     const tier = b.confirmation;
     if (!EVIDENCE_TIERS.includes(tier)) {
-        return { reportRecorded: false, executionConfirmed: false, diagnostic: `the gate reported an evidence tier this SDK does not recognise (${JSON.stringify(tier)}) — refusing to treat it as evidence. Upgrade @decidio/sdk; your action DID run, and ${retry}` };
+        return { reportRecorded: false, executionConfirmed: false, confirmationRetryable: false, reportJournalled: journalled, diagnostic: `the gate reported an evidence tier this SDK does not recognise (${JSON.stringify(tier)}) — refusing to treat it as evidence. Upgrade @decidio/sdk; your action DID run, and ${retry}` };
     }
     const executionConfirmed = CONFIRMING.includes(tier);
-    const outcome = { reportRecorded: true, evidenceTier: tier, executionConfirmed };
+    const outcome = { reportRecorded: true, evidenceTier: tier, executionConfirmed, reportJournalled: journalled };
     if (!executionConfirmed && opts.signed)
         outcome.diagnostic = describeTierGap(opts.capturedResponse);
     else if (!executionConfirmed)
@@ -40,6 +41,8 @@ export function readConfirmResponse(body, opts) {
     const rpt = body?.executionReport;
     if (rpt && typeof rpt === "object" && typeof rpt.verified === "boolean") {
         outcome.executionReportVerified = rpt.verified;
+        if (typeof rpt.reason === "string" && rpt.reason)
+            outcome.executionReportReason = rpt.reason;
         if (!rpt.verified) {
             const why = typeof rpt.reason === "string" && rpt.reason ? ` (${rpt.reason})` : "";
             outcome.diagnostic = `${outcome.diagnostic ? outcome.diagnostic + " " : ""}The signed execution report did NOT verify${why} — the report was recorded without a proven attestation. Check the agent's key/DID/registration (npx @decidio/sdk doctor).`;

package/dist/guard.d.ts

@@ -1,4 +1,4 @@
-import { type ApprovalContext } from "./index.js";
+import { type ApprovalContext, type ProtectedExecution } from "./index.js";
 import { type ResumeController, type ResumeOutcome } from "./resume.js";
 export interface GuardFacadeConfig {
     apiUrl: string;
@@ -28,6 +28,12 @@ export interface ProtectOptions {
      *  across every door), but their ENGINE integration is verified against structural mocks, not
      *  live engines. Use the core path for production until that changes. */
     adapter?: "generic" | "langgraph" | "openai" | "temporal" | "inngest";
+    /** Hand the action an `ExecutionContext` as its FIRST argument: `{ decisionId, attemptId,
+     *  idempotencyKey }`. Pass `idempotencyKey` to your downstream API and the one window this SDK
+     *  cannot close — the vendor committing twice — closes on their side. Opt-in by design: arity
+     *  inspection would have to guess, and guessing wrong hands a payment call a context object
+     *  where it expected an invoice. */
+    withContext?: boolean;
     /** "durable" (default) suspends for async approval; "blocking" polls (short approvals only). */
     mode?: "durable" | "blocking";
     /** The action name this wrapper produces, declared UP FRONT so the resume registry is populated
@@ -84,7 +90,18 @@ export declare class Guard {
     /** Throws when the facade has no gate URL — at USE time, not import time, so `import { guard }`
      *  stays safe in envless contexts. */
     private assertConfigured;
-    protect<A extends any[], R>(fn: (...a: A) => Promise<R>, describe: (...a: A) => ApprovalContext, opts?: ProtectOptions): (...a: A) => Promise<R>;
+    /** Wrap a function so every call is authorized, recorded and — in 0.2.0 — REPORTED BACK.
+     *
+     *  Returns `{ value, decisionId, confirmation }`, not the bare value. Through 0.1.x it returned
+     *  `R` and the confirmation outcome went to a console warning, so the one thing a caller of an
+     *  authority SDK could not do was find out what Decidio recorded. If you genuinely do not need
+     *  it, `protectBestEffort` keeps the old shape. */
+    protect<A extends any[], R>(fn: (...a: A) => Promise<R>, describe: (...a: A) => ApprovalContext, opts?: ProtectOptions): (...a: A) => Promise<ProtectedExecution<R>>;
+    /** @deprecated The 0.1.x shape: resolves to your function's value alone and DISCARDS what
+     *  Decidio recorded. Kept because a caller who truly does not care should not have to
+     *  destructure — but "the report was not recorded" and "the execution could not be attested"
+     *  become invisible again, which is the gap 0.2.0 exists to close. Prefer `protect`. */
+    protectBestEffort<A extends any[], R>(fn: (...a: A) => Promise<R>, describe: (...a: A) => ApprovalContext, opts?: ProtectOptions): (...a: A) => Promise<R>;
 }
 /** Preconfigured singleton — `import { guard } from "@decidio/sdk"`. */
 export declare const guard: Guard;

package/dist/guard.js

@@ -1,6 +1,5 @@
 import { withApproval } from "./index.js";
 import { createDecidioResume, FilePendingStore } from "./resume.js";
-import { join } from "node:path";
 export class Guard {
     config;
     _resume;
@@ -38,7 +37,6 @@ export class Guard {
             this._resume = createDecidioResume({
                 apiUrl: c.apiUrl, apiToken: c.apiToken, webhookSecret: c.webhookSecret,
                 resumeUrl: c.resumeUrl, store: new FilePendingStore(c.pendingDir ?? ".decidio-pending"),
-                reportDir: join(c.pendingDir ?? ".decidio-pending", "reports"),
                 agentId: c.agentId, agentKey: c.agentKey, agentDid: c.agentDid, workspaceId: c.workspaceId,
                 fetchImpl: c.fetchImpl,
             });
@@ -70,12 +68,16 @@ export class Guard {
                 `(pollTimeoutMs), and when it does, the decision stays OPEN in Decidio while this process stops waiting: ` +
                 `a later approval cannot resume it. Only safe for short, watched approvals — omit mode:"blocking" for ` +
                 `durable async resume on real (minutes-to-days) approvals.`);
-            return withApproval(fn, describe, base, opts?.evidence ? { evidence: opts.evidence } : undefined);
+            return withApproval(fn, describe, base, { ...(opts?.evidence ? { evidence: opts.evidence } : {}), ...(opts?.withContext ? { withContext: true } : {}) });
         }
         const resume = this.ensureResume();
         if (opts?.action)
-            resume.register(opts.action, fn, opts?.evidence);
-        return withApproval(fn, describe, { ...base, resumeUrl: c.resumeUrl, resume }, opts?.evidence ? { evidence: opts.evidence } : undefined);
+            resume.register(opts.action, fn, opts?.evidence, opts?.withContext);
+        return withApproval(fn, describe, { ...base, resumeUrl: c.resumeUrl, resume }, { ...(opts?.evidence ? { evidence: opts.evidence } : {}), ...(opts?.withContext ? { withContext: true } : {}) });
+    }
+    protectBestEffort(fn, describe, opts) {
+        const wrapped = this.protect(fn, describe, opts);
+        return async (...a) => (await wrapped(...a)).value;
     }
 }
 export const guard = Guard.fromEnv();

package/dist/index.d.ts

@@ -1,9 +1,10 @@
 import type { ResumeController } from "./resume.js";
+import { type EvidenceOutcome } from "./evidence.js";
 export { DecidioSuspendedError, FilePendingStore, MemoryPendingStore, createDecidioResume, assertConfirmRecorded } from "./resume.js";
 export type { PendingAction, PendingStore, ResumeController, ResumeOutcome } from "./resume.js";
 export { guard, Guard } from "./guard.js";
 export type { GuardFacadeConfig, ProtectOptions } from "./guard.js";
-export { DecidioHttpError } from "./errors.js";
+export { DecidioHttpError, decisionIdProblem } from "./errors.js";
 export { generateKeypair, didFromPrivateKey, signBoundProof, signConfirm, signExecutionReport, verifyExecutionReport, resultDigest, assertSafeTransport, carriesCredential } from "./signing.js";
 export { canonicalize, canonicalizeArgs, canonicalJson, DecidioUnsafeArgumentsError } from "./canonical.js";
 export type { JsonValue, JsonPrimitive } from "./canonical.js";
@@ -107,10 +108,34 @@ export declare class DecidioNetworkError extends Error {
 /** `<appUrl>/d/<decisionId>` — the deep link that opens this decision directly, on the web app or
  *  the phone build. Null when DECIDIO_APP_URL is not configured, never a half-built URL. */
 export declare function decisionUrl(appUrl: string | undefined, decisionId: string): string | null;
+/** What a protected call returns in 0.2.0: your function's value, the decision it was authorized
+ *  under, and what Decidio actually recorded about the execution.
+ *
+ *  Through 0.1.x this was just `R`. The SDK computed the full confirmation outcome — tier, whether
+ *  the report was recorded, whether the signed execution report verified, whether the evidence
+ *  mapper failed — and then dropped it on the floor, surfacing it only as a console warning. For a
+ *  product whose value IS the record, the one thing a caller could not do was find out what got
+ *  recorded. Returning it makes "my action ran but was logged as an unproven assertion" something
+ *  code can branch on instead of something a human might notice in a log.
+ *
+ *  `protectBestEffort` keeps the old value-only shape for callers that genuinely do not care. */
+export interface ProtectedExecution<R> {
+    /** Exactly what your function returned — unchanged, uncanonicalized, your object. */
+    value: R;
+    /** The decision this execution was authorized under. Use it as your downstream idempotency key. */
+    decisionId: string;
+    /** What Decidio recorded. `reportRecorded` false means the execution happened and Decidio does
+     *  NOT know; `executionConfirmed` false means it knows but could not attest a commit. */
+    confirmation: EvidenceOutcome;
+}
 export declare function withApproval<A extends any[], R>(fn: (...args: A) => Promise<R>, describe: (...args: A) => ApprovalContext, config: GuardConfig, opts?: {
     /** Map YOUR function's natural return value to the evidence Decidio records. The gate awards
      *  its strongest wrapper tier (application_confirmed) only for a committed record id plus a
      *  success indication — this lets a real API keep its own shape instead of being forced into
      *  magic field names: `evidence: (r) => ({ recordId: r.transactionId, success: r.status === "committed" })`. */
     evidence?: (result: R) => unknown;
-}): (...args: A) => Promise<R>;
+    /** Hand the action an `ExecutionContext` as its FIRST argument: `{ decisionId, attemptId,
+     *  idempotencyKey }`. Opt-in, never inferred from the function's arity — guessing wrong means
+     *  passing a context object as someone's first business argument. */
+    withContext?: boolean;
+}): (...args: A) => Promise<ProtectedExecution<R>>;

package/dist/index.js

@@ -4,8 +4,8 @@ import { canonicalize, canonicalizeArgs } from "./canonical.js";
 import { readConfirmResponse, buildConfirmBody } from "./evidence.js";
 export { DecidioSuspendedError, FilePendingStore, MemoryPendingStore, createDecidioResume, assertConfirmRecorded } from "./resume.js";
 export { guard, Guard } from "./guard.js";
-export { DecidioHttpError } from "./errors.js";
-import { DecidioHttpError } from "./errors.js";
+export { DecidioHttpError, decisionIdProblem } from "./errors.js";
+import { DecidioHttpError, decisionIdProblem } from "./errors.js";
 export { generateKeypair, didFromPrivateKey, signBoundProof, signConfirm, signExecutionReport, verifyExecutionReport, resultDigest, assertSafeTransport, carriesCredential } from "./signing.js";
 export { canonicalize, canonicalizeArgs, canonicalJson, DecidioUnsafeArgumentsError } from "./canonical.js";
 export { readConfirmResponse, buildConfirmBody, describeTierGap, EVIDENCE_TIERS } from "./evidence.js";
@@ -142,6 +142,12 @@ export function withApproval(fn, describe, config, opts) {
             ? signBoundProof(config.agentKey, { agentId: config.agentId, did: config.agentDid, action: ctx.action, amount: ctx.amount, scope: ctx.scope, workspaceId: config.workspaceId })
             : undefined;
         canonicalize(ctx, "describe(...)");
+        if (typeof ctx?.action !== "string" || ctx.action.trim().length === 0) {
+            throw new Error(`[decidio] describe(...) must return an \`action\` string naming what is being asked (got ${JSON.stringify(ctx?.action ?? null)}). Nothing was routed or executed.`);
+        }
+        if (typeof ctx.amount !== "number" || !Number.isFinite(ctx.amount) || ctx.amount < 0) {
+            throw new Error(`[decidio] describe(...) must return a finite, non-negative \`amount\` — the policy decides on it, so a request without one is not a request Decidio can rule on (got ${JSON.stringify(ctx.amount ?? null)}). Use 0 for an action with no monetary value. Nothing was routed or executed.`);
+        }
         const auth = await post(config, "/agent/authorize", {
             requester: config.agentId, action: ctx.action, amount: ctx.amount,
             scope: ctx.scope, sourceSystem: config.sourceSystem,
@@ -151,8 +157,9 @@ export function withApproval(fn, describe, config, opts) {
         });
         if (auth.decision !== "proceed" && auth.decision !== "route" && auth.decision !== "block")
             throw new DecidioBlockedError(`unrecognized gate verdict: ${String(auth.decision)}`, auth.decisionId);
-        if (typeof auth.decisionId !== "string" || !auth.decisionId)
-            throw new DecidioBlockedError(`the gate answered "${auth.decision}" with no usable decisionId (${JSON.stringify(auth.decisionId ?? null)}) — refusing to execute. Every authorized action must be addressable: without an id it cannot be polled, resumed, confirmed or audited.`, auth.decisionId);
+        const idProblem = decisionIdProblem(auth.decisionId);
+        if (idProblem)
+            throw new DecidioBlockedError(`the gate answered "${auth.decision}" with no usable decisionId (${JSON.stringify(auth.decisionId ?? null)} — ${idProblem}) — refusing to execute. Every authorized action must be addressable: without an id it cannot be polled, resumed, confirmed or audited.`, typeof auth.decisionId === "string" ? auth.decisionId : String(auth.decisionId ?? ""));
         if (auth.decision === "block")
             throw new DecidioBlockedError(auth.reason ?? "blocked by policy", auth.decisionId);
         if (auth.decision === "route") {
@@ -188,7 +195,9 @@ export function withApproval(fn, describe, config, opts) {
                 await sleep(pollInterval);
             }
         }
-        const result = await fn(...args);
+        const result = opts?.withContext
+            ? await fn({ decisionId: auth.decisionId, attemptId: null, idempotencyKey: auth.decisionId }, ...args)
+            : await fn(...args);
         let reported = null;
         let evidenceProblem;
         try {
@@ -199,20 +208,31 @@ export function withApproval(fn, describe, config, opts) {
             evidenceProblem = String(e?.message ?? e);
             console.warn(`[decidio] ${auth.decisionId}: the action SUCCEEDED but its result could not be reported as evidence (${evidenceProblem}). Reporting an empty captured response so the execution is still recorded — map the return value with the \`evidence\` option (e.g. evidence: (r) => ({ recordId: String(r.id), success: true })) to earn a confirming tier. The action was NOT re-run.`);
         }
+        let confirmation;
         try {
             const confirmIdentity = signConfirm(auth.decisionId, config);
             const confirmBody = await post(config, "/agent/confirm", buildConfirmBody(config, auth.decisionId, reported, confirmIdentity));
-            const ev = readConfirmResponse(confirmBody, { signed: !!confirmIdentity, capturedResponse: reported });
-            if (!ev.reportRecorded)
-                console.warn(`[decidio] ${auth.decisionId}: ${ev.diagnostic}`);
-            else if (!ev.executionConfirmed || ev.executionReportVerified === false)
-                console.warn(`[decidio] execution evidence for ${auth.decisionId} recorded as ${ev.evidenceTier} — ${ev.diagnostic}`);
+            confirmation = readConfirmResponse(confirmBody, { signed: !!confirmIdentity, capturedResponse: reported, journalled: false });
+            if (!confirmation.reportRecorded)
+                console.warn(`[decidio] ${auth.decisionId}: ${confirmation.diagnostic}`);
+            else if (!confirmation.executionConfirmed || confirmation.executionReportVerified === false)
+                console.warn(`[decidio] execution evidence for ${auth.decisionId} recorded as ${confirmation.evidenceTier} — ${confirmation.diagnostic}`);
             if (evidenceProblem)
                 console.warn(`[decidio] ${auth.decisionId}: the execution IS recorded, but with an empty captured response — see the evidence note above.`);
         }
         catch (e) {
-            console.warn(`[decidio] confirmation post failed (action succeeded): ${e.message}`);
+            const isHttp = e instanceof DecidioHttpError;
+            console.warn(`[decidio] confirmation post failed (action succeeded): ${e?.message ?? e}`);
+            confirmation = {
+                reportRecorded: false,
+                executionConfirmed: false,
+                confirmationRetryable: isHttp ? e.retryable : true,
+                reportJournalled: false,
+                diagnostic: `your action RAN and Decidio does NOT have its execution report (${e?.message ?? e}). This path journals nothing, so there is no local copy to re-send: record the outcome from your own system. Durable mode DOES journal reports, and its recovery path can re-send them — that is the mode to use if this matters to you. Do NOT re-run the action.`,
+            };
         }
-        return result;
+        if (evidenceProblem)
+            confirmation.evidenceError = evidenceProblem;
+        return { value: result, decisionId: auth.decisionId, confirmation };
     };
 }

package/dist/inngest.d.ts

@@ -45,6 +45,10 @@ export declare function decidioGateStep<R>(args: {
     ctx: ApprovalContext;
     run: () => Promise<R>;
     timeout?: string;
+    /** Map your action's return value to the evidence Decidio records — the same option the core
+     *  path takes. This door's own confirm chokepoint tells callers to use it; until 0.2.0 no
+     *  adapter door accepted one, so the advice was unfollowable everywhere it was printed. */
+    evidence?: (result: R) => unknown;
 }): Promise<GateStepOutcome<R>>;
 /**
  * Decidio → Inngest bridge. Mount as an HTTP endpoint and register it as the agent's

package/dist/inngest.js

@@ -22,7 +22,7 @@ export async function decidioGateStep(args) {
             return { status: "blocked", decisionId: auth.decisionId };
     }
     const result = await step.run("agent-action", args.run);
-    await step.run("decidio-confirm", async () => { await gateConfirm(config, auth.decisionId, result); return true; });
+    await step.run("decidio-confirm", async () => { await gateConfirm(config, auth.decisionId, result, args.evidence); return true; });
     return { status: "executed", decisionId: auth.decisionId, result };
 }
 export function createInngestResumeBridge(opts) {