@pouchy_ai/admin-sdk 0.16.0 → 0.17.0

package/CHANGELOG.md

@@ -2,6 +2,85 @@
 
 All notable changes to `@pouchy_ai/admin-sdk` are documented here.
 
+## 0.17.0 — 2026-08-07
+
+- **New `extractJson()` — structured JSON output, outside the companion.**
+  `POST /v1/admin/utility/json`. Additive; nothing else changed.
+
+  This exists because using a companion agent for extraction does not work, and
+  did not fail in a way that explained itself. A companion turn is a
+  conversation engine — persona prompt, memory recall, tools — and when the
+  model returns an empty completion it answers with a natural-language fallback
+  line rather than shipping an empty bubble. Correct for a chat surface, wrong
+  for a parser. An extraction prompt reliably *reaches* that fallback, because
+  the reasoning-effort bump off the cheapest tier is gated on conversational and
+  functional cues (weather, search, wallet, social) that an extraction input
+  never matches. The result was a soft chat sentence where JSON was expected.
+
+  `extractJson()` shares none of that machinery: no persona, no memory, no
+  tools, no session, no fallback. One provider call with `response_format` set,
+  and a parsed result.
+
+  ```ts
+  const { data } = await admin.extractJson<{ nickname: string | null }>({
+    content: '叫我 Alex',
+    schema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['nickname'],
+      properties: { nickname: { type: ['string', 'null'] } }
+    }
+  });
+  // → { nickname: 'Alex' }
+  ```
+
+- **`strict` defaults to true**, which asks the provider to ENFORCE the schema.
+  The schema must then sit inside the provider's structured-output subset: root
+  object, `additionalProperties: false`, and every property listed in
+  `required` — model an optional field as a union with `null` rather than by
+  omitting it from `required`. A schema outside the subset comes back as `400`
+  / `code: 'schema_invalid'` carrying the provider's own reason instead of
+  failing at generation time. Pass `strict: false` to fall back to plain JSON
+  mode plus server-side validation.
+
+- **Failures are typed, not prose.** `schema_invalid` (400 — fix the schema;
+  retrying verbatim cannot help), `unavailable` (5xx — transient, back off),
+  `invalid_json` (502 — a completion arrived but did not parse or did not
+  satisfy the schema). `invalid_json` carries `raw`, the text actually
+  returned, so the failure is debuggable rather than opaque.
+
+- **Note on schema key names.** The companion reply path strips objects
+  matching internal memory-pipeline signatures, among them
+  `{domain, key, value, label}` and `{content, kind, importance}`. That
+  stripping does not apply to this endpoint — but if you were previously
+  extracting through a companion agent with a schema shaped like either of
+  those, a *correct* answer could be removed before you saw it. Another reason
+  to move extraction here.
+
+## 0.16.1 — 2026-08-06
+
+Documentation only — no type, signature or runtime change. Two doc comments
+were describing a contract the server does not have.
+
+- **`updateSkill` said the response echoes "the knob(s) you changed".** It is
+  one knob per call. `PATCH /skills/{slug}` disambiguates by payload, so a
+  patch naming two groups — `{ ratePerMin, maxCallsPerDay }` — used to perform
+  whichever the server checked first and silently drop the rest under a `200`.
+  The plural in this package's own doc invited exactly that call. The server
+  now refuses an ambiguous body with a `400` naming the groups it found, and
+  the doc states the rule. `{ freeHttp, grantedDomains }` remains ONE knob (a
+  single write), not two.
+
+  The typed conveniences (`setSkillRate`, `setSkillDailyCap`, `grantSkill`)
+  were never affected — each sends exactly one knob by construction. Only a
+  hand-built `updateSkill` patch could reach it.
+
+- **`grantSkill` is a full REPLACE and did not say so.** `grantedDomains` is
+  optional in the signature, which reads as "leave it alone"; it is sent as
+  `[]` when omitted, clearing the extra allowlist. Pass the domains you want to
+  end up with on every call. (The manifest's own `allowed_domains` is a
+  separate list and is never touched by this call.)
+
 ## 0.16.0 — 2026-08-06
 
 - **Catches the package up to a server change that already shipped.**

package/README.md

