@sanctum-runtime/adapter-agent-runtime 0.1.0

package/README.md

@@ -0,0 +1,26 @@
+# @sanctum-runtime/adapter-agent-runtime
+
+`protectAgent()` and `AgentActions` helpers for the Sanctum runtime SDK.
+
+```bash
+npm install @sanctum-runtime/sdk @sanctum-runtime/adapter-agent-runtime
+```
+
+```ts
+import { SanctumRuntime } from '@sanctum-runtime/sdk'
+import { protectAgent, AgentActions } from '@sanctum-runtime/adapter-agent-runtime'
+
+const sanctum = new SanctumRuntime({ baseUrl: process.env.SANCTUM_API_URL! })
+
+await protectAgent(sanctum, {
+  actor: 'my-agent',
+  action: AgentActions.SEND_EMAIL,
+  context: { to: 'user@example.com' },
+  offlineMode: true,
+  execute: async () => sendEmail(),
+})
+```
+
+Requires a running Sanctum API — clone [sanctum-runtime](https://github.com/Matik103/sanctum-runtime) and `npm run dev:runtime`, or point at your hosted API.
+
+MIT — see [OPEN_CORE.md](https://github.com/Matik103/sanctum-runtime/blob/main/OPEN_CORE.md).

package/dist/index.d.ts

@@ -0,0 +1,69 @@
+import * as _sanctum_runtime_sdk from '@sanctum-runtime/sdk';
+import { SanctumActionBlockedError, SanctumRuntime, ActionRequest, ActionResult, SanctumVerificationRequiredError } from '@sanctum-runtime/sdk';
+
+/** Canonical agent action types (PRD §17 — Category 1). */
+declare const AgentActions: {
+    readonly SEND_EMAIL: "send_email";
+    readonly DELETE_FILE: "delete_file";
+    readonly EXECUTE_TERMINAL: "execute_terminal";
+    readonly TRANSFER_FUNDS: "transfer_funds";
+    readonly ACCESS_DATABASE: "access_database";
+    readonly CREATE_USER: "create_user";
+};
+type AgentAction = (typeof AgentActions)[keyof typeof AgentActions];
+declare const AGENT_ACTIONS: AgentAction[];
+
+type AgentRuntimeAdapterOptions = {
+    /** Default actor id for verify calls (e.g. workflow or session id). */
+    actor?: string;
+    offlineMode?: boolean;
+};
+type AgentProtectOptions<T> = {
+    action: AgentAction | string;
+    context?: Record<string, unknown>;
+    actor?: string;
+    correlationId?: string;
+    offlineMode?: boolean;
+    /** Called only when decision is APPROVED. */
+    execute: () => Promise<T>;
+};
+/** @deprecated Use SanctumActionBlockedError from @sanctum-runtime/sdk */
+declare class AgentActionBlockedError extends SanctumActionBlockedError {
+}
+/** @deprecated Use SanctumVerificationRequiredError from @sanctum-runtime/sdk */
+declare class AgentVerificationRequiredError extends SanctumVerificationRequiredError {
+}
+/** Normalizes agent-layer calls into Sanctum {@link ActionRequest}. */
+declare class AgentRuntimeAdapter {
+    private runtime;
+    private defaultActor;
+    private defaultOffline;
+    constructor(runtime: SanctumRuntime, options?: AgentRuntimeAdapterOptions);
+    normalize(input: {
+        actor?: string;
+        action: AgentAction | string;
+        context?: Record<string, unknown>;
+    }): ActionRequest;
+    verifyAction(input: Parameters<AgentRuntimeAdapter['normalize']>[0], options?: {
+        offlineMode?: boolean;
+        correlationId?: string;
+    }): Promise<ActionResult>;
+    /**
+     * Intercept → verify → execute. Throws on block or verification required.
+     * PRD integration north star: `sanctum.protect(agent)` style flows.
+     */
+    protect<T>(options: AgentProtectOptions<T>): Promise<{
+        result: ActionResult;
+        value: T;
+    }>;
+}
+
+/** One-line guard for agent runtimes (PRD §17). */
+declare function protectAgent<T>(runtime: SanctumRuntime, options: AgentProtectOptions<T> & {
+    actor?: string;
+}): Promise<{
+    result: _sanctum_runtime_sdk.ActionResult;
+    value: T;
+}>;
+
+export { AGENT_ACTIONS, type AgentAction, AgentActionBlockedError, AgentActions, type AgentProtectOptions, AgentRuntimeAdapter, type AgentRuntimeAdapterOptions, AgentVerificationRequiredError, protectAgent };

package/dist/index.js

@@ -0,0 +1,77 @@
+// src/actions.ts
+var AgentActions = {
+  SEND_EMAIL: "send_email",
+  DELETE_FILE: "delete_file",
+  EXECUTE_TERMINAL: "execute_terminal",
+  TRANSFER_FUNDS: "transfer_funds",
+  ACCESS_DATABASE: "access_database",
+  CREATE_USER: "create_user"
+};
+var AGENT_ACTIONS = Object.values(AgentActions);
+
+// src/adapter.ts
+import { ActionRequestSchema, SanctumActionBlockedError, SanctumVerificationRequiredError } from "@sanctum-runtime/sdk";
+var AgentActionBlockedError = class extends SanctumActionBlockedError {
+};
+var AgentVerificationRequiredError = class extends SanctumVerificationRequiredError {
+};
+var AgentRuntimeAdapter = class {
+  constructor(runtime, options = {}) {
+    this.runtime = runtime;
+    this.defaultActor = options.actor ?? "agent";
+    this.defaultOffline = options.offlineMode ?? false;
+  }
+  runtime;
+  defaultActor;
+  defaultOffline;
+  normalize(input) {
+    return ActionRequestSchema.parse({
+      actor: input.actor ?? this.defaultActor,
+      action: input.action,
+      context: input.context ?? {}
+    });
+  }
+  verifyAction(input, options = {}) {
+    const request = this.normalize(input);
+    return this.runtime.verifyAction(request, {
+      offlineMode: options.offlineMode ?? this.defaultOffline,
+      correlationId: options.correlationId
+    });
+  }
+  /**
+   * Intercept → verify → execute. Throws on block or verification required.
+   * PRD integration north star: `sanctum.protect(agent)` style flows.
+   */
+  async protect(options) {
+    const result = await this.verifyAction(
+      {
+        actor: options.actor,
+        action: options.action,
+        context: options.context
+      },
+      { offlineMode: options.offlineMode, correlationId: options.correlationId }
+    );
+    assertExecutable(result.decision, result);
+    const value = await options.execute();
+    return { result, value };
+  }
+};
+function assertExecutable(decision, result) {
+  if (decision === "BLOCKED") throw new SanctumActionBlockedError(result);
+  if (decision === "REQUIRE_VERIFICATION") throw new SanctumVerificationRequiredError(result);
+}
+
+// src/index.ts
+function protectAgent(runtime, options) {
+  const adapter = new AgentRuntimeAdapter(runtime, { actor: options.actor });
+  return adapter.protect(options);
+}
+export {
+  AGENT_ACTIONS,
+  AgentActionBlockedError,
+  AgentActions,
+  AgentRuntimeAdapter,
+  AgentVerificationRequiredError,
+  protectAgent
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/actions.ts","../src/adapter.ts","../src/index.ts"],"sourcesContent":["/** Canonical agent action types (PRD §17 — Category 1). */\nexport const AgentActions = {\n  SEND_EMAIL: 'send_email',\n  DELETE_FILE: 'delete_file',\n  EXECUTE_TERMINAL: 'execute_terminal',\n  TRANSFER_FUNDS: 'transfer_funds',\n  ACCESS_DATABASE: 'access_database',\n  CREATE_USER: 'create_user',\n} as const\n\nexport type AgentAction = (typeof AgentActions)[keyof typeof AgentActions]\n\nexport const AGENT_ACTIONS = Object.values(AgentActions) as AgentAction[]\n","import type { ActionRequest, ActionResult, Decision } from '@sanctum-runtime/sdk'\nimport { ActionRequestSchema, SanctumActionBlockedError, SanctumVerificationRequiredError } from '@sanctum-runtime/sdk'\nimport type { SanctumRuntime } from '@sanctum-runtime/sdk'\nimport type { AgentAction } from './actions.js'\n\nexport type AgentRuntimeAdapterOptions = {\n  /** Default actor id for verify calls (e.g. workflow or session id). */\n  actor?: string\n  offlineMode?: boolean\n}\n\nexport type AgentProtectOptions<T> = {\n  action: AgentAction | string\n  context?: Record<string, unknown>\n  actor?: string\n  correlationId?: string\n  offlineMode?: boolean\n  /** Called only when decision is APPROVED. */\n  execute: () => Promise<T>\n}\n\n/** @deprecated Use SanctumActionBlockedError from @sanctum-runtime/sdk */\nexport class AgentActionBlockedError extends SanctumActionBlockedError {}\n\n/** @deprecated Use SanctumVerificationRequiredError from @sanctum-runtime/sdk */\nexport class AgentVerificationRequiredError extends SanctumVerificationRequiredError {}\n\n/** Normalizes agent-layer calls into Sanctum {@link ActionRequest}. */\nexport class AgentRuntimeAdapter {\n  private defaultActor: string\n  private defaultOffline: boolean\n\n  constructor(\n    private runtime: SanctumRuntime,\n    options: AgentRuntimeAdapterOptions = {},\n  ) {\n    this.defaultActor = options.actor ?? 'agent'\n    this.defaultOffline = options.offlineMode ?? false\n  }\n\n  normalize(input: {\n    actor?: string\n    action: AgentAction | string\n    context?: Record<string, unknown>\n  }): ActionRequest {\n    return ActionRequestSchema.parse({\n      actor: input.actor ?? this.defaultActor,\n      action: input.action,\n      context: input.context ?? {},\n    })\n  }\n\n  verifyAction(\n    input: Parameters<AgentRuntimeAdapter['normalize']>[0],\n    options: { offlineMode?: boolean; correlationId?: string } = {},\n  ): Promise<ActionResult> {\n    const request = this.normalize(input)\n    return this.runtime.verifyAction(request, {\n      offlineMode: options.offlineMode ?? this.defaultOffline,\n      correlationId: options.correlationId,\n    })\n  }\n\n  /**\n   * Intercept → verify → execute. Throws on block or verification required.\n   * PRD integration north star: `sanctum.protect(agent)` style flows.\n   */\n  async protect<T>(options: AgentProtectOptions<T>): Promise<{ result: ActionResult; value: T }> {\n    const result = await this.verifyAction(\n      {\n        actor: options.actor,\n        action: options.action,\n        context: options.context,\n      },\n      { offlineMode: options.offlineMode, correlationId: options.correlationId },\n    )\n    assertExecutable(result.decision, result)\n    const value = await options.execute()\n    return { result, value }\n  }\n}\n\nfunction assertExecutable(decision: Decision, result: ActionResult): void {\n  if (decision === 'BLOCKED') throw new SanctumActionBlockedError(result)\n  if (decision === 'REQUIRE_VERIFICATION') throw new SanctumVerificationRequiredError(result)\n}\n","export { AgentActions, AGENT_ACTIONS, type AgentAction } from './actions.js'\nexport {\n  AgentRuntimeAdapter,\n  AgentActionBlockedError,\n  AgentVerificationRequiredError,\n  type AgentRuntimeAdapterOptions,\n  type AgentProtectOptions,\n} from './adapter.js'\n\nimport type { SanctumRuntime } from '@sanctum-runtime/sdk'\nimport { AgentRuntimeAdapter, type AgentProtectOptions } from './adapter.js'\n\n/** One-line guard for agent runtimes (PRD §17). */\nexport function protectAgent<T>(\n  runtime: SanctumRuntime,\n  options: AgentProtectOptions<T> & { actor?: string },\n): Promise<{ result: import('@sanctum-runtime/sdk').ActionResult; value: T }> {\n  const adapter = new AgentRuntimeAdapter(runtime, { actor: options.actor })\n  return adapter.protect(options)\n}\n"],"mappings":";AACO,IAAM,eAAe;AAAA,EAC1B,YAAY;AAAA,EACZ,aAAa;AAAA,EACb,kBAAkB;AAAA,EAClB,gBAAgB;AAAA,EAChB,iBAAiB;AAAA,EACjB,aAAa;AACf;AAIO,IAAM,gBAAgB,OAAO,OAAO,YAAY;;;ACXvD,SAAS,qBAAqB,2BAA2B,wCAAwC;AAqB1F,IAAM,0BAAN,cAAsC,0BAA0B;AAAC;AAGjE,IAAM,iCAAN,cAA6C,iCAAiC;AAAC;AAG/E,IAAM,sBAAN,MAA0B;AAAA,EAI/B,YACU,SACR,UAAsC,CAAC,GACvC;AAFQ;AAGR,SAAK,eAAe,QAAQ,SAAS;AACrC,SAAK,iBAAiB,QAAQ,eAAe;AAAA,EAC/C;AAAA,EALU;AAAA,EAJF;AAAA,EACA;AAAA,EAUR,UAAU,OAIQ;AAChB,WAAO,oBAAoB,MAAM;AAAA,MAC/B,OAAO,MAAM,SAAS,KAAK;AAAA,MAC3B,QAAQ,MAAM;AAAA,MACd,SAAS,MAAM,WAAW,CAAC;AAAA,IAC7B,CAAC;AAAA,EACH;AAAA,EAEA,aACE,OACA,UAA6D,CAAC,GACvC;AACvB,UAAM,UAAU,KAAK,UAAU,KAAK;AACpC,WAAO,KAAK,QAAQ,aAAa,SAAS;AAAA,MACxC,aAAa,QAAQ,eAAe,KAAK;AAAA,MACzC,eAAe,QAAQ;AAAA,IACzB,CAAC;AAAA,EACH;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,MAAM,QAAW,SAA8E;AAC7F,UAAM,SAAS,MAAM,KAAK;AAAA,MACxB;AAAA,QACE,OAAO,QAAQ;AAAA,QACf,QAAQ,QAAQ;AAAA,QAChB,SAAS,QAAQ;AAAA,MACnB;AAAA,MACA,EAAE,aAAa,QAAQ,aAAa,eAAe,QAAQ,cAAc;AAAA,IAC3E;AACA,qBAAiB,OAAO,UAAU,MAAM;AACxC,UAAM,QAAQ,MAAM,QAAQ,QAAQ;AACpC,WAAO,EAAE,QAAQ,MAAM;AAAA,EACzB;AACF;AAEA,SAAS,iBAAiB,UAAoB,QAA4B;AACxE,MAAI,aAAa,UAAW,OAAM,IAAI,0BAA0B,MAAM;AACtE,MAAI,aAAa,uBAAwB,OAAM,IAAI,iCAAiC,MAAM;AAC5F;;;ACxEO,SAAS,aACd,SACA,SAC4E;AAC5E,QAAM,UAAU,IAAI,oBAAoB,SAAS,EAAE,OAAO,QAAQ,MAAM,CAAC;AACzE,SAAO,QAAQ,QAAQ,OAAO;AAChC;","names":[]}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@sanctum-runtime/adapter-agent-runtime",
+  "version": "0.1.0",
+  "description": "Agent adapter — protectAgent() and action helpers for @sanctum-runtime/sdk",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Matik103/sanctum-runtime.git",
+    "directory": "packages/adapters/agent-runtime"
+  },
+  "homepage": "https://github.com/Matik103/sanctum-runtime#readme",
+  "bugs": {
+    "url": "https://github.com/Matik103/sanctum-runtime/issues"
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "runtime",
+    "security",
+    "middleware"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "prepublishOnly": "npm run build"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "dependencies": {
+    "@sanctum-runtime/sdk": "^0.1.0",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.0",
+    "typescript": "^5.8.3"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}