@pouchy_ai/admin-sdk 0.5.0 → 0.6.1

package/CHANGELOG.md

@@ -2,6 +2,63 @@
 
 All notable changes to `@pouchy_ai/admin-sdk` are documented here.
 
+## 0.6.1 — 2026-07-27
+
+Fix: the four long-running requests are no longer cut at 30s while the server is
+still working.
+
+- **Per-route request deadlines.** `POST /knowledge`, `POST /knowledge/file`,
+  `POST /knowledge/url` and `DELETE /users/{instanceId}` are the Admin API
+  handlers that declare `maxDuration: 300` — their response headers only arrive
+  when the ingest (chunk + summarize + embed, after OCR / Whisper / vision or an
+  SSRF-guarded page fetch) or the recursive GDPR erasure has FINISHED. Under the
+  flat 30s deadline a real PDF or a data-heavy instance rejected
+  `request timed out after 30000ms` while the operation kept running and
+  billing server-side, and the natural retry then raced the still-running first
+  ingest. Those four now default to `LONG_WORK_TIMEOUT_MS` (310s — the server's
+  own ceiling plus headroom); every other request keeps the 30s default, so a
+  genuinely hung server still fails fast.
+
+  This is the same defect the companion JS SDK fixed as `BUFFERED_TURN_TIMEOUT_MS`
+  (CR-141); 0.6.0 added `/knowledge/file` and `/knowledge/url` behind the old
+  flat deadline without porting it.
+
+- **`timeoutMs` still wins.** A host that sets `timeoutMs` explicitly gets it on
+  every request, long or short — only the DEFAULT is route-aware. No API surface
+  added or removed; purely widening for calls that previously failed.
+
+- New exports for hosts that want the contract in code:
+  `LONG_WORK_TIMEOUT_MS`, `LONG_WORK_REQUESTS`, `requestDeadlineMs(method, path)`.
+
+## 0.6.0 — 2026-07-21
+
+Additive: knowledge ingestion parity + headless agent version control. Both
+close a documented owner-console-only gap so the whole build-and-serve loop is
+now reachable with a `pchy_admin_…` key.
+
+- **Knowledge ingestion beyond raw text.** Three new methods mirror the
+  dashboard's knowledge tab, sharing the exact server-side pipelines:
+  - **`ingestKnowledgeFile({ dataUrl, name?, kind?, locale?, replaceDocId? })`**
+    — ingest a PDF / audio / video / image data URL; the server runs the same
+    understanding (OCR / Whisper / vision caption) as the SDK personal-materials
+    path, then chunks + embeds into the shared corpus.
+  - **`ingestKnowledgeUrl({ url, name?, locale?, replaceDocId? })`** — ingest a
+    web page (https only, SSRF-guarded fetch, HTML reduced to text).
+  - **`searchKnowledge(query)`** — recall probe: run the SAME retrieval an
+    instance turn uses and get the ranked chunks back, without burning an LLM
+    turn. `mode` is `semantic` or `lexical`.
+- **Agent version control (headless GitOps of a persona).** Six methods:
+  `listAgentVersions`, `getAgentVersion`, `diffAgentVersions`, `rollbackAgent`,
+  `getAgentPromotion`, `promoteAgent`. Inspect the rolling revision history,
+  diff any two revisions (or against `current`), roll back (git-revert
+  semantics), and drive staging→prod promotion — all previously
+  owner-session-only.
+
+Server: adds `POST /v1/admin/knowledge/{file,url,search}`,
+`GET /v1/admin/agents/{agentId}/versions[/{rev}|/diff]`,
+`POST /v1/admin/agents/{agentId}/versions/rollback`, and
+`GET|POST /v1/admin/agents/{agentId}/promote`. No breaking changes.
+
 ## 0.5.0 — 2026-07-17
 
 Additive: end-user listing pagination.

package/README.md

