@pouchy_ai/admin-sdk 0.25.1 → 0.26.1

package/CHANGELOG.md

@@ -2,6 +2,40 @@
 
 All notable changes to `@pouchy_ai/admin-sdk` are documented here.
 
+## 0.26.1 — 2026-08-09
+
+- **Docs-only.** No type, method or signature moves. `extractJson`'s failure
+  table now says which arm each 400 can come from: `schema_invalid` is
+  reachable only on a **strict** call, because `strict: false` sends
+  `{type:'json_object'}` and the schema never reaches the wire. A provider
+  rejection of a schema-less call — JSON mode refusing a custom `system`
+  prompt that never contains the word "json" is the common one — is
+  `request_invalid`, the code that already meant "the provider rejected the
+  request itself". Server-side change; both codes are 400 and neither is
+  retryable, so no client logic that branches on retry direction is affected.
+- `schemaName: ''` is accepted again as "unset" (it falls back to the
+  documented `extraction` default). The 0.24.x-era identifier-grammar check
+  400'd it with a charset message that named characters the empty string does
+  not have.
+
+## 0.26.0 — 2026-08-09
+
+- **New methods `importAgentPlugin` / `exportAgentPlugin`** (additive; nothing
+  renamed or removed): interop with the cross-vendor **Agent Plugins 1.0.0**
+  packaging standard (agent-plugins.org). Import takes the plugin as an
+  explicit file map — `skills/<dir>/SKILL.md` installs as a docs-only skill,
+  `mcp.json` streamable-http servers connect through the MCP path (stdio/sse
+  are skipped per component; the platform is serverless), and a
+  Pouchy-exported plugin's `extensions["ai.pouchy"]` manifest round-trips
+  losslessly. Every component runs the same install safety judge as the
+  native install paths, and declared mcp `headers` are never forwarded
+  (store credentials with `putCredentials` instead — the spec itself calls
+  headers visible package data). Export composes a conformant package for any
+  installed skill: SKILL.md prose or an mcp.json reference as the portable
+  face, the full Pouchy manifest under `extensions["ai.pouchy"]` as the
+  lossless face. Per-component failures are non-fatal (201 with
+  `installed`/`skipped`/`errors`; 422 only when nothing was installable).
+
 ## 0.25.1 — 2026-08-09
 
 - **Docs-only: the README's 409 vocabulary table gains the `one_shot_spent`

package/README.md

