@workerkit/core 0.3.5 → 0.3.7

package/dist/descriptors/onboarding.d.ts

@@ -0,0 +1,3 @@
+import { type ToolDescriptor } from "./types.js";
+export declare const onboardingDescriptors: readonly ToolDescriptor[];
+//# sourceMappingURL=onboarding.d.ts.map

package/dist/descriptors/onboarding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"onboarding.d.ts","sourceRoot":"","sources":["../../src/descriptors/onboarding.ts"],"names":[],"mappings":"AACA,OAAO,EAAa,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC;AAE5D,eAAO,MAAM,qBAAqB,EAAE,SAAS,cAAc,EAmD1D,CAAC"}

package/dist/descriptors/onboarding.js

@@ -0,0 +1,55 @@
+import { z } from "../zod.js";
+import { READ_ONLY } from "./types.js";
+export const onboardingDescriptors = [
+    {
+        name: "onboarding_get",
+        title: "Check onboarding requirements",
+        auth: "manager",
+        method: "get",
+        path: "/api/manage/onboarding",
+        schema: {
+            provider: z.string().max(40).optional().describe("Optional model provider to check."),
+        },
+        annotations: READ_ONLY,
+        description: "Read this credential’s scopes/expiry, account model-funding requirements and human-approved spendPolicy with remaining reserved allowance. No additional scope required. Agents cannot raise the account ceiling; it applies to scheduled and manual runs. If humanActionRequired is true, show the returned setup URL. The user enters provider keys on WorkerKit, never in chat. BYOK can still require wallet credits for platform fees and metered apps. After funding, check worker readiness, deploy and run; runtime guards remain authoritative.",
+    },
+    {
+        name: "wallet_get",
+        title: "Read wallet",
+        auth: "manager",
+        method: "get",
+        path: "/api/manage/wallet",
+        schema: {},
+        annotations: READ_ONLY,
+        description: "Read spendable wallet balance and checkout fee/amount limits. Requires readWallet. A wallet balance is not evidence that a particular checkout was credited; use wallet_checkout_get for that.",
+    },
+    {
+        name: "wallet_checkout_create",
+        title: "Request wallet funding",
+        auth: "manager",
+        method: "post",
+        path: "/api/manage/wallet/checkouts",
+        schema: {
+            amountUsd: z.number().min(0.01).max(999999.99).multipleOf(0.01)
+                .describe("Credit amount in whole cents, before the returned platform fee. Read wallet_get for current purchase limits."),
+            idempotencyKey: z.string().min(1).max(200).regex(/^[\x21-\x7E]+$/)
+                .describe("Unique printable-ASCII purchase request ID. Reuse only for retries of the same amount."),
+        },
+        bodyBuilder: (params) => ({ amountUsd: params.amountUsd }),
+        headerBuilder: (params) => ({ "Idempotency-Key": String(params.idempotencyKey) }),
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+        description: "Create a Stripe Checkout link for a specific wallet credit purchase. Requires requestWalletTopUp. Show the credit, fee and total and ask the user to open checkout and confirm payment. Never ask for card details or charge a saved card. Poll wallet_checkout_get after payment; only credited confirms funds reached the ledger. Reuse idempotencyKey for retries, never a different amount.",
+    },
+    {
+        name: "wallet_checkout_get",
+        title: "Check wallet payment",
+        auth: "manager",
+        method: "get",
+        path: (params) => `/api/manage/wallet/checkouts/${encodeURIComponent(String(params.sessionId))}`,
+        paramFilter: () => ({}),
+        schema: { sessionId: z.string().min(1).max(255) },
+        annotations: READ_ONLY,
+        description: "Check pending, paid_pending_credit, credited or expired checkout status. Requires readWallet, or requestWalletTopUp for a checkout created by this credential. Only credited means the wallet ledger has committed. Wait at least five seconds between checks; stop on credited or expired and use bounded waits for delayed payment.",
+    },
+];
+//# sourceMappingURL=onboarding.js.map