@@ -62,10 +62,24 @@ createAdminClient({
   adminKey: 'pchy_admin_…',   // required
   baseUrl: 'https://pouchy.ai/v1/admin', // optional (self-host / staging)
   fetch: myFetch,             // optional (Node <18, or tests)
-  timeoutMs: 30_000           // optional per-request timeout (default 30s)
+  timeoutMs: 30_000           // optional per-request timeout — see below
 });
 ```
 
+`timeoutMs` defaults to **30s**, except for the four requests whose server
+handler declares `maxDuration: 300` and therefore answers only when the work is
+finished — `POST /knowledge`, `POST /knowledge/file`, `POST /knowledge/url`
+(chunk + summarize + embed, after OCR / Whisper / vision or a page fetch) and
+`DELETE /users/{instanceId}` (recursive GDPR erasure). Those default to **310s**
+(`LONG_WORK_TIMEOUT_MS`), so a client abort can only ever mean "the server really
+is hung", never "the server is still working" — a shorter deadline there reports
+a failure for an ingest that is succeeding, and the retry it invites races the
+still-running first one.
+
+Setting `timeoutMs` explicitly always wins and applies to **every** request, long
+or short. `requestDeadlineMs(method, path)` returns the default a given request
+would use.
+
 ## Errors
 
 Every method throws `AdminApiError` on failure — a non-2xx response, a network
@@ -86,10 +100,11 @@ try {
 | Area | Methods |
 | --- | --- |
 | Agents | `listAgents` · `createAgent` · `getAgent` · `updateAgent` · `deleteAgent` |
+| Agent versions | `listAgentVersions` · `getAgentVersion` · `diffAgentVersions({ from?, to? })` · `rollbackAgent` · `getAgentPromotion` · `promoteAgent` (staging→prod) |
 | Voices | `listVoices({ gender?, age?, locale? })` — catalog for programmatic voice selection (each `CatalogVoice` carries `age`) |
 | Secret keys | `listKeys` · `createKey` · `revokeKey` · `rotateKey` (24 h grace) |
 | End users | `listUsers({ limit?, cursor? })` (cursor-paginated — the response's `nextCursor` feeds the next page; filter variants: `external_user_id` / `external_user_prefix`) · `setUserSuspended` · `deleteUser` · `getUserWallet` · `getUserTraces` · `importUsers` · `exportUser` · `getUserSessions` · `getUserTurns` |
-| Knowledge | `listKnowledge` · `ingestKnowledge` · `deleteKnowledge` |
+| Knowledge | `listKnowledge` · `ingestKnowledge` · `ingestKnowledgeFile` (PDF/audio/video/image) · `ingestKnowledgeUrl` (web page) · `searchKnowledge` (recall probe) · `deleteKnowledge` |
 | Skills | `listSkills` · `installSkill` · `updateSkill` · `setSkillRate` · `setSkillDailyCap` · `grantSkill` (free-HTTP) · `compileSkill` (prose→tools) · `uninstallSkill` |
 | Credentials | `listCredentials` · `putCredentials` · `deleteCredentials` |
 | Channels | `listChannels` · `createChannel` · `getChannel` · `updateChannel` · `deleteChannel` |

package/dist/index.d.ts

@@ -1,5 +1,34 @@
-export declare const ADMIN_SDK_VERSION = "0.5.0";
+export declare const ADMIN_SDK_VERSION = "0.6.1";
 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
+ *  "the server really is hung", never "the server is still working".
+ *
+ *  Why this exists: a flat client deadline BELOW a route's declared server
+ *  ceiling turns a succeeding, billed operation into a client-side
+ *  `request timed out`. The companion JS SDK hit exactly this (CR-141) and
+ *  fixed it with `BUFFERED_TURN_TIMEOUT_MS = 310_000`; on knowledge ingest it
+ *  is worse than a bad error message, because the integrator's natural retry
+ *  then races the still-running first ingest — the register's CR-14 interleave,
+ *  made systematic instead of rare. This SDK shipped the same flat 30s and, in
+ *  0.6.0, ADDED two more long routes behind it (`/knowledge/file`,
+ *  `/knowledge/url`). Same number as the JS constant, for the same reason. */
+export declare const LONG_WORK_TIMEOUT_MS = 310000;
+/** The Admin API requests whose handler declares `maxDuration: 300`.
+ *
+ *  Derived from the route files, not guessed — `sdk-deadlines.drift.test.ts`
+ *  binds this list to `export const config = { maxDuration }` in
+ *  `src/routes/v1/admin/**` in BOTH directions, so a new long-running admin
+ *  route (or a renamed one) fails a merge instead of silently shipping a
+ *  30s client cut. Paths are SDK-relative (the base URL already carries
+ *  `/v1/admin`). */
+export declare const LONG_WORK_REQUESTS: ReadonlyArray<{
+    method: string;
+    path: RegExp;
+}>;
+/** The deadline a given request runs under when the host set no `timeoutMs`.
+ *  Exported so the contract is assertable without timing anything. */
+export declare function requestDeadlineMs(method: string, path: string): number;
 export interface AdminClientOptions {
     /** A project Admin key (`pchy_admin_…`) from the dashboard Admin Keys page. */
     adminKey: string;
@@ -7,8 +36,12 @@ export interface AdminClientOptions {
     baseUrl?: string;
     /** Inject a fetch impl (Node <18, or for tests). Default global fetch. */
     fetch?: typeof fetch;
-    /** Per-request timeout in ms (default 30s). A request that outlives it
-     *  rejects with an AdminApiError(status 0). */
+    /** Per-request timeout in ms. Default 30s, EXCEPT the requests whose server
+     *  handler declares `maxDuration: 300` (knowledge ingest by text/file/url,
+     *  and the GDPR user delete), which default to
+     *  {@link LONG_WORK_TIMEOUT_MS}. Setting this explicitly always wins and
+     *  applies to every request, long or short. A request that outlives its
+     *  deadline rejects with an AdminApiError(status 0). */
     timeoutMs?: number;
 }
 /** Thrown on any non-2xx response. `status` is the HTTP status; `message` is the
@@ -132,6 +165,62 @@ export interface AdminClient {
     deleteAgent(agentId: string): Promise<{
         deleted: boolean;
     }>;
+    /** Archived template revisions, newest first. The live/current template is
+     *  NOT in here — it lives on the agent doc; a snapshot is created only when a
+     *  persona edit supersedes a rev. */
+    listAgentVersions(agentId: string): Promise<{
+        versions: Array<{
+            version: number;
+            templateRev: number;
+            archivedAt: string;
+            name: string;
+        }>;
+    }>;
+    /** One archived template snapshot — the full frozen agent for that revision. */
+    getAgentVersion(agentId: string, rev: number): Promise<{
+        version: Agent;
+    }>;
+    /** Field-level diff between two revisions. `from`/`to` are each an archived
+     *  version number or `current` (default) = the live template; only changed
+     *  fields are returned. */
+    diffAgentVersions(agentId: string, opts?: {
+        from?: number | 'current';
+        to?: number | 'current';
+    }): Promise<{
+        from: string;
+        to: string;
+        diff: Array<{
+            field: string;
+            from: unknown;
+            to: unknown;
+        }>;
+    }>;
+    /** Roll an agent back to an archived revision. git-revert semantics: the
+     *  snapshot re-applies as a NEW edit (rev moves forward), the current state is
+     *  archived first. */
+    rollbackAgent(agentId: string, version: number): Promise<{
+        agent: Agent;
+    }>;
+    /** Promotion status: the head (staging) vs the pinned production version, plus
+     *  the diff a promotion would ship (empty when in sync). `pending` is false
+     *  when the agent was never promoted (live follows the head). */
+    getAgentPromotion(agentId: string): Promise<{
+        stagingRev: number;
+        prodRev: number | null;
+        pending: boolean;
+        diff: Array<{
+            field: string;
+            from: unknown;
+            to: unknown;
+        }>;
+    }>;
+    /** Promote the head to production: freezes the head as an archived version and
+     *  pins prodRev WITHOUT bumping the rev. Live instances re-resolve on their
+     *  next mint; test instances always run the head. */
+    promoteAgent(agentId: string): Promise<{
+        prodRev: number;
+        templateRev: number;
+    }>;
     listKeys(): Promise<{
         keys: SecretKey[];
     }>;
@@ -230,6 +319,48 @@ export interface AdminClient {
             chunks: number;
         };
     }>;