@@ -147,9 +147,12 @@ const { data } = await admin.extractJson<{ items: { kind: string; summary: strin
 ```
 
 Failures are typed rather than prose, so the recoveries are distinguishable:
-`schema_invalid` (400 — fix the schema; retrying verbatim cannot help),
-`request_invalid` (400 — the provider rejected the request itself: an unknown
-`model`, or a parameter outside the provider's validation; fix the request),
+`schema_invalid` (400 — fix the schema; retrying verbatim cannot help; only
+reachable on a **strict** call, since `strict: false` never puts a schema on the
+wire), `request_invalid` (400 — the provider rejected the request itself: an
+unknown `model`, a parameter outside the provider's validation, or any rejection
+of a schema-less `strict: false` call — for example JSON mode refusing a custom
+`system` prompt that never says "json"; fix the request),
 `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
@@ -192,6 +195,51 @@ 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.
 
+### Agent Plugins (agent-plugins.org) — import & export
+
+Pouchy consumes and emits the cross-vendor **Agent Plugins 1.0.0** packaging
+standard. Import takes the plugin as an explicit file map (read the directory
+yourself — no archive upload): `skills/<dir>/SKILL.md` installs as a docs-only
+skill, `mcp.json` `streamable-http` servers connect through the MCP path, and
+a Pouchy-exported plugin round-trips losslessly via its
+`extensions["ai.pouchy"]` manifest. `stdio`/`sse` transports and bundled
+script files are skipped per component with a reason (the platform is
+serverless — the spec requires clients to support only one transport).
+Declared mcp `headers` are **never forwarded** — the spec itself calls them
+visible package data; store real credentials with `putCredentials` after
+install. Every imported component runs the same install safety judge as the
+native install paths.
+
+```ts
+import { createAdminClient } from '@pouchy_ai/admin-sdk';
+
+const admin = createAdminClient({ adminKey: process.env.POUCHY_ADMIN_KEY! });
+
+// The plugin travels as an explicit { path, content } file map — read the
+// plugin directory with your runtime's fs and preserve relative POSIX paths.
+const result = await admin.importAgentPlugin({
+  files: [
+    {
+      path: 'plugin.json',
+      content: JSON.stringify({
+        $schema: 'https://agent-plugins.org/schemas/1.0.0/plugin.schema.json',
+        name: 'hello-plugin'
+      })
+    },
+    {
+      path: 'skills/greet/SKILL.md',
+      content: '---\nname: greet\ndescription: Greet the user and offer help.\n---\n\nGreet the user warmly.\n'
+    }
+  ]
+});
+console.log(result.installed); // [{ slug: 'greet', kind: 'http', component: 'skills/greet' }]
+for (const s of result.skipped) console.warn(`${s.component}: ${s.reason}`);
+
+// Export any installed skill as a conformant plugin (write it out / zip it).
+const pkg = await admin.exportAgentPlugin('greet');
+for (const f of pkg.files) console.log(f.path, f.content.length);
+```
+
 ## Options
 
 ```ts
@@ -332,7 +380,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` |
+| Skills | `listSkills` · `installSkill` · `updateSkill` · `setSkillRate` · `setSkillDailyCap` · `grantSkill` (free-HTTP) · `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` |

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export declare const ADMIN_SDK_VERSION = "0.25.1";
+export declare const ADMIN_SDK_VERSION = "0.26.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
@@ -678,9 +678,12 @@ export interface AdminClient {
      *  validation.
      *
      *  Failures are typed rather than prose, which is the point:
-     *  `schema_invalid` (400 — fix the schema, retrying verbatim cannot help),
-     *  `request_invalid` (400 — the provider rejected the request itself:
-     *  an unknown `model`, or a parameter outside the provider's validation;
+     *  `schema_invalid` (400 — fix the schema, retrying verbatim cannot help;
+     *  only reachable on a STRICT call, because `strict: false` never puts a
+     *  schema on the wire), `request_invalid` (400 — the provider rejected the
+     *  request itself: an unknown `model`, a parameter outside the provider's
+     *  validation, or any rejection of a schema-less `strict: false` call, such
+     *  as JSON mode refusing a `system` prompt that never says "json";
      *  fix the request, 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`,
@@ -828,6 +831,56 @@ export interface AdminClient {
     uninstallSkill(slug: string): Promise<{
         deleted: boolean;
     }>;
+    /** Import an Agent Plugins 1.0.0 package (agent-plugins.org — the
+     *  cross-vendor plugin packaging standard) as custom skills. Pass the
+     *  plugin as an explicit file map (read the directory yourself; no archive
+     *  upload). `skills/<dir>/SKILL.md` installs as a docs-only skill,
+     *  `mcp.json` streamable-http servers connect through the MCP path
+     *  (stdio/sse are skipped per component — the platform is serverless), and
+     *  a Pouchy-exported plugin's `extensions["ai.pouchy"]` manifest
+     *  round-trips losslessly. Every component runs the same install safety
+     *  judge as the native paths; declared mcp `headers` are never forwarded —
+     *  store credentials with `putCredentials` after install. Resolves 201
+     *  when at least one component installed (`skipped`/`errors` carry the
+     *  rest); a package with nothing installable rejects with a 422 naming
+     *  the first per-component reason. */
+    importAgentPlugin(input: {
+        files: Array<{
+            path: string;
+            content: string;
+        }>;
+    }): Promise<{
+        plugin: {
+            name: string;
+            version?: string;
+        };
+        installed: Array<{
+            slug: string;
+            kind: string;
+            component: string;
+        }>;
+        skipped: Array<{
+            component: string;
+            reason: string;
+        }>;
+        errors: Array<{
+            component: string;
+            error: string;
+        }>;
+    }>;
+    /** Export one installed skill as a conformant Agent Plugins 1.0.0 package
+     *  (file map — write it to a directory or zip it yourself). Portable face:
+     *  SKILL.md instruction prose or an mcp.json streamable-http reference;
+     *  lossless face: the full Pouchy manifest under plugin.json
+     *  `extensions["ai.pouchy"]` (a Pouchy re-import round-trips exactly —
+     *  other conformant clients ignore the namespace). Credential values never
+     *  leave the vault. */
+    exportAgentPlugin(slug: string): Promise<{
+        files: Array<{
+            path: string;
+            content: string;
+        }>;
+    }>;
     /** Secret-free vault metadata: `enabled` says whether the deployment has a
      *  vault at all; `skills` lists which skill slugs hold credentials (values
      *  are never returned by any endpoint). */

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.25.1';
+export const ADMIN_SDK_VERSION = '0.26.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;
@@ -263,6 +263,8 @@ export function createAdminClient(opts) {
             grantedDomains: grant.grantedDomains ?? []
         }),
         uninstallSkill: (slug) => request('DELETE', `/skills/${encodeURIComponent(slug)}`),
+        importAgentPlugin: (input) => request('POST', '/skills/agent-plugin', input),
+        exportAgentPlugin: (slug) => request('GET', `/skills/${encodeURIComponent(slug)}/agent-plugin`),
         listCredentials: () => request('GET', '/credentials'),
         putCredentials: (input) => request('POST', '/credentials', input),
         deleteCredentials: (skill) => request('DELETE', `/credentials/${encodeURIComponent(skill)}`),

package/package.json

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