@pouchy_ai/admin-sdk 0.28.0 → 0.30.0

package/CHANGELOG.md

@@ -2,6 +2,46 @@
 
 All notable changes to `@pouchy_ai/admin-sdk` are documented here.
 
+## 0.30.0 — 2026-09-04
+
+- **`internal-a2a` leaves `ChannelTransportType`.** It was a placeholder the
+  platform's union and store knew and no adapter served — `createChannel`
+  answered 400 on it, which is why `CreatableChannelType` excluded it. The
+  platform retired the id (design #24 / F-04: the friend auto-reply is a
+  companion session SURFACE, not a transport), so the union no longer names it
+  and `CreatableChannelType` is now the whole union. A caller that referenced
+  the literal type gets a compile error, which is the point; nothing that ever
+  worked changes.
+
+## 0.29.1 — 2026-09-04
+
+- **`story_contract_v4_write_disabled`** joins `ADMIN_ERROR_CODES` — a Story
+  Package publish that declares a `public: true` flag (Story Contract v4,
+  design #23) answers 409 with this code in an environment that has not
+  enabled v4 writes, the field intact. Vocabulary only; no method changed.
+
+## 0.29.0 — 2026-08-31
+
+- **`setSkillAutoRunTools(slug, toolNames)` — the per-tool confirm exemptions
+  (免确认工具) the Admin API could not reach.** Admin API 1.12.0. The knob
+  existed on the owner plane and in the dashboard since 2026-08 and was never
+  added here, so a headless provisioning flow could install a skill, rate-limit
+  it, grant its domains and attach it to an agent — and then answer nothing.
+  For MCP skills that is not an edge case: `mcpRecord` hard-codes
+  `platformSafe: false`, so every `run_skill` raises a confirm, and a platform
+  instance has no human who could ever approve one. This was the only route out.
+
+  A full REPLACE, not a merge — pass the complete list each call. Names the
+  skill does not declare are dropped and echoed in `dropped`, so a typo is
+  visible rather than silently ungranted. Grant the READ tools (a storefront's
+  `search_catalog` / `get_product`); leave cart mutations and order placement
+  gated.
+
+  Opening this to a long-lived admin key was an explicit decision, not a
+  symmetry fix: the confirm being waived is not a human in the loop (on an
+  instance nobody can approve it), and the same key already grants the strictly
+  wider `freeHttp` + `grantedDomains`.
+
 ## 0.28.0 — 2026-08-29
 
 - **`installSkill` / `importAgentPlugin` now type the re-push outcome.** Both

package/README.md

@@ -243,7 +243,8 @@ that voice, or the voice catalog is temporarily unreachable; retry),
 like the other voice planes — there is no separate platform credit rate; it is
 bounded by an input cap and the shared per-IP utility rate limit.
 
-Every skill knob (`setSkillRate`, `setSkillDailyCap`, `grantSkill`) returns
+Every skill knob (`setSkillRate`, `setSkillDailyCap`, `grantSkill`,
+`setSkillAutoRunTools`) 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
@@ -307,15 +308,19 @@ createAdminClient({
 });
 ```
 
-`timeoutMs` defaults to **30s**, except for the four requests whose server
-handler declares `maxDuration: 300` and therefore answers only when the work is
+`timeoutMs` defaults to **30s**, except for the 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.
+(chunk + summarize + embed, after OCR / Whisper / vision or a page fetch),
+`DELETE /users/{instanceId}` (recursive GDPR erasure) and
+`POST /capabilities/{name}/test-action` (the Action protocol verifier makes
+REAL deliveries to your endpoint, and an abort mid-test cannot undo the ones
+already made). 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 (or
+re-runs a side-effecting test whose first verdict is never read). The list is
+`LONG_WORK_REQUESTS`, exported, and a drift test binds it to the routes.
 
 Setting `timeoutMs` explicitly always wins and applies to **every** request, long
 or short. `requestDeadlineMs(method, path)` returns the default a given request
@@ -436,7 +441,7 @@ Reads (`GET`) are not covered by that bucket. `retryAfter` is available from
 | 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` · `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` · `importAgentPlugin` / `exportAgentPlugin` (Agent Plugins 1.0.0 interop) |
+| Skills | `listSkills` · `installSkill` · `updateSkill` · `setSkillRate` · `setSkillDailyCap` · `grantSkill` (free-HTTP) · `setSkillAutoRunTools` (免确认工具 — required to arm an MCP skill on an instance) · `compileSkill` (prose→tools) · `uninstallSkill` · `importAgentPlugin` / `exportAgentPlugin` (Agent Plugins 1.0.0 interop) |
 | Credentials | `listCredentials` · `putCredentials` · `deleteCredentials` |
 | Channels | `listChannels` · `createChannel` · `getChannel` · `updateChannel` · `deleteChannel` |
 | Schedules | `listSchedules` · `createSchedule` · `getSchedule` · `updateSchedule` · `deleteSchedule` |
