@pouchy_ai/admin-sdk 0.7.1 → 0.8.0

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to `@pouchy_ai/admin-sdk` are documented here.
 
+## 0.8.0 — 2026-07-28
+
+- **Durable runs.** `listRuns`, `createRun`, `getRun`, `cancelRun`, `resumeRun`,
+  `signalRun` — long-running agent work that is checkpointed per step and
+  advanced by the platform across ticks, so it survives restarts and can span
+  minutes to hours.
+- The feature shipped server-side without this plane: the routes existed only
+  under `/v1/projects/{projectId}/…` (owner session auth), so an admin-key
+  integrator had no reachable endpoint at all. `/v1/admin/runs/*` now mirrors
+  them, and both planes share one implementation.
+- Note the status codes: every run mutation answers **202**, not 200/201. The
+  work happens on a later tick, never inside your request — treating the
+  response as a result is the mistake the code is chosen to prevent.
+
 ## 0.7.1 — 2026-07-27
 
 Fix: `timeoutMs: 0` now disables the deadline instead of aborting every request.

package/README.md

@@ -141,10 +141,56 @@ Reads (`GET`) are not covered by that bucket. `retryAfter` is available from
 | Credentials | `listCredentials` · `putCredentials` · `deleteCredentials` |
 | Channels | `listChannels` · `createChannel` · `getChannel` · `updateChannel` · `deleteChannel` |
 | Schedules | `listSchedules` · `createSchedule` · `getSchedule` · `updateSchedule` · `deleteSchedule` |
+| Durable runs | `listRuns` · `createRun` · `getRun` · `cancelRun` · `resumeRun` · `signalRun` |
 | 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 |
 
+### Durable runs
+
+A schedule *fires* one turn and is done. A **run** is long-lived agent work:
+checkpointed after every step and advanced by the platform across as many ticks
+as it needs, so it survives restarts and can span minutes to hours.
+
+Every mutation answers **202**, not 200/201 — the work happens on a later tick,
+never inside your request:
+
+```ts
+const agentId = 'agt_123';
+const { run } = await admin.createRun({
+  agentId,
+  externalUserId: 'user-42',
+  goal: 'Reconcile the overnight invoices and flag anything over $500.',
+  steps: [
+    { id: 'gather', kind: 'agent_turn' },
+    { id: 'ok', kind: 'human_approval', input: { prompt: 'Approve the flagged refunds?' } },
+    { id: 'apply', kind: 'agent_turn' }
+  ]
+});
+console.log(run.id, run.status); // → 'queued'
+```
+
+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
+token, and `getRun` always carries it:
+
+```ts
+const runId = 'run_abc';
+const { run } = await admin.getRun(runId);
+if (run.status === 'awaiting_human' && run.awaiting) {
+  await admin.resumeRun(runId, { approved: true, token: run.awaiting.token });
+}
+```
+
+The `token` is a fencing token, not a secret — authorization is your admin key.
+It exists so a stale or replayed decision cannot land on a question the run has
+already moved past (you get `409 stale_token`).
+
+An `await_event` step parks the same way until you call `signalRun` with the
+matching key; a mismatch answers `409 event_mismatch`, which lets a webhook
+retry tell "too late" from "rejected".
+
 ## OpenAPI
 
 The machine-readable contract is served at **`GET https://pouchy.ai/v1/admin/openapi`**

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export declare const ADMIN_SDK_VERSION = "0.7.1";
+export declare const ADMIN_SDK_VERSION = "0.8.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
@@ -166,6 +166,48 @@ export interface DeliveryOutcome {
 }
 /** The Admin API client. Every method returns the parsed JSON body; failures
  *  throw AdminApiError. */
