@pouchy_ai/admin-sdk 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 All notable changes to `@pouchy_ai/admin-sdk` are documented here.
 
+## 0.11.0 — 2026-08-01
+
+- **Data capabilities, headless.** Six new methods over the `/v1/admin/capabilities`
+  mirror: `listCapabilities` (heads + masked signing status — the `pcsk_`
+  plaintext is issued once on the owner plane and is never readable through any
+  API), `publishCapability` (immutable next version; idempotent on content),
+  `setCapabilityDisabled` (per-capability live revoke — live both directions,
+  pinned reconciliations unaffected), `listCapabilityVersions` (append-only
+  history; rollback = republishing an old declaration as the next version),
+  `testReadCapability`, and `testActionCapability` (the four-phase Action
+  protocol verifier; the server refuses without `confirmDuplicates: true`
+  because phases B/C intentionally re-deliver the same `actionId`).
+- `POST /capabilities/{name}/test-action` joins `LONG_WORK_REQUESTS`: the
+  verifier makes real round-trips to YOUR endpoint, and aborting mid-test
+  cannot undo phase A's side effect — so the default deadline is the long one.
+
 ## 0.10.0 — 2026-07-29
 
 - **`AdminApiError.code` — the Admin API's machine-readable failure tag.** The

package/README.md

@@ -203,6 +203,7 @@ Channel types are checked at compile time: `createChannel` takes a
 `CreatableChannelType` (the platform's 31-transport union minus the adapterless
 `internal-a2a`), and `secret` is a named `ChannelSecretInput`. Per-transport
 `secret.extra` fields are listed in <https://pouchy.ai/docs/channel-setup>.
+| Data capabilities | `listCapabilities` (heads + MASKED signing status) · `publishCapability` (immutable next version, idempotent on content) · `setCapabilityDisabled` (per-capability live revoke) · `listCapabilityVersions` (history; rollback = republish an old declaration) · `testReadCapability` · `testActionCapability({ confirmDuplicates: true, … })` (REAL deliveries incl. intentional duplicates — 428 without consent) |
 | Webhooks | `listWebhooks` · `createWebhook` · `updateWebhook` · `rotateWebhookSecret` · `deleteWebhook` · `testWebhook` · `redeliverWebhook` |
 | Reporting | `getUsage` · `getBilling` · `getTracesSummary` · `getRecentTraces` · `getLogs` · `getProject` · `updateProject` |
 | Escape hatch | `request(method, path, body?)` — any endpoint not yet typed |