@@ -448,8 +453,8 @@ Reads (`GET`) are not covered by that bucket. `retryAfter` is available from
 | Escape hatch | `request(method, path, body?)` — any endpoint not yet typed |
 
 Channel types are checked at compile time: `createChannel` takes a
-`CreatableChannelType` (the platform's 82-transport union minus the adapterless
-`internal-a2a`), and `secret` is a named `ChannelSecretInput`. Per-transport
+`CreatableChannelType` (the platform's 81-transport union — every member has an
+adapter since 0.30.0), and `secret` is a named `ChannelSecretInput`. Per-transport
 `secret.extra` fields are listed in <https://pouchy.ai/docs/channel-setup>.
 
 **Telegram and Discord register themselves.** On create — and again on a

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export declare const ADMIN_SDK_VERSION = "0.28.0";
+export declare const ADMIN_SDK_VERSION = "0.30.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
@@ -38,7 +38,8 @@ export interface AdminClientOptions {
     fetch?: typeof fetch;
     /** 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
+     *  the GDPR user delete, and the capability test-action verifier — the
+     *  list is {@link LONG_WORK_REQUESTS}), 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).
@@ -59,7 +60,7 @@ export interface AdminClientOptions {
  *  published: on this plane the status line never disambiguates, so two of the
  *  durable-run routes answer 409 for two entirely different reasons each, with
  *  different recoveries. `code` is the only thing that tells them apart. */
-export declare const ADMIN_ERROR_CODES: readonly ["story_contract_v2_write_disabled", "story_contract_v3_write_disabled", "episode_history_incomplete", "episode_ended", "idempotency_key_reused", "stale_deliberation", "deliberation_disabled", "deliberation_uncalibrated", "deliberation_not_enabled", "deliberation_candidates_exceeded", "schedule_limit_reached", "one_shot_spent", "ghost_row", "channel_limit_reached", "webhook_limit_reached", "run_limit_reached", "reembed_required", "run_terminal", "run_not_parked", "stale_token", "run_not_waiting", "event_mismatch"];
+export declare const ADMIN_ERROR_CODES: readonly ["story_contract_v2_write_disabled", "story_contract_v3_write_disabled", "story_contract_v4_write_disabled", "episode_history_incomplete", "episode_ended", "idempotency_key_reused", "stale_deliberation", "deliberation_disabled", "deliberation_uncalibrated", "deliberation_not_enabled", "deliberation_candidates_exceeded", "schedule_limit_reached", "one_shot_spent", "ghost_row", "channel_limit_reached", "webhook_limit_reached", "run_limit_reached", "reembed_required", "run_terminal", "run_not_parked", "stale_token", "run_not_waiting", "event_mismatch"];
 /** `AdminApiError.code` values. The `(string & {})` arm keeps the type open for
  *  codes newer than this SDK build while preserving autocomplete — same
  *  doctrine as the companion SDK's `CompanionErrorCodeValue`. */
@@ -332,11 +333,12 @@ export interface DeliveryOutcome {
  *  (`channels/types.ts`) — this package is standalone and cannot import it, so
  *  `admin-sdk-channel-types.drift.test.ts` binds the two and fails CI if either
  *  side gains a transport the other lacks. */
-export type ChannelTransportType = 'echo' | 'matrix' | 'telegram' | 'web' | 'activitypub' | 'internal-a2a' | 'discord' | 'slack' | 'nostr' | 'atproto' | 'sms' | 'email' | 'whatsapp' | 'messenger' | 'instagram' | 'line' | 'teams' | 'wechat' | 'wecom' | 'feishu' | 'dingtalk' | 'twitter' | 'xmpp' | 'qq' | 'kakao' | 'viber' | 'signal' | 'weibo' | 'alexa' | 'google-assistant' | 'voice' | 'onlyfans' | 'fansly' | 'fanvue' | 'imessage' | 'rcs' | 'intercom' | 'twitch' | 'zalo' | 'douyin' | 'kick' | 'reddit' | 'xmtp' | 'guilded' | 'youtube-live' | 'bilibili-live' | 'minecraft' | 'steam' | 'vk' | 'ok' | 'threads' | 'groupme' | 'threema' | 'mattermost' | 'rocketchat' | 'zulip' | 'farcaster' | 'tiktok' | 'crisp' | 'freshchat' | 'front' | 'gorgias' | 'kustomer' | 'helpscout' | 'livechat' | 'zohodesk' | 'hubspot' | 'zendesk' | 'salesforce' | 'webex' | 'chatwork' | 'google-chat' | 'zohocliq' | 'zoom' | 'line-works' | 'ringcentral' | 'vonage' | 'github' | 'gitlab' | 'bitbucket' | 'jira' | 'linear' | 'discourse';
-/** Transports `createChannel` accepts. `internal-a2a` is in the union but has
- *  no adapter, so the server answers 400 — excluding it here turns a runtime
- *  rejection into a compile error. */
-export type CreatableChannelType = Exclude<ChannelTransportType, 'internal-a2a'>;
+export type ChannelTransportType = 'echo' | 'matrix' | 'telegram' | 'web' | 'activitypub' | 'discord' | 'slack' | 'nostr' | 'atproto' | 'sms' | 'email' | 'whatsapp' | 'messenger' | 'instagram' | 'line' | 'teams' | 'wechat' | 'wecom' | 'feishu' | 'dingtalk' | 'twitter' | 'xmpp' | 'qq' | 'kakao' | 'viber' | 'signal' | 'weibo' | 'alexa' | 'google-assistant' | 'voice' | 'onlyfans' | 'fansly' | 'fanvue' | 'imessage' | 'rcs' | 'intercom' | 'twitch' | 'zalo' | 'douyin' | 'kick' | 'reddit' | 'xmtp' | 'guilded' | 'youtube-live' | 'bilibili-live' | 'minecraft' | 'steam' | 'vk' | 'ok' | 'threads' | 'groupme' | 'threema' | 'mattermost' | 'rocketchat' | 'zulip' | 'farcaster' | 'tiktok' | 'crisp' | 'freshchat' | 'front' | 'gorgias' | 'kustomer' | 'helpscout' | 'livechat' | 'zohodesk' | 'hubspot' | 'zendesk' | 'salesforce' | 'webex' | 'chatwork' | 'google-chat' | 'zohocliq' | 'zoom' | 'line-works' | 'ringcentral' | 'vonage' | 'github' | 'gitlab' | 'bitbucket' | 'jira' | 'linear' | 'discourse';
+/** Transports `createChannel` accepts — the whole union, since 0.30.0: the
+ *  adapterless `internal-a2a` placeholder this type used to exclude was
+ *  retired from the platform's union (design #24 / F-04). Kept as a named
+ *  alias so existing imports compile unchanged. */
+export type CreatableChannelType = ChannelTransportType;
 /** Credentials for a connector, sealed server-side as one AES-GCM blob.
  *
  *  `extra` is where the transports needing more than a token live — Twitter
@@ -888,6 +890,25 @@ export interface AdminClient {
         freeHttp: boolean;
         grantedDomains: string[];
     }>>;
+    /** Per-tool confirm exemptions (免确认工具) — the tools an INSTANCE may call
+     *  without a confirm card.
+     *
+     *  The one knob a headless flow could not reach before 0.29.0, and for MCP
+     *  skills it is not optional: `mcpRecord` hard-codes `platformSafe: false`,
+     *  so every `run_skill` raises a confirm — and a platform instance has no
+     *  human who could ever approve one (a synthetic uid has no Firebase user).
+     *  Without this the skill installs, rate-limits and attaches cleanly and then
+     *  answers nothing. Grant the READ tools (a storefront's `search_catalog` /
+     *  `get_product`) and leave anything that mutates a cart or places an order
+     *  gated.
+     *
+     *  A full REPLACE, not a merge — pass the complete list every call. Names the
+     *  skill does not declare are dropped and echoed back in `dropped`, so a typo
+     *  is visible rather than silently ungranted. */
+    setSkillAutoRunTools(slug: string, toolNames: string[]): Promise<SkillKnobResult<{
+        autoRunTools: string[];
+        dropped: string[];
+    }>>;
     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.28.0';
+export const ADMIN_SDK_VERSION = '0.30.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;
@@ -72,6 +72,7 @@ export function requestDeadlineMs(method, path) {
 export const ADMIN_ERROR_CODES = [
     'story_contract_v2_write_disabled',
     'story_contract_v3_write_disabled',
+    'story_contract_v4_write_disabled',
     'episode_history_incomplete',
     'episode_ended',
     'idempotency_key_reused',
@@ -194,8 +195,9 @@ export function createAdminClient(opts) {
         throw new AdminApiError('no fetch available — pass opts.fetch on Node <18', 0);
     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.
+        // the deadline is sized to the ROUTE, so the handlers that declare
+        // `maxDuration: 300` (LONG_WORK_REQUESTS) are not cut at 30s while they
+        // are still working.
         // `??` (not `||`) is deliberate: 0 is a SET value meaning "no deadline",
         // and it must not fall through to the route default.
         const timeoutMs = opts.timeoutMs ?? requestDeadlineMs(method, path);
@@ -266,6 +268,7 @@ export function createAdminClient(opts) {
         listSkills: () => request('GET', '/skills'),
         installSkill: (input) => request('POST', '/skills', input),
         updateSkill: (slug, patch) => request('PATCH', `/skills/${encodeURIComponent(slug)}`, patch),
+        setSkillAutoRunTools: (slug, toolNames) => request('PATCH', `/skills/${encodeURIComponent(slug)}`, { autoRunTools: toolNames }),
         setSkillRate: (slug, ratePerMin) => request('PATCH', `/skills/${encodeURIComponent(slug)}`, { ratePerMin }),
         setSkillDailyCap: (slug, maxCallsPerDay) => request('PATCH', `/skills/${encodeURIComponent(slug)}`, { maxCallsPerDay }),
         compileSkill: (slug) => request('POST', `/skills/${encodeURIComponent(slug)}/compile`, {}),

package/package.json

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