+/** A durable run as the API returns it. Typed rather than `unknown` because
+ *  the parked-run flow — read `status`, read `awaiting.token`, answer — is the
+ *  SDK's most important interaction, and forcing a cast there would put the
+ *  burden on every integrator at exactly the wrong moment. */
+export interface AdminRunStep {
+    id: string;
+    kind?: string;
+    status: 'pending' | 'running' | 'succeeded' | 'failed' | 'compensated' | 'skipped';
+    attempts: number;
+    error?: string;
+    nextAttemptAt?: number;
+    output?: unknown;
+}
+export interface AdminRun {
+    id: string;
+    projectId: string;
+    agentId: string;
+    externalUserId: string;
+    goal: string;
+    status: 'queued' | 'running' | 'awaiting_human' | 'awaiting_event' | 'succeeded' | 'failed' | 'compensating' | 'compensated' | 'compensation_failed' | 'cancelled';
+    journal: AdminRunStep[];
+    /** Epoch ms the platform next looks at this run. Absent when terminal, or
+     *  parked on a human decision (only an answer moves it). */
+    wakeAt?: number;
+    /** Present while parked on a person. `token` fences your answer against a
+     *  stale or replayed decision — it is not a secret. */
+    awaiting?: {
+        token: string;
+        prompt: string;
+        stepId: string;
+        since: number;
+    };
+    /** Present while parked on an external event, with its deadline if it has one. */
+    awaitingEvent?: {
+        key: string;
+        stepId: string;
+        since: number;
+        timeoutAt?: number;
+    };
+    createdAt: string;
+    updatedAt: string;
+}
 export interface AdminClient {
     listAgents(): Promise<{
         agents: Agent[];
@@ -521,6 +563,67 @@ export interface AdminClient {
     deleteSchedule(scheduleId: string): Promise<{
         ok: boolean;
     }>;
+    listRuns(query?: {
+        status?: string;
+        limit?: number;
+    }): Promise<{
+        runs: AdminRun[];
+    }>;
+    /** Start a durable run. Omit `steps` for the common case — a single agent
+     *  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. */
+    createRun(input: {
+        agentId: string;
+        externalUserId: string;
+        goal: string;
+        env?: 'live' | 'test';
+        startAt?: number;
+        steps?: {
+            id: string;
+            kind?: string;
+            input?: Record<string, unknown>;
+        }[];
+    }): Promise<{
+        run: AdminRun;
+    }>;
+    /** Fetch a run with its full step journal — what ran, what retried, what was
+     *  rolled back. For a failed run this is the only place the reason survives. */
+    getRun(runId: string): Promise<{
+        run: AdminRun;
+    }>;
+    /** Request cancellation. The run stops at the next STEP BOUNDARY and then
+     *  rolls back completed work, so this returns `status: 'cancelling'`. */
+    cancelRun(runId: string): Promise<{
+        ok: boolean;
+        status: string;
+    }>;
+    /** Answer a run parked on a human decision. `token` comes from the run's
+     *  `awaiting.token` (also carried by the `agent.run_awaiting` webhook) and
+     *  fences the decision against a stale or replayed answer. Without this call
+     *  a parked run never resumes: it holds no lease and has left the platform's
+     *  due window by design. */
+    resumeRun(runId: string, input: {
+        approved: boolean;
+        token: string;
+        note?: string;
+    }): Promise<{
+        ok: boolean;
+        approved: boolean;
+        status: string;
+    }>;
+    /** Deliver an external event to a run parked on one. `event` must equal the
+     *  key the run is waiting for — a mismatch answers 409 `event_mismatch`, so a
+     *  webhook retry can tell "too late" from "rejected". */
+    signalRun(runId: string, input: {
+        event: string;
+        payload?: unknown;
+    }): Promise<{
+        ok: boolean;
+        event: string;
+        status: string;
+    }>;
     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.7.1';
+export const ADMIN_SDK_VERSION = '0.8.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;
@@ -223,6 +223,20 @@ export function createAdminClient(opts) {
         getSchedule: (id) => request('GET', `/schedules/${encodeURIComponent(id)}`),
         updateSchedule: (id, patch) => request('PATCH', `/schedules/${encodeURIComponent(id)}`, patch),
         deleteSchedule: (id) => request('DELETE', `/schedules/${encodeURIComponent(id)}`),
+        listRuns: (q) => {
+            const qs = new URLSearchParams();
+            if (q?.status)
+                qs.set('status', q.status);
+            if (typeof q?.limit === 'number')
+                qs.set('limit', String(q.limit));
+            const tail = qs.toString();
+            return request('GET', `/runs${tail ? `?${tail}` : ''}`);
+        },
+        createRun: (input) => request('POST', '/runs', input),
+        getRun: (id) => request('GET', `/runs/${encodeURIComponent(id)}`),
+        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),
         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.7.1",
+  "version": "0.8.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",