@pouchy_ai/admin-sdk 0.15.1 → 0.16.1

package/CHANGELOG.md

@@ -2,6 +2,57 @@
 
 All notable changes to `@pouchy_ai/admin-sdk` are documented 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.**
+  `PATCH /skills/{slug}` with `{ ratePerMin }` used to be the only skill knob
+  that did not push the updated def to the project's running instances — and the
+  per-minute budget is read off each instance's provisioned def, not the record
+  the PATCH writes, so a rate you set persisted, echoed back on read, and reached
+  **no running agent** until an unrelated persona edit bumped the agent's
+  `templateRev`. That was fixed server-side, and every knob now also returns
+  `truncated`. This package still typed the old shapes — `setSkillRate` as
+  `Promise<{ ratePerMin }>`, the other two without `truncated` — so the typed
+  client was asserting a contract the server had already stopped honouring.
+
+- **New `SkillKnobResult<T>` — every skill knob returns `reprovisioned` and
+  `truncated`.** `setSkillRate`, `setSkillDailyCap` and `grantSkill` now share
+  one result shape. `truncated: true` means the re-push swept its cap (100
+  agents / 200 instances) and the remainder were NOT refreshed — and they do not
+  catch up on their next session, they keep the OLD def until a persona edit
+  bumps `templateRev`. **A revoking call that returns `truncated: true` is a
+  PARTIAL revocation**; re-issue it or make a persona edit before treating it as
+  complete.
+
+  Additive and backward compatible: the previously-returned fields are all still
+  present with the same names and types, so existing destructuring keeps
+  compiling. Only widen your own annotations if you had hand-written the old
+  return types.
+
 ## 0.15.1 — 2026-08-03
 
 - **Docs fix: `MonthUsage.mauLimit` prescribed a call that does not compile.**

package/README.md

@@ -58,6 +58,14 @@ console.log(`armed — ${armed.reprovisioned} running instance(s) updated`);
 // The agent can now drive the API from the skill's prose via http_request.
 ```
 
+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
+reaches its instance, so `truncated: true` means the sweep hit its cap (100
+agents / 200 instances) and the remainder still hold the **old** def; they do
+not catch up on their next session. Treat a *revoking* call that returns
+`truncated: true` as a partial revocation and re-issue it.
+
 ## Options
 
 ```ts

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export declare const ADMIN_SDK_VERSION = "0.15.1";
+export declare const ADMIN_SDK_VERSION = "0.16.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
@@ -421,6 +421,21 @@ export interface AdminRun {
     createdAt: string;
     updatedAt: string;
 }
+/** What every skill-knob PATCH reports about the re-push, on top of the knob it
+ *  echoes. A knob only takes effect on a running agent once the def reaches its
+ *  instance, so these two fields are the outcome, not decoration.
+ *
+ *  `reprovisioned` — instances refreshed by this call.
+ *  `truncated` — the sweep hit a cap (100 agents / 200 instances) and the
+ *  remainder were NOT refreshed. They do not catch up on their next session:
+ *  they keep the OLD def until a persona edit bumps the agent's templateRev. So
+ *  a revoking call (e.g. clearing a grant) that returns `truncated: true` is a
+ *  PARTIAL revocation — re-issue it, or make a persona edit, before treating it
+ *  as complete. */
+export type SkillKnobResult<T> = T & {
+    reprovisioned: number;
+    truncated: boolean;
+};
 export interface AdminClient {
     listAgents(): Promise<{
         agents: Agent[];
@@ -656,23 +671,30 @@ export interface AdminClient {
             version: number;
         };
     }>;
-    /** Generic PATCH of a skill's knobs. The response echoes only the knob(s)
-     *  you changed (e.g. `{ ratePerMin }`, `{ maxCallsPerDay, reprovisioned }`,
-     *  `{ freeHttp, grantedDomains, reprovisioned }`) — prefer the typed
-     *  conveniences (setSkillRate / setSkillDailyCap / grantSkill) for a precise
+    /** 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). */
-    setSkillRate(slug: string, ratePerMin: number | null): Promise<{
+    /** 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
+     *  each instance's provisioned def, so a saved rate that was not re-pushed
+     *  reached no running agent (server-side fix; this signature now carries the
+     *  outcome the other knobs already returned). */
+    setSkillRate(slug: string, ratePerMin: number | null): Promise<SkillKnobResult<{
         ratePerMin: number | null;
-    }>;
+    }>>;
     /** Set a skill's opt-in daily call ceiling — max HTTP calls per rolling 24h
      *  (1..20000; null clears it, leaving only the per-minute cap). A runaway
      *  guard for autonomous outbound. Re-pushes the def to running instances. */
-    setSkillDailyCap(slug: string, maxCallsPerDay: number | null): Promise<{
+    setSkillDailyCap(slug: string, maxCallsPerDay: number | null): Promise<SkillKnobResult<{
         maxCallsPerDay: number | null;
-        reprovisioned: number;
-    }>;
+    }>>;
     /** Compile a docs-only skill's prose (curl snippets / endpoint tables) into
      *  declared `http` tools via a one-shot LLM, then re-install the result
      *  (safety gate + version archive → reversible via rollback). Each tool is
@@ -690,15 +712,19 @@ 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[];
-    }): Promise<{
+    }): Promise<SkillKnobResult<{
         freeHttp: boolean;
         grantedDomains: string[];
-        reprovisioned: number;
-    }>;
+    }>>;
     uninstallSkill(slug: string): Promise<{
         deleted: boolean;
     }>;

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.15.1';
+export const ADMIN_SDK_VERSION = '0.16.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;

package/package.json

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