package/dist/descriptors/onboarding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"onboarding.js","sourceRoot":"","sources":["../../src/descriptors/onboarding.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,WAAW,CAAC;AAC9B,OAAO,EAAE,SAAS,EAAuB,MAAM,YAAY,CAAC;AAE5D,MAAM,CAAC,MAAM,qBAAqB,GAA8B;IAC9D;QACE,IAAI,EAAE,gBAAgB;QACtB,KAAK,EAAE,+BAA+B;QACtC,IAAI,EAAE,SAAS;QACf,MAAM,EAAE,KAAK;QACb,IAAI,EAAE,wBAAwB;QAC9B,MAAM,EAAE;YACN,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,mCAAmC,CAAC;SACtF;QACD,WAAW,EAAE,SAAS;QACtB,WAAW,EAAE,0hBAA0hB;KACxiB;IACD;QACE,IAAI,EAAE,YAAY;QAClB,KAAK,EAAE,aAAa;QACpB,IAAI,EAAE,SAAS;QACf,MAAM,EAAE,KAAK;QACb,IAAI,EAAE,oBAAoB;QAC1B,MAAM,EAAE,EAAE;QACV,WAAW,EAAE,SAAS;QACtB,WAAW,EAAE,gMAAgM;KAC9M;IACD;QACE,IAAI,EAAE,wBAAwB;QAC9B,KAAK,EAAE,wBAAwB;QAC/B,IAAI,EAAE,SAAS;QACf,MAAM,EAAE,MAAM;QACd,IAAI,EAAE,8BAA8B;QACpC,MAAM,EAAE;YACN,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC;iBAC5D,QAAQ,CAAC,8GAA8G,CAAC;YAC3H,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,gBAAgB,CAAC;iBAC/D,QAAQ,CAAC,wFAAwF,CAAC;SACtG;QACD,WAAW,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,CAAC,SAAS,EAAE,CAAC;QAC1D,aAAa,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,EAAE,iBAAiB,EAAE,MAAM,CAAC,MAAM,CAAC,cAAc,CAAC,EAAE,CAAC;QACjF,WAAW,EAAE,EAAE,YAAY,EAAE,KAAK,EAAE,eAAe,EAAE,KAAK,EAAE,cAAc,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE;QACvG,WAAW,EAAE,iYAAiY;KAC/Y;IACD;QACE,IAAI,EAAE,qBAAqB;QAC3B,KAAK,EAAE,sBAAsB;QAC7B,IAAI,EAAE,SAAS;QACf,MAAM,EAAE,KAAK;QACb,IAAI,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,gCAAgC,kBAAkB,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,EAAE;QAChG,WAAW,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC;QACvB,MAAM,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE;QACjD,WAAW,EAAE,SAAS;QACtB,WAAW,EAAE,uUAAuU;KACrV;CACF,CAAC","sourcesContent":["import { z } from \"../zod.js\";\nimport { READ_ONLY, type ToolDescriptor } from \"./types.js\";\n\nexport const onboardingDescriptors: readonly ToolDescriptor[] = [\n  {\n    name: \"onboarding_get\",\n    title: \"Check onboarding requirements\",\n    auth: \"manager\",\n    method: \"get\",\n    path: \"/api/manage/onboarding\",\n    schema: {\n      provider: z.string().max(40).optional().describe(\"Optional model provider to check.\"),\n    },\n    annotations: READ_ONLY,\n    description: \"Read this credential’s scopes/expiry, account model-funding requirements and human-approved spendPolicy with remaining reserved allowance. No additional scope required. Agents cannot raise the account ceiling; it applies to scheduled and manual runs. If humanActionRequired is true, show the returned setup URL. The user enters provider keys on WorkerKit, never in chat. BYOK can still require wallet credits for platform fees and metered apps. After funding, check worker readiness, deploy and run; runtime guards remain authoritative.\",\n  },\n  {\n    name: \"wallet_get\",\n    title: \"Read wallet\",\n    auth: \"manager\",\n    method: \"get\",\n    path: \"/api/manage/wallet\",\n    schema: {},\n    annotations: READ_ONLY,\n    description: \"Read spendable wallet balance and checkout fee/amount limits. Requires readWallet. A wallet balance is not evidence that a particular checkout was credited; use wallet_checkout_get for that.\",\n  },\n  {\n    name: \"wallet_checkout_create\",\n    title: \"Request wallet funding\",\n    auth: \"manager\",\n    method: \"post\",\n    path: \"/api/manage/wallet/checkouts\",\n    schema: {\n      amountUsd: z.number().min(0.01).max(999999.99).multipleOf(0.01)\n        .describe(\"Credit amount in whole cents, before the returned platform fee. Read wallet_get for current purchase limits.\"),\n      idempotencyKey: z.string().min(1).max(200).regex(/^[\\x21-\\x7E]+$/)\n        .describe(\"Unique printable-ASCII purchase request ID. Reuse only for retries of the same amount.\"),\n    },\n    bodyBuilder: (params) => ({ amountUsd: params.amountUsd }),\n    headerBuilder: (params) => ({ \"Idempotency-Key\": String(params.idempotencyKey) }),\n    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },\n    description: \"Create a Stripe Checkout link for a specific wallet credit purchase. Requires requestWalletTopUp. Show the credit, fee and total and ask the user to open checkout and confirm payment. Never ask for card details or charge a saved card. Poll wallet_checkout_get after payment; only credited confirms funds reached the ledger. Reuse idempotencyKey for retries, never a different amount.\",\n  },\n  {\n    name: \"wallet_checkout_get\",\n    title: \"Check wallet payment\",\n    auth: \"manager\",\n    method: \"get\",\n    path: (params) => `/api/manage/wallet/checkouts/${encodeURIComponent(String(params.sessionId))}`,\n    paramFilter: () => ({}),\n    schema: { sessionId: z.string().min(1).max(255) },\n    annotations: READ_ONLY,\n    description: \"Check pending, paid_pending_credit, credited or expired checkout status. Requires readWallet, or requestWalletTopUp for a checkout created by this credential. Only credited means the wallet ledger has committed. Wait at least five seconds between checks; stop on credited or expired and use bounded waits for delayed payment.\",\n  },\n];\n"]}