@@ -58,6 +58,44 @@ console.log(`armed — ${armed.reprovisioned} running instance(s) updated`);
 // The agent can now drive the API from the skill's prose via http_request.
 ```
 
+### Structured JSON — use `extractJson`, not a companion agent
+
+```ts
+const { data } = await admin.extractJson<{ nickname: string | null }>({
+  content: '叫我 Alex',
+  schema: {
+    type: 'object',
+    additionalProperties: false,
+    required: ['nickname'],                 // strict mode: EVERY property, always
+    properties: { nickname: { type: ['string', 'null'] } }  // optional → union with null
+  }
+});
+console.log(data.nickname); // 'Alex'
+```
+
+A companion turn is a **conversation** engine — persona prompt, memory recall,
+tools — and when the model returns an empty completion it answers with a
+natural-language fallback line rather than an empty bubble. That is right for a
+chat surface and wrong for a parser, and an extraction prompt reliably reaches
+it, because the reasoning-effort bump off the cheapest tier is gated on
+conversational/functional cues an extraction input never matches. So a companion
+agent asked for JSON returns chat filler, fairly consistently.
+
+`extractJson` shares none of that: no persona, no memory, no tools, no session,
+no fallback — one provider call with `response_format` set. `strict` defaults to
+true, which makes the provider **enforce** the schema; the schema must then sit
+inside the provider's structured-output subset (root object,
+`additionalProperties: false`, every property listed in `required`). Pass
+`strict: false` for schemas outside it — you still get JSON mode plus
+server-side validation.
+
+Failures are typed rather than prose, so the recoveries are distinguishable:
+`schema_invalid` (400 — fix the schema; retrying verbatim cannot help),
+`unavailable` (5xx — transient, back off), and `invalid_json` (502 — a
+completion arrived but did not parse or satisfy the schema; the error carries
+`raw`, the text actually returned). Tokens roll into the project's month usage
+like any other model call.
+
 Every skill knob (`setSkillRate`, `setSkillDailyCap`, `grantSkill`) returns
 `SkillKnobResult<T>` — the knob you set plus `reprovisioned` (instances the new
 def reached) and `truncated`. A knob only binds a running agent once the def

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export declare const ADMIN_SDK_VERSION = "0.16.0";
+export declare const ADMIN_SDK_VERSION = "0.17.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
@@ -652,6 +652,49 @@ export interface AdminClient {
         mode: 'semantic' | 'lexical';
         hits: unknown[];
     }>;
+    /** Structured JSON extraction, OUTSIDE the companion.
+     *
+     *  Use this — not a companion agent — whenever you want machine-readable
+     *  output. A companion turn is a conversation engine: it carries a persona
+     *  prompt, recalls memory, and when the model returns nothing it answers with
+     *  a natural-language fallback line rather than dead air. That is right for a
+     *  chat bubble and wrong for a parser, and an extraction prompt reliably
+     *  triggers it, because the reasoning-effort bump off the cheapest tier is
+     *  gated on conversational/functional cues that an extraction input does not
+     *  match. This endpoint shares none of that: no persona, no memory, no tools,
+     *  no session, no fallback — one provider call with `response_format` set.
+     *
+     *  `strict` (default true) asks the provider to ENFORCE the schema. It must
+     *  then sit inside the provider's structured-output subset: a root object,
+     *  `additionalProperties: false`, and EVERY property listed in `required`
+     *  (model an optional field as a union with `null`, not by omitting it from
+     *  `required`). A schema outside the subset is rejected with `400` /
+     *  `code: 'schema_invalid'` naming the provider's reason — pass
+     *  `strict: false` to fall back to plain JSON mode plus server-side
+     *  validation.
+     *
+     *  Failures are typed rather than prose, which is the point:
+     *  `schema_invalid` (400 — fix the schema, retrying verbatim cannot help),
+     *  `unavailable` (5xx — transient, back off), `invalid_json` (502 — a
+     *  completion arrived but did not parse or did not satisfy the schema; the
+     *  error carries `raw`, the text actually returned).
+     *
+     *  Tokens roll into the project's month usage like any other model call. */
+    extractJson<T = unknown>(input: {
+        schema: Record<string, unknown>;
+        content: string;
+        system?: string;
+        strict?: boolean;
+        model?: string;
+        schemaName?: string;
+    }): Promise<{
+        data: T;
+        raw: string;
+        usage?: {
+            promptTokens: number;
+            completionTokens: number;
+        };
+    }>;
     deleteKnowledge(docId: string): Promise<{
         deleted: boolean;
     }>;
@@ -671,11 +714,15 @@ export interface AdminClient {
             version: number;
         };
     }>;
-    /** Generic PATCH of a skill's knobs. The response echoes the knob(s) you
-     *  changed plus the re-push outcome every knob now carries
-     *  (`reprovisioned`, `truncated`) — prefer the typed conveniences
-     *  (setSkillRate / setSkillDailyCap / grantSkill) for a precise return
-     *  type. */
+    /** Generic PATCH of a skill's knobs. **Exactly ONE knob per call** — the
+     *  endpoint disambiguates by payload, so a patch naming two (say
+     *  `{ ratePerMin, maxCallsPerDay }`) is refused with 400 rather than
+     *  half-applied. `{ freeHttp, grantedDomains }` is one knob, not two: the
+     *  grant is a single write. The response echoes the knob you changed plus
+     *  the re-push outcome every knob carries (`reprovisioned`, `truncated`).
+     *  Prefer the typed conveniences (setSkillRate / setSkillDailyCap /
+     *  grantSkill) — they are one knob each by construction and give a precise
+     *  return type. */
     updateSkill(slug: string, patch: Record<string, unknown>): Promise<Record<string, unknown>>;
     /** Set a skill's per-minute call budget (1..120; null restores the default).
      *  Re-pushes the def to running instances — the limiter reads the budget off
@@ -708,7 +755,12 @@ export interface AdminClient {
      *  `allowed_domains` ∪ `grantedDomains`. This is how a docs-only skill
      *  (no `tools:` block) becomes runnable — install it, attach it to an agent
      *  (`updateAgent(id, { skills: [...] })`), then grant it here. The new def is
-     *  re-pushed to running instances; `reprovisioned` is how many were updated. */
+     *  re-pushed to running instances; `reprovisioned` is how many were updated.
+     *
+     *  This is a full REPLACE of the grant, not a merge: omitting
+     *  `grantedDomains` sends `[]` and clears the extra allowlist (the manifest's
+     *  own `allowed_domains` is unaffected). Pass the domains you want to end up
+     *  with on every call. */
     grantSkill(slug: string, grant: {
         freeHttp: boolean;
         grantedDomains?: string[];

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.16.0';
+export const ADMIN_SDK_VERSION = '0.17.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;
@@ -247,6 +247,7 @@ export function createAdminClient(opts) {
         ingestKnowledgeFile: (input) => request('POST', '/knowledge/file', input),
         ingestKnowledgeUrl: (input) => request('POST', '/knowledge/url', input),
         searchKnowledge: (query) => request('POST', '/knowledge/search', { query }),
+        extractJson: (input) => request('POST', '/utility/json', input),
         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.16.0",
+  "version": "0.17.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",