@decidio/sdk 0.1.6 → 0.1.8

package/dist/guard.d.ts

@@ -17,12 +17,14 @@ export interface GuardFacadeConfig {
 export interface ProtectOptions {
     adapter?: "generic" | "langgraph" | "openai" | "temporal" | "inngest" | "mcp";
     mode?: "durable" | "blocking";
+    action?: string;
 }
 export declare class Guard {
     config: GuardFacadeConfig;
     resume?: ResumeController;
     constructor(config: GuardFacadeConfig, resume?: ResumeController);
     static fromEnv(): Guard;
+    register(action: string, fn: (...a: any[]) => Promise<any>): void;
     resumeHandler(): import("http").RequestListener;
     resumeFetchHandler(): (req: Request) => Promise<Response>;
     worker(opts?: {

package/dist/guard.js

@@ -22,6 +22,7 @@ export class Guard {
             appUrl: process.env.DECIDIO_APP_URL,
         });
     }
+    register(action, fn) { this.ensureResume().register(action, fn); }
     resumeHandler() { return this.ensureResume().webhookHandler(); }
     resumeFetchHandler() { return this.ensureResume().fetchHandler(); }
     worker(opts) {
@@ -53,7 +54,10 @@ export class Guard {
                 "Omit mode:\"blocking\" for durable async resume on real (minutes-to-days) approvals.");
             return withApproval(fn, describe, base);
         }
-        return withApproval(fn, describe, { ...base, resumeUrl: c.resumeUrl, resume: this.ensureResume() });
+        const resume = this.ensureResume();
+        if (opts?.action)
+            resume.register(opts.action, fn);
+        return withApproval(fn, describe, { ...base, resumeUrl: c.resumeUrl, resume });
     }
 }
 export const guard = Guard.fromEnv();

package/dist/index.d.ts

@@ -45,6 +45,12 @@ export declare class DecidioTimeoutError extends Error {
     decisionId: string;
     constructor(decisionId: string);
 }