package/dist/descriptors/types.d.ts

@@ -33,6 +33,10 @@ export interface ToolDescriptor {
     method: HttpMethod;
     /** Single source for the MCP inputSchema AND future CLI flags. */
     schema: z.ZodRawShape;
+    /** Reject unknown top-level inputs instead of silently dropping unsupported controls. */
+    strictInput?: boolean;
+    /** Structured success result. MCP adapters retain a serialized text fallback. */
+    outputSchema?: z.ZodRawShape;
     /** Upstream path, or a builder over the validated params. */
     path: string | ((params: Record<string, unknown>) => string);
     /**
@@ -45,6 +49,8 @@ export interface ToolDescriptor {
      * params object is the body. DELETE requests never send a body either way.
      */
     bodyBuilder?: (params: Record<string, unknown>) => unknown;
+    /** Headers derived from typed inputs, e.g. a checkout idempotency key. */
+    headerBuilder?: (params: Record<string, unknown>) => Record<string, string>;
     /** Mutations: message served on an empty (204) success body. */
     successMessage?: string;
     annotations: ToolAnnotations;

package/dist/descriptors/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/descriptors/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,WAAW,CAAC;AAE9B,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,KAAK,GAAG,QAAQ,CAAC;AAErE;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAMD,eAAO,MAAM,SAAS,EAAE,eAAsF,CAAC;AAC/G,eAAO,MAAM,MAAM,EAAE,eAAuF,CAAC;AAC7G,eAAO,MAAM,MAAM,EAAE,eAA6G,CAAC;AACnI,eAAO,MAAM,MAAM,EAAE,eAAsF,CAAC;AAI5G,eAAO,MAAM,OAAO,EAAE,eAAsF,CAAC;AAE7G;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,kFAAkF;IAClF,IAAI,EAAE,SAAS,GAAG,WAAW,CAAC;IAC9B,MAAM,EAAE,UAAU,CAAC;IACnB,kEAAkE;IAClE,MAAM,EAAE,CAAC,CAAC,WAAW,CAAC;IACtB,6DAA6D;IAC7D,IAAI,EAAE,MAAM,GAAG,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,CAAC,CAAC;IAC7D;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC3E;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC;IAC3D,gEAAgE;IAChE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,eAAe,CAAC;IAC7B;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC;IACtE;;;;;OAKG;IACH,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,GAAG,SAAS,CAAC;CACjF"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/descriptors/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,WAAW,CAAC;AAE9B,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,KAAK,GAAG,QAAQ,CAAC;AAErE;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAMD,eAAO,MAAM,SAAS,EAAE,eAAsF,CAAC;AAC/G,eAAO,MAAM,MAAM,EAAE,eAAuF,CAAC;AAC7G,eAAO,MAAM,MAAM,EAAE,eAA6G,CAAC;AACnI,eAAO,MAAM,MAAM,EAAE,eAAsF,CAAC;AAI5G,eAAO,MAAM,OAAO,EAAE,eAAsF,CAAC;AAE7G;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,kFAAkF;IAClF,IAAI,EAAE,SAAS,GAAG,WAAW,CAAC;IAC9B,MAAM,EAAE,UAAU,CAAC;IACnB,kEAAkE;IAClE,MAAM,EAAE,CAAC,CAAC,WAAW,CAAC;IACtB,yFAAyF;IACzF,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,iFAAiF;IACjF,YAAY,CAAC,EAAE,CAAC,CAAC,WAAW,CAAC;IAC7B,6DAA6D;IAC7D,IAAI,EAAE,MAAM,GAAG,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,CAAC,CAAC;IAC7D;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC3E;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC;IAC3D,0EAA0E;IAC1E,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5E,gEAAgE;IAChE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,eAAe,CAAC;IAC7B;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC;IACtE;;;;;OAKG;IACH,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,GAAG,SAAS,CAAC;CACjF"}