@@ -231,6 +232,11 @@ const { run } = await admin.createRun({
 console.log(run.id, run.status); // → 'queued'
 ```
 
+A `subtask_fanout` step runs at most **4** subtasks (`input.subtasks`).
+Declaring more is a **400** naming the cap rather than a silent trim — split
+the remainder into a second fan-out step. Entries without a non-empty `goal`
+are ignored and do not count against the cap.
+
 When a run reaches a `human_approval` step it **parks**: it holds no lease and
 leaves the platform's due window, so nothing will move it until you answer.
 You learn about it either way — the `agent.run_awaiting` webhook pushes the

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export declare const ADMIN_SDK_VERSION = "0.10.0";
+export declare const ADMIN_SDK_VERSION = "0.11.0";
 export declare const DEFAULT_BASE_URL = "https://pouchy.ai/v1/admin";
 /** Deadline for the routes whose server handler declares `maxDuration: 300` —
  *  the server's own ceiling plus headroom, so a client abort can only ever mean
@@ -623,7 +623,12 @@ export interface AdminClient {
      *  turn carrying `goal`. Step ids must be unique and match
      *  `[A-Za-z0-9_-]{1,64}`; `kind` is one of `agent_turn`, `subtask_fanout`,
      *  `human_approval`, `await_event`. Answers **202**, not 201: the run is
-     *  accepted and has not run yet. */
+     *  accepted and has not run yet.
+     *
+     *  A `subtask_fanout` step runs at most **4** subtasks (`input.subtasks`).
+     *  Declaring more is a **400** naming the cap, not a silent trim — split the
+     *  remainder into a second fan-out step. Entries without a non-empty `goal`
+     *  are ignored and do not count against the cap. */
     createRun(input: {
         agentId: string;
         externalUserId: string;
@@ -686,6 +691,72 @@ export interface AdminClient {
         event: string;
         status: string;
     }>;
+    /** Capability heads + MASKED signing status (key IDs and rotation state
+     *  only — the `pcsk_` plaintext is issued ONCE on the owner plane and is
+     *  never readable through any API). */
+    listCapabilities(): Promise<{
+        capabilities: Array<{
+            capabilityId: string;
+            name: string;
+            kind: string;
+            latestVersion: number;
+            disabled?: boolean;
+        }>;
+        signing: {
+            activeKeyId: string;
+            previousKeyId: string | null;
+        } | null;
+    }>;
+    /** Publish the next IMMUTABLE revision. Idempotent on content: an unchanged
+     *  manifest returns the existing version with `created: false`; different
+     *  bytes mint version+1 and never rewrite an old one. Publishing is NOT
+     *  revocation — the per-agent data flags and `setCapabilityDisabled` are
+     *  the live levers. */
+    publishCapability(declaration: Record<string, unknown>): Promise<{
+        revision: {
+            capabilityId: string;
+            version: number;
+            revisionHash: string;
+        };
+        created: boolean;
+    }>;
+    /** Per-capability live revoke: flips the head's `disabled` bit. Live in
+     *  BOTH directions on the next resolution — existing sessions lose it from
+     *  their next turn, new plans/ingress see honest absence; a reconciliation
+     *  pinned to a revision keeps reconciling. */
+    setCapabilityDisabled(name: string, disabled: boolean): Promise<{
+        name: string;
+        disabled: boolean;
+    }>;
+    /** Full version history, newest first, WITH declaration bodies. There is no
+     *  rollback verb: restoring vN = `publishCapability(versions[i].declaration)`,
+     *  which mints it as the NEXT version (history stays append-only). */
+    listCapabilityVersions(name: string): Promise<{
+        versions: Array<{
+            version: number;
+            revisionHash: string;
+            publishedAt: string;
+            declaration: Record<string, unknown>;
+        }>;
+    }>;
+    /** View integration test: real pinned revision + production signer; returns
+     *  the curated rows exactly as an agent would see them, the menu/model
+     *  bytes, and DECODED (never signed, never replayable) claims. */
+    testReadCapability(name: string, input?: {
+        externalUserId?: string;
+        filters?: Record<string, unknown>;
+    }): Promise<Record<string, unknown>>;
+    /** Action protocol verifier — four phases (connectivity, duplicate
+     *  same-intent, mismatch, reconcile) against your REAL endpoint, including
+     *  intentional duplicate deliveries of one actionId; the server refuses
+     *  (428) without `confirmDuplicates: true`. Phase outcomes use production
+     *  vocabulary (committed/rejected/unknown) SEPARATELY from protocol
+     *  verdicts — "Protocol: PASS, outcome: unknown" is a valid result. */
+    testActionCapability(name: string, input: {
+        confirmDuplicates: true;
+        args?: Record<string, unknown>;
+        externalUserId?: string;
+    }): Promise<Record<string, unknown>>;
     listWebhooks(): Promise<{
         webhooks: unknown[];
     }>;

package/dist/index.js

@@ -8,7 +8,7 @@
 //   import { createAdminClient } from '@pouchy_ai/admin-sdk';
 //   const admin = createAdminClient({ adminKey: process.env.POUCHY_ADMIN_KEY! });
 //   const { agents } = await admin.listAgents();
-export const ADMIN_SDK_VERSION = '0.10.0';
+export const ADMIN_SDK_VERSION = '0.11.0';
 export const DEFAULT_BASE_URL = 'https://pouchy.ai/v1/admin';
 /** Default per-request timeout (ms). A hung upstream otherwise never rejects. */
 const DEFAULT_TIMEOUT_MS = 30_000;
@@ -44,7 +44,12 @@ export const LONG_WORK_REQUESTS = [
     // GDPR erasure: recursive delete of the instance's whole users/** subtree
     // plus the top-level social graph. A client abort here is the worst of the
     // four — the operator is left not knowing whether the wipe completed.
-    { method: 'DELETE', path: /^\/users\/[^/]+$/ }
+    { method: 'DELETE', path: /^\/users\/[^/]+$/ },
+    // The Action protocol verifier makes REAL deliveries to the developer's
+    // endpoint (four phases incl. reconcile) — network round-trips we don't
+    // control the latency of. An abort mid-test also cannot undo phase A's
+    // side effect, so waiting is strictly better than cutting.
+    { method: 'POST', path: /^\/capabilities\/[^/]+\/test-action$/ }
 ];
 /** The deadline a given request runs under when the host set no `timeoutMs`.
  *  Exported so the contract is assertable without timing anything. */
@@ -281,6 +286,12 @@ export function createAdminClient(opts) {
         cancelRun: (id) => request('DELETE', `/runs/${encodeURIComponent(id)}`),
         resumeRun: (id, input) => request('POST', `/runs/${encodeURIComponent(id)}/resume`, input),
         signalRun: (id, input) => request('POST', `/runs/${encodeURIComponent(id)}/signal`, input),
+        listCapabilities: () => request('GET', '/capabilities'),
+        publishCapability: (declaration) => request('POST', '/capabilities', declaration),
+        setCapabilityDisabled: (name, disabled) => request('PATCH', `/capabilities/${encodeURIComponent(name)}`, { disabled }),
+        listCapabilityVersions: (name) => request('GET', `/capabilities/${encodeURIComponent(name)}/versions`),
+        testReadCapability: (name, input = {}) => request('POST', `/capabilities/${encodeURIComponent(name)}/test-read`, input),
+        testActionCapability: (name, input) => request('POST', `/capabilities/${encodeURIComponent(name)}/test-action`, input),
         listWebhooks: () => request('GET', '/webhooks'),
         createWebhook: (input) => request('POST', '/webhooks', input),
         deleteWebhook: (id) => request('DELETE', `/webhooks/${encodeURIComponent(id)}`),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pouchy_ai/admin-sdk",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Typed TypeScript client for the Pouchy Admin API \u2014 manage agents, keys, end users, knowledge, skills, channels, schedules, webhooks and credentials headlessly, with a project Admin key.",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",