+export declare class DecidioRateLimitError extends Error {
+    limit: number | undefined;
+    remaining: number | undefined;
+    resetAt: string | undefined;
+    constructor(limit: number | undefined, remaining: number | undefined, resetAt: string | undefined, serverMessage?: string);
+}
 export declare class DecidioNetworkError extends Error {
     endpoint: string;
     op: string;

package/dist/index.js

@@ -32,12 +32,28 @@ export class DecidioTimeoutError extends Error {
     }
 }
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+export class DecidioRateLimitError extends Error {
+    limit;
+    remaining;
+    resetAt;
+    constructor(limit, remaining, resetAt, serverMessage) {
+        super(`[decidio] governed-action rate limit reached${limit != null ? ` (${limit}/hour on this workspace)` : ""}${resetAt ? ` — resets ${resetAt}` : ""}. ` +
+            `${serverMessage ? serverMessage + " " : ""}Nothing was routed or executed; retry after the reset.`);
+        this.limit = limit;
+        this.remaining = remaining;
+        this.resetAt = resetAt;
+        this.name = "DecidioRateLimitError";
+    }
+}
 export class DecidioNetworkError extends Error {
     endpoint;
     op;
     code;
     constructor(endpoint, op, code, cause) {
         super(`[decidio] could not reach ${endpoint} during ${op}${code ? ` (${code})` : ""}. ` +
+            (/localhost|127\.0\.0\.1/.test(endpoint) && code === "ECONNREFUSED"
+                ? `A refused localhost connection usually means the SDK never saw your config: if your settings live in .env, run node with --env-file=.env (or export DECIDIO_API_URL — the hosted sandbox is https://decidio-api.onrender.com). `
+                : "") +
             `Nothing was executed locally and no verdict was received — if a request reached Decidio it is ` +
             `visible in your queue. Check the network/URL (DECIDIO_API_URL) and retry; retrying is safe ` +
             `(a retry creates a new request — it can never double-execute).`);
@@ -63,6 +79,10 @@ async function post(cfg, path, body) {
         headers: { "content-type": "application/json", ...(cfg.apiToken ? { authorization: `Bearer ${cfg.apiToken}` } : {}) },
         body: JSON.stringify(body),
     });
+    if (res.status === 429) {
+        const b = await res.json().catch(() => null);
+        throw new DecidioRateLimitError(b?.limit, b?.remaining, b?.resetAt, b?.message);
+    }
     if (!res.ok)
         throw new Error(`decidio ${path} ${res.status}: ${await res.text().catch(() => "")}`);
     return res.json();

package/dist/resume.js

@@ -57,7 +57,7 @@ export class FilePendingStore {
     key(id) { return id.replace(/[^\w.-]/g, "_"); }
     path(id) { return join(this.dir, `${this.key(id)}.json`); }
     claimedPath(id) { return join(this.dir, `${this.key(id)}.claimed`); }
-    async put(p) { writeFileSync(this.path(p.decisionId), JSON.stringify(p, null, 2)); }
+    async put(p) { writeFileSync(this.path(p.decisionId), JSON.stringify(p, null, 2), { mode: 0o600 }); }
     async get(id) {
         for (const f of [this.path(id), this.claimedPath(id)])
             if (existsSync(f))
@@ -70,8 +70,16 @@ export class FilePendingStore {
     async list() {
         if (!existsSync(this.dir))
             return [];
-        return readdirSync(this.dir).filter((f) => f.endsWith(".json"))
-            .map((f) => JSON.parse(readFileSync(join(this.dir, f), "utf8")));
+        const out = [];
+        for (const f of readdirSync(this.dir).filter((f) => f.endsWith(".json"))) {
+            try {
+                out.push(JSON.parse(readFileSync(join(this.dir, f), "utf8")));
+            }
+            catch (e) {
+                console.error(`[decidio] skipping unreadable parked entry ${f} (${e.message}) — the other parked actions still resume; inspect or delete this file.`);
+            }
+        }
+        return out;
     }
     async claim(id) {
         try {
@@ -143,7 +151,12 @@ export function createDecidioResume(opts) {
         workspaceId: opts.workspaceId ?? process.env.DECIDIO_WORKSPACE_ID,
         webhookSecret: secret,
         store: opts.store,
-        register(action, fn) { registry.set(action, fn); },
+        register(action, fn) {
+            const prev = registry.get(action);
+            if (prev && prev !== fn)
+                console.warn(`[decidio] action "${action}" is being registered again with a DIFFERENT function — the latest one wins, and a resumed decision would run IT. Give each protected function its own action name.`);
+            registry.set(action, fn);
+        },
         async park(p) {
             const argsSig = signArgs(p, ctrl.agentKey, ctrl.webhookSecret);
             if (!argsSig)
@@ -187,19 +200,36 @@ export function createDecidioResume(opts) {
             if (integrity === "unbound")
                 console.warn(`[decidio] executing ${decisionId} from an UNBOUND parked entry (this agent has no key material to bind or verify payloads) — its arguments cannot be integrity-checked. Run \`npx @decidio/sdk init\` to enable binding.`);
             const fn = registry.get(pending.action);
-            if (!fn)
-                return finish({ status: "no_handler", decisionId, action: pending.action, reason: `no fn registered for action "${pending.action}" — call resume.register(...) at startup` });
+            if (!fn) {
+                console.error(`[decidio] cannot resume ${decisionId}: no function is registered for action "${pending.action}" in THIS process.`);
+                console.error(`  A worker only re-executes actions registered where it runs. At startup, either declare the action on the wrapper:`);
+                console.error(`      const doIt = guard.protect(doItRaw, describe, { action: "${pending.action}" });`);
+                console.error(`  or register the raw function directly:`);
+                console.error(`      guard.register("${pending.action}", doItRaw);`);
+                console.error(`  then start the worker. The approved action stays parked until then — nothing is lost.`);
+                return finish({ status: "no_handler", decisionId, action: pending.action, reason: `no fn registered for action "${pending.action}" in this process — declare { action } on protect(), or call guard.register("${pending.action}", fn) at startup` });
+            }
             const claimed = ctrl.store.claim ? await ctrl.store.claim(decisionId) : (!inFlight.has(decisionId) && (inFlight.add(decisionId), true));
             if (!claimed)
                 return { status: "unknown", decisionId };
             try {
                 const result = await fn(...pending.args);
-                await ctrl.store.delete(decisionId);
+                let confirmed = true;
                 try {
                     await confirm(ctrl, decisionId, result);
                 }
                 catch (e) {
-                    console.warn(`[decidio] resume confirm failed (action succeeded): ${e.message}`);
+                    confirmed = false;
+                    console.warn(`[decidio] resume confirm failed (your action DID succeed): ${e.message}`);
+                }
+                const retainedIsSafe = typeof ctrl.store.claim === "function";
+                if (confirmed || !retainedIsSafe)
+                    await ctrl.store.delete(decisionId);
+                if (!confirmed) {
+                    if (retainedIsSafe)
+                        console.warn(`  The parked entry for ${decisionId} is kept as local evidence that it executed — it stays CLAIMED, so it cannot re-run. Retry the confirmation, then delete it.`);
+                    else
+                        console.warn(`  This store provides no claim() primitive, so the entry was DELETED to guarantee the action cannot execute twice. ${decisionId} executed, but its confirmation never reached Decidio — re-confirm it from your own records.`);
                 }
                 return finish({ status: "executed", decisionId, action: pending.action, result });
             }

package/openapi.yaml

@@ -5,7 +5,7 @@
 openapi: 3.1.0
 info:
   title: Decidio Agent Gate
-  version: 0.1.6
+  version: 0.1.8
   description: >
     Authorize an AI-agent action (proceed | route | block), confirm the captured outcome, and
     receive the signed resume webhook when a routed action is decided. Every outcome seals a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decidio/sdk",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "One-line approval gate for AI-agent actions. Wrap a risky tool call with guard.protect(); Decidio's policy engine decides proceed | route | block, a human approves routed actions, and every outcome is sealed as a verifiable Authority Receipt.",
   "license": "Apache-2.0",
   "type": "module",
@@ -81,7 +81,7 @@
     "prepublishOnly": "npm run typecheck && npm run build"
   },
   "dependencies": {
-    "@decidio/verify": "^0.1.3"
+    "@decidio/verify": "0.1.7"
   },
   "author": "OmniTwin Technologies Inc.",
   "bugs": {