package/dist/descriptors/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/descriptors/types.ts"],"names":[],"mappings":"AAiBA,gFAAgF;AAChF,mFAAmF;AACnF,oDAAoD;AAEpD,MAAM,CAAC,MAAM,SAAS,GAAoB,EAAE,YAAY,EAAE,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,CAAC;AAC/G,MAAM,CAAC,MAAM,MAAM,GAAoB,EAAE,YAAY,EAAE,KAAK,EAAE,eAAe,EAAE,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,CAAC;AAC7G,MAAM,CAAC,MAAM,MAAM,GAAoB,EAAE,YAAY,EAAE,KAAK,EAAE,eAAe,EAAE,KAAK,EAAE,cAAc,EAAE,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,CAAC;AACnI,MAAM,CAAC,MAAM,MAAM,GAAoB,EAAE,YAAY,EAAE,KAAK,EAAE,eAAe,EAAE,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,CAAC;AAC5G,kFAAkF;AAClF,kFAAkF;AAClF,0BAA0B;AAC1B,MAAM,CAAC,MAAM,OAAO,GAAoB,EAAE,YAAY,EAAE,KAAK,EAAE,eAAe,EAAE,KAAK,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC","sourcesContent":["import { z } from \"../zod.js\";\n\nexport type HttpMethod = \"get\" | \"post\" | \"patch\" | \"put\" | \"delete\";\n\n/**\n * MCP-style behavior hints. Kept structurally identical to the MCP spec's\n * ToolAnnotations (minus display title, which is presentation) so an MCP\n * server can spread these straight into a tool registration — but this module\n * has no MCP dependency; a CLI can read them as plain capability flags.\n */\nexport interface ToolAnnotations {\n  readOnlyHint?: boolean;\n  destructiveHint?: boolean;\n  idempotentHint?: boolean;\n  openWorldHint?: boolean;\n}\n\n// ─── Annotation presets ──────────────────────────────────────────────────────\n// Every tool carries one. Clients read them to decide what may run unattended, and\n// MCP directory listings expect them to be present.\n\nexport const READ_ONLY: ToolAnnotations = { readOnlyHint: true, destructiveHint: false, openWorldHint: false };\nexport const CREATE: ToolAnnotations = { readOnlyHint: false, destructiveHint: false, openWorldHint: false };\nexport const UPDATE: ToolAnnotations = { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false };\nexport const DELETE: ToolAnnotations = { readOnlyHint: false, destructiveHint: true, openWorldHint: false };\n// Triggering a worker run causes real-world side effects through the worker's own\n// tools (it may send email, edit CRM rows, …) — openWorld, but not destructive to\n// WorkerKit state itself.\nexport const TRIGGER: ToolAnnotations = { readOnlyHint: false, destructiveHint: false, openWorldHint: true };\n\n/**\n * One tool, described declaratively: what it is called, what it teaches the\n * agent, and exactly how its parameters map onto one upstream HTTP request.\n * This is the single source of truth consumed by the MCP server (inputSchema,\n * annotations, wire call via executeTool) and by any future surface (CLI\n * flags, docs) — wire construction exists exactly once, in executeTool.\n */\nexport interface ToolDescriptor {\n  name: string;\n  title: string;\n  description: string;\n  /** \"manager\" tools require a bearer; \"anonymous\" tools must never forward one. */\n  auth: \"manager\" | \"anonymous\";\n  method: HttpMethod;\n  /** Single source for the MCP inputSchema AND future CLI flags. */\n  schema: z.ZodRawShape;\n  /** Upstream path, or a builder over the validated params. */\n  path: string | ((params: Record<string, unknown>) => string);\n  /**\n   * GET only: maps tool params to query params (typically stripping the ones\n   * already consumed by the path builder). Omitted = all params pass through.\n   */\n  paramFilter?: (params: Record<string, unknown>) => Record<string, unknown>;\n  /**\n   * Mutations only: builds the JSON body from the params. Omitted = the raw\n   * params object is the body. DELETE requests never send a body either way.\n   */\n  bodyBuilder?: (params: Record<string, unknown>) => unknown;\n  /** Mutations: message served on an empty (204) success body. */\n  successMessage?: string;\n  annotations: ToolAnnotations;\n  /**\n   * Pure success-data transform (e.g. computed pageUrl injection). Returning\n   * `undefined` means \"unexpected shape — serve the upstream body verbatim\";\n   * the consumer then falls back to its plain formatting path.\n   */\n  mapData?: (data: unknown, params: Record<string, unknown>) => unknown;\n  /**\n   * Agent-guidance footer for a successful result (empty-result hints,\n   * next-page pointers, omitted-bodies notes). Receives the mapData output.\n   * How the footer is rendered (e.g. bracketed, appended) is the consumer's\n   * presentation decision.\n   */\n  footer?: (data: unknown, params: Record<string, unknown>) => string | undefined;\n}\n"]}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/descriptors/types.ts"],"names":[],"mappings":"AAiBA,gFAAgF;AAChF,mFAAmF;AACnF,oDAAoD;AAEpD,MAAM,CAAC,MAAM,SAAS,GAAoB,EAAE,YAAY,EAAE,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,CAAC;AAC/G,MAAM,CAAC,MAAM,MAAM,GAAoB,EAAE,YAAY,EAAE,KAAK,EAAE,eAAe,EAAE,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,CAAC;AAC7G,MAAM,CAAC,MAAM,MAAM,GAAoB,EAAE,YAAY,EAAE,KAAK,EAAE,eAAe,EAAE,KAAK,EAAE,cAAc,EAAE,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,CAAC;AACnI,MAAM,CAAC,MAAM,MAAM,GAAoB,EAAE,YAAY,EAAE,KAAK,EAAE,eAAe,EAAE,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,CAAC;AAC5G,kFAAkF;AAClF,kFAAkF;AAClF,0BAA0B;AAC1B,MAAM,CAAC,MAAM,OAAO,GAAoB,EAAE,YAAY,EAAE,KAAK,EAAE,eAAe,EAAE,KAAK,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC","sourcesContent":["import { z } from \"../zod.js\";\n\nexport type HttpMethod = \"get\" | \"post\" | \"patch\" | \"put\" | \"delete\";\n\n/**\n * MCP-style behavior hints. Kept structurally identical to the MCP spec's\n * ToolAnnotations (minus display title, which is presentation) so an MCP\n * server can spread these straight into a tool registration — but this module\n * has no MCP dependency; a CLI can read them as plain capability flags.\n */\nexport interface ToolAnnotations {\n  readOnlyHint?: boolean;\n  destructiveHint?: boolean;\n  idempotentHint?: boolean;\n  openWorldHint?: boolean;\n}\n\n// ─── Annotation presets ──────────────────────────────────────────────────────\n// Every tool carries one. Clients read them to decide what may run unattended, and\n// MCP directory listings expect them to be present.\n\nexport const READ_ONLY: ToolAnnotations = { readOnlyHint: true, destructiveHint: false, openWorldHint: false };\nexport const CREATE: ToolAnnotations = { readOnlyHint: false, destructiveHint: false, openWorldHint: false };\nexport const UPDATE: ToolAnnotations = { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false };\nexport const DELETE: ToolAnnotations = { readOnlyHint: false, destructiveHint: true, openWorldHint: false };\n// Triggering a worker run causes real-world side effects through the worker's own\n// tools (it may send email, edit CRM rows, …) — openWorld, but not destructive to\n// WorkerKit state itself.\nexport const TRIGGER: ToolAnnotations = { readOnlyHint: false, destructiveHint: false, openWorldHint: true };\n\n/**\n * One tool, described declaratively: what it is called, what it teaches the\n * agent, and exactly how its parameters map onto one upstream HTTP request.\n * This is the single source of truth consumed by the MCP server (inputSchema,\n * annotations, wire call via executeTool) and by any future surface (CLI\n * flags, docs) — wire construction exists exactly once, in executeTool.\n */\nexport interface ToolDescriptor {\n  name: string;\n  title: string;\n  description: string;\n  /** \"manager\" tools require a bearer; \"anonymous\" tools must never forward one. */\n  auth: \"manager\" | \"anonymous\";\n  method: HttpMethod;\n  /** Single source for the MCP inputSchema AND future CLI flags. */\n  schema: z.ZodRawShape;\n  /** Reject unknown top-level inputs instead of silently dropping unsupported controls. */\n  strictInput?: boolean;\n  /** Structured success result. MCP adapters retain a serialized text fallback. */\n  outputSchema?: z.ZodRawShape;\n  /** Upstream path, or a builder over the validated params. */\n  path: string | ((params: Record<string, unknown>) => string);\n  /**\n   * GET only: maps tool params to query params (typically stripping the ones\n   * already consumed by the path builder). Omitted = all params pass through.\n   */\n  paramFilter?: (params: Record<string, unknown>) => Record<string, unknown>;\n  /**\n   * Mutations only: builds the JSON body from the params. Omitted = the raw\n   * params object is the body. DELETE requests never send a body either way.\n   */\n  bodyBuilder?: (params: Record<string, unknown>) => unknown;\n  /** Headers derived from typed inputs, e.g. a checkout idempotency key. */\n  headerBuilder?: (params: Record<string, unknown>) => Record<string, string>;\n  /** Mutations: message served on an empty (204) success body. */\n  successMessage?: string;\n  annotations: ToolAnnotations;\n  /**\n   * Pure success-data transform (e.g. computed pageUrl injection). Returning\n   * `undefined` means \"unexpected shape — serve the upstream body verbatim\";\n   * the consumer then falls back to its plain formatting path.\n   */\n  mapData?: (data: unknown, params: Record<string, unknown>) => unknown;\n  /**\n   * Agent-guidance footer for a successful result (empty-result hints,\n   * next-page pointers, omitted-bodies notes). Receives the mapData output.\n   * How the footer is rendered (e.g. bracketed, appended) is the consumer's\n   * presentation decision.\n   */\n  footer?: (data: unknown, params: Record<string, unknown>) => string | undefined;\n}\n"]}