+    /** Ingest a RAW file (PDF / audio / video / image data URL) into the shared
+     *  corpus — same server-side understanding (OCR / Whisper / vision caption)
+     *  as the SDK personal-materials path, then chunk + embed. `replaceDocId`
+     *  updates an existing doc in place. */
+    ingestKnowledgeFile(input: {
+        dataUrl: string;
+        name?: string;
+        kind?: string;
+        locale?: string;
+        replaceDocId?: string;
+    }): Promise<{
+        ok: boolean;
+        doc: {
+            docId: string;
+            chunks: number;
+        };
+        summary?: string;
+    }>;
+    /** Ingest a WEB PAGE by URL (https only, SSRF-guarded fetch, HTML reduced to
+     *  readable text server-side) into the shared corpus. */
+    ingestKnowledgeUrl(input: {
+        url: string;
+        name?: string;
+        locale?: string;
+        replaceDocId?: string;
+    }): Promise<{
+        ok: boolean;
+        doc: {
+            docId: string;
+            chunks: number;
+        };
+        summary?: string;
+        sourceUrl: string;
+    }>;
+    /** Recall probe: run the SAME retrieval an instance turn uses and get the
+     *  ranked chunks back, WITHOUT burning an LLM turn. `mode` is the recall
+     *  truth — `semantic` (vector path answered) or `lexical` (fallback). */
+    searchKnowledge(query: string): Promise<{
+        query: string;
+        mode: 'semantic' | 'lexical';
+        hits: unknown[];
+    }>;
     deleteKnowledge(docId: string): Promise<{
         deleted: boolean;
     }>;

package/dist/index.js

@@ -8,10 +8,53 @@
 //   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.5.0';
+export const ADMIN_SDK_VERSION = '0.6.1';
 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;
+/** 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
+ *  "the server really is hung", never "the server is still working".
+ *
+ *  Why this exists: a flat client deadline BELOW a route's declared server
+ *  ceiling turns a succeeding, billed operation into a client-side
+ *  `request timed out`. The companion JS SDK hit exactly this (CR-141) and
+ *  fixed it with `BUFFERED_TURN_TIMEOUT_MS = 310_000`; on knowledge ingest it
+ *  is worse than a bad error message, because the integrator's natural retry
+ *  then races the still-running first ingest — the register's CR-14 interleave,
+ *  made systematic instead of rare. This SDK shipped the same flat 30s and, in
+ *  0.6.0, ADDED two more long routes behind it (`/knowledge/file`,
+ *  `/knowledge/url`). Same number as the JS constant, for the same reason. */
+export const LONG_WORK_TIMEOUT_MS = 310_000;
+/** The Admin API requests whose handler declares `maxDuration: 300`.
+ *
+ *  Derived from the route files, not guessed — `sdk-deadlines.drift.test.ts`
+ *  binds this list to `export const config = { maxDuration }` in
+ *  `src/routes/v1/admin/**` in BOTH directions, so a new long-running admin
+ *  route (or a renamed one) fails a merge instead of silently shipping a
+ *  30s client cut. Paths are SDK-relative (the base URL already carries
+ *  `/v1/admin`). */
+export const LONG_WORK_REQUESTS = [
+    // Synchronous ingest: chunk + summarize + embed before headers.
+    { method: 'POST', path: /^\/knowledge$/ },
+    // …plus OCR / Whisper / vision understanding of the raw file first.
+    { method: 'POST', path: /^\/knowledge\/file$/ },
+    // …plus an SSRF-guarded fetch + HTML reduction first.
+    { method: 'POST', path: /^\/knowledge\/url$/ },
+    // 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\/[^/]+$/ }
+];
+/** The deadline a given request runs under when the host set no `timeoutMs`.
+ *  Exported so the contract is assertable without timing anything. */
+export function requestDeadlineMs(method, path) {
+    const bare = path.split('?')[0];
+    const m = method.toUpperCase();
+    return LONG_WORK_REQUESTS.some((r) => r.method === m && r.path.test(bare))
+        ? LONG_WORK_TIMEOUT_MS
+        : DEFAULT_TIMEOUT_MS;
+}
 /** Thrown on any non-2xx response. `status` is the HTTP status; `message` is the
  *  server's `error` string when present. */
 export class AdminApiError extends Error {
@@ -37,8 +80,11 @@ export function createAdminClient(opts) {
     const f = opts.fetch ?? globalThis.fetch;
     if (!f)
         throw new AdminApiError('no fetch available — pass opts.fetch on Node <18', 0);
-    const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
     async function request(method, path, body) {
+        // An explicit host `timeoutMs` always wins (JS SDK contract); otherwise
+        // the deadline is sized to the ROUTE, so the four handlers that declare
+        // `maxDuration: 300` are not cut at 30s while they are still working.
+        const timeoutMs = opts.timeoutMs ?? requestDeadlineMs(method, path);
         // Every failure surfaces as an AdminApiError (the doc contract): a
         // network/DNS error or a timeout would otherwise escape as a raw
         // `TypeError: fetch failed` / AbortError. Status 0 = never reached the
@@ -70,6 +116,12 @@ export function createAdminClient(opts) {
         getAgent: (id) => request('GET', `/agents/${encodeURIComponent(id)}`),
         updateAgent: (id, patch) => request('PATCH', `/agents/${encodeURIComponent(id)}`, patch),
         deleteAgent: (id) => request('DELETE', `/agents/${encodeURIComponent(id)}`),
+        listAgentVersions: (id) => request('GET', `/agents/${encodeURIComponent(id)}/versions`),
+        getAgentVersion: (id, rev) => request('GET', `/agents/${encodeURIComponent(id)}/versions/${rev}`),
+        diffAgentVersions: (id, opts = {}) => request('GET', `/agents/${encodeURIComponent(id)}/versions/diff${qs(opts)}`),
+        rollbackAgent: (id, version) => request('POST', `/agents/${encodeURIComponent(id)}/versions/rollback`, { version }),
+        getAgentPromotion: (id) => request('GET', `/agents/${encodeURIComponent(id)}/promote`),
+        promoteAgent: (id) => request('POST', `/agents/${encodeURIComponent(id)}/promote`, {}),
         listKeys: () => request('GET', '/keys'),
         createKey: (input) => request('POST', '/keys', input),
         revokeKey: (id) => request('DELETE', `/keys/${encodeURIComponent(id)}`),
@@ -85,6 +137,9 @@ export function createAdminClient(opts) {
         getUserTurns: (id, sessionId, params = {}) => request('GET', `/users/${encodeURIComponent(id)}/sessions/${encodeURIComponent(sessionId)}/turns${qs(params)}`),
         listKnowledge: () => request('GET', '/knowledge'),
         ingestKnowledge: (input) => request('POST', '/knowledge', input),
+        ingestKnowledgeFile: (input) => request('POST', '/knowledge/file', input),
+        ingestKnowledgeUrl: (input) => request('POST', '/knowledge/url', input),
+        searchKnowledge: (query) => request('POST', '/knowledge/search', { query }),
         deleteKnowledge: (id) => request('DELETE', `/knowledge/${encodeURIComponent(id)}`),
         listSkills: () => request('GET', '/skills'),
         installSkill: (input) => request('POST', '/skills', input),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pouchy_ai/admin-sdk",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "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",