package/dist/execute.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"execute.d.ts","sourceRoot":"","sources":["../src/execute.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAE7D,MAAM,WAAW,eAAe;IAC9B,iEAAiE;IACjE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;;GAKG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,cAAc,EACtB,UAAU,EAAE,cAAc,EAC1B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,IAAI,GAAE,eAAoB,GACzB,OAAO,CAAC,SAAS,CAAC,CAoBpB"}
+{"version":3,"file":"execute.d.ts","sourceRoot":"","sources":["../src/execute.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAE7D,MAAM,WAAW,eAAe;IAC9B,iEAAiE;IACjE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;;GAKG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,cAAc,EACtB,UAAU,EAAE,cAAc,EAC1B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,IAAI,GAAE,eAAoB,GACzB,OAAO,CAAC,SAAS,CAAC,CAyBpB"}

package/dist/execute.js

@@ -6,18 +6,23 @@
  */
 export async function executeTool(client, descriptor, params, opts = {}) {
     const resolvedPath = typeof descriptor.path === "function" ? descriptor.path(params) : descriptor.path;
+    // Discovery stays anonymous even when a caller shares its authenticated client context.
+    const token = descriptor.auth === "manager" ? opts.token : undefined;
+    const extra = descriptor.headerBuilder ? { headers: descriptor.headerBuilder(params) } : {};
     if (descriptor.method === "get") {
         // Strip path params from query params
         const queryParams = descriptor.paramFilter ? descriptor.paramFilter(params) : { ...params };
         return client.get(resolvedPath, {
-            token: opts.token,
+            ...extra,
+            token,
             params: queryParams,
             signal: opts.signal,
         });
     }
     const body = descriptor.bodyBuilder ? descriptor.bodyBuilder(params) : params;
     return client[descriptor.method](resolvedPath, {
-        token: opts.token,
+        ...extra,
+        token,
         body: descriptor.method !== "delete" ? body : undefined,
         signal: opts.signal,
     });

package/dist/execute.js.map

@@ -1 +1 @@
-{"version":3,"file":"execute.js","sourceRoot":"","sources":["../src/execute.ts"],"names":[],"mappings":"AASA;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,MAAsB,EACtB,UAA0B,EAC1B,MAA+B,EAC/B,OAAwB,EAAE;IAE1B,MAAM,YAAY,GAChB,OAAO,UAAU,CAAC,IAAI,KAAK,UAAU,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC;IAEpF,IAAI,UAAU,CAAC,MAAM,KAAK,KAAK,EAAE,CAAC;QAChC,sCAAsC;QACtC,MAAM,WAAW,GAAG,UAAU,CAAC,WAAW,CAAC,CAAC,CAAC,UAAU,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,MAAM,EAAE,CAAC;QAC5F,OAAO,MAAM,CAAC,GAAG,CAAC,YAAY,EAAE;YAC9B,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,MAAM,EAAE,WAAW;YACnB,MAAM,EAAE,IAAI,CAAC,MAAM;SACpB,CAAC,CAAC;IACL,CAAC;IAED,MAAM,IAAI,GAAG,UAAU,CAAC,WAAW,CAAC,CAAC,CAAC,UAAU,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IAC9E,OAAO,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,YAAY,EAAE;QAC7C,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,IAAI,EAAE,UAAU,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS;QACvD,MAAM,EAAE,IAAI,CAAC,MAAM;KACpB,CAAC,CAAC;AACL,CAAC","sourcesContent":["import type { ApiResult, PortEdenClient } from \"./client.js\";\nimport type { ToolDescriptor } from \"./descriptors/types.js\";\n\nexport interface ExecuteToolOpts {\n  /** Bearer forwarded upstream. Omit for anonymous descriptors. */\n  token?: string;\n  signal?: AbortSignal;\n}\n\n/**\n * The ONE place a descriptor becomes a wire call: resolves the path, applies\n * paramFilter (GET query) or bodyBuilder (mutations), and dispatches to the\n * client. Every consumer (MCP server, CLI) goes through here, so the wire\n * contract each tool produces exists exactly once.\n */\nexport async function executeTool(\n  client: PortEdenClient,\n  descriptor: ToolDescriptor,\n  params: Record<string, unknown>,\n  opts: ExecuteToolOpts = {}\n): Promise<ApiResult> {\n  const resolvedPath =\n    typeof descriptor.path === \"function\" ? descriptor.path(params) : descriptor.path;\n\n  if (descriptor.method === \"get\") {\n    // Strip path params from query params\n    const queryParams = descriptor.paramFilter ? descriptor.paramFilter(params) : { ...params };\n    return client.get(resolvedPath, {\n      token: opts.token,\n      params: queryParams,\n      signal: opts.signal,\n    });\n  }\n\n  const body = descriptor.bodyBuilder ? descriptor.bodyBuilder(params) : params;\n  return client[descriptor.method](resolvedPath, {\n    token: opts.token,\n    body: descriptor.method !== \"delete\" ? body : undefined,\n    signal: opts.signal,\n  });\n}\n"]}
+{"version":3,"file":"execute.js","sourceRoot":"","sources":["../src/execute.ts"],"names":[],"mappings":"AASA;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,MAAsB,EACtB,UAA0B,EAC1B,MAA+B,EAC/B,OAAwB,EAAE;IAE1B,MAAM,YAAY,GAChB,OAAO,UAAU,CAAC,IAAI,KAAK,UAAU,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC;IACpF,wFAAwF;IACxF,MAAM,KAAK,GAAG,UAAU,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;IACrE,MAAM,KAAK,GAAG,UAAU,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,UAAU,CAAC,aAAa,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAE5F,IAAI,UAAU,CAAC,MAAM,KAAK,KAAK,EAAE,CAAC;QAChC,sCAAsC;QACtC,MAAM,WAAW,GAAG,UAAU,CAAC,WAAW,CAAC,CAAC,CAAC,UAAU,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,MAAM,EAAE,CAAC;QAC5F,OAAO,MAAM,CAAC,GAAG,CAAC,YAAY,EAAE;YAC9B,GAAG,KAAK;YACR,KAAK;YACL,MAAM,EAAE,WAAW;YACnB,MAAM,EAAE,IAAI,CAAC,MAAM;SACpB,CAAC,CAAC;IACL,CAAC;IAED,MAAM,IAAI,GAAG,UAAU,CAAC,WAAW,CAAC,CAAC,CAAC,UAAU,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IAC9E,OAAO,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,YAAY,EAAE;QAC7C,GAAG,KAAK;QACR,KAAK;QACL,IAAI,EAAE,UAAU,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS;QACvD,MAAM,EAAE,IAAI,CAAC,MAAM;KACpB,CAAC,CAAC;AACL,CAAC","sourcesContent":["import type { ApiResult, PortEdenClient } from \"./client.js\";\nimport type { ToolDescriptor } from \"./descriptors/types.js\";\n\nexport interface ExecuteToolOpts {\n  /** Bearer forwarded upstream. Omit for anonymous descriptors. */\n  token?: string;\n  signal?: AbortSignal;\n}\n\n/**\n * The ONE place a descriptor becomes a wire call: resolves the path, applies\n * paramFilter (GET query) or bodyBuilder (mutations), and dispatches to the\n * client. Every consumer (MCP server, CLI) goes through here, so the wire\n * contract each tool produces exists exactly once.\n */\nexport async function executeTool(\n  client: PortEdenClient,\n  descriptor: ToolDescriptor,\n  params: Record<string, unknown>,\n  opts: ExecuteToolOpts = {}\n): Promise<ApiResult> {\n  const resolvedPath =\n    typeof descriptor.path === \"function\" ? descriptor.path(params) : descriptor.path;\n  // Discovery stays anonymous even when a caller shares its authenticated client context.\n  const token = descriptor.auth === \"manager\" ? opts.token : undefined;\n  const extra = descriptor.headerBuilder ? { headers: descriptor.headerBuilder(params) } : {};\n\n  if (descriptor.method === \"get\") {\n    // Strip path params from query params\n    const queryParams = descriptor.paramFilter ? descriptor.paramFilter(params) : { ...params };\n    return client.get(resolvedPath, {\n      ...extra,\n      token,\n      params: queryParams,\n      signal: opts.signal,\n    });\n  }\n\n  const body = descriptor.bodyBuilder ? descriptor.bodyBuilder(params) : params;\n  return client[descriptor.method](resolvedPath, {\n    ...extra,\n    token,\n    body: descriptor.method !== \"delete\" ? body : undefined,\n    signal: opts.signal,\n  });\n}\n"]}

package/dist/index.js

@@ -1,5 +1,5 @@
 // @workerkit/core — the shareable WorkerKit surface: the HTTP client, the
-// tool-descriptor registry (79 manager + 9 anonymous directory tools), the
+// tool-descriptor registry (84 manager + 9 anonymous directory tools), the
 // single wire-execution path, and the pure formatting/redaction helpers.
 // Deliberately MCP-free: MCP (or CLI) presentation lives with the consumer.
 export { PortEdenClient, WorkerKitClient, ResponseTooLargeError, } from "./client.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,2EAA2E;AAC3E,yEAAyE;AACzE,4EAA4E;AAE5E,OAAO,EACL,cAAc,EACd,eAAe,EACf,qBAAqB,GACtB,MAAM,aAAa,CAAC;AASrB,cAAc,wBAAwB,CAAC;AAEvC,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAG3C,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEvE,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE5D,OAAO,EAAE,CAAC,EAAE,MAAM,UAAU,CAAC","sourcesContent":["// @workerkit/core — the shareable WorkerKit surface: the HTTP client, the\n// tool-descriptor registry (79 manager + 9 anonymous directory tools), the\n// single wire-execution path, and the pure formatting/redaction helpers.\n// Deliberately MCP-free: MCP (or CLI) presentation lives with the consumer.\n\nexport {\n  PortEdenClient,\n  WorkerKitClient,\n  ResponseTooLargeError,\n} from \"./client.js\";\nexport type {\n  ApiResult,\n  ClientLogger,\n  ClientOptions,\n  QuotaInfo,\n  RequestOpts,\n} from \"./client.js\";\n\nexport * from \"./descriptors/index.js\";\n\nexport { executeTool } from \"./execute.js\";\nexport type { ExecuteToolOpts } from \"./execute.js\";\n\nexport { isSuccess, quotaSuffix, retryAfterSuffix } from \"./errors.js\";\n\nexport { SECRET_PATTERNS, scrubSecrets } from \"./redact.js\";\n\nexport { z } from \"./zod.js\";\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,2EAA2E;AAC3E,yEAAyE;AACzE,4EAA4E;AAE5E,OAAO,EACL,cAAc,EACd,eAAe,EACf,qBAAqB,GACtB,MAAM,aAAa,CAAC;AASrB,cAAc,wBAAwB,CAAC;AAEvC,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAG3C,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEvE,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE5D,OAAO,EAAE,CAAC,EAAE,MAAM,UAAU,CAAC","sourcesContent":["// @workerkit/core — the shareable WorkerKit surface: the HTTP client, the\n// tool-descriptor registry (84 manager + 9 anonymous directory tools), the\n// single wire-execution path, and the pure formatting/redaction helpers.\n// Deliberately MCP-free: MCP (or CLI) presentation lives with the consumer.\n\nexport {\n  PortEdenClient,\n  WorkerKitClient,\n  ResponseTooLargeError,\n} from \"./client.js\";\nexport type {\n  ApiResult,\n  ClientLogger,\n  ClientOptions,\n  QuotaInfo,\n  RequestOpts,\n} from \"./client.js\";\n\nexport * from \"./descriptors/index.js\";\n\nexport { executeTool } from \"./execute.js\";\nexport type { ExecuteToolOpts } from \"./execute.js\";\n\nexport { isSuccess, quotaSuffix, retryAfterSuffix } from \"./errors.js\";\n\nexport { SECRET_PATTERNS, scrubSecrets } from \"./redact.js\";\n\nexport { z } from \"./zod.js\";\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workerkit/core",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "description": "API client and tool descriptors for WorkerKit: manage AI workers and browse the public kits directory",
   "type": "module",
   "license": "MIT",
@@ -58,6 +58,6 @@
   "devDependencies": {
     "@types/node": "22.20.1",
     "typescript": "5.9.3",
-    "vitest": "3.2.7"
+    "vitest": "4.1.11"
   }
 }