@workerkit/core 0.3.7 → 0.3.8

package/dist/descriptors/onboarding.d.ts

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

package/dist/descriptors/types.d.ts

@@ -31,6 +31,8 @@ export interface ToolDescriptor {
     /** "manager" tools require a bearer; "anonymous" tools must never forward one. */
     auth: "manager" | "anonymous";
     method: HttpMethod;
+    /** Explicit long waits may need a larger per-request transport timeout. */
+    requestTimeoutMs?: (params: Record<string, unknown>) => number | undefined;
     /** Single source for the MCP inputSchema AND future CLI flags. */
     schema: z.ZodRawShape;
     /** Reject unknown top-level inputs instead of silently dropping unsupported controls. */
@@ -68,4 +70,3 @@ export interface ToolDescriptor {
      */
     footer?: (data: unknown, params: Record<string, unknown>) => string | undefined;
 }
-//# sourceMappingURL=types.d.ts.map

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  /** 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"]}
+{"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  /** Explicit long waits may need a larger per-request transport timeout. */\n  requestTimeoutMs?: (params: Record<string, unknown>) => number | undefined;\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/errors.d.ts

@@ -3,4 +3,3 @@ import type { ApiResult, QuotaInfo } from "./client.js";
 export declare function isSuccess(result: ApiResult): boolean;
 export declare function quotaSuffix(quota: QuotaInfo): string;
 export declare function retryAfterSuffix(result: ApiResult): string;
-//# sourceMappingURL=errors.d.ts.map

package/dist/execute.d.ts

@@ -12,4 +12,3 @@ export interface ExecuteToolOpts {
  * contract each tool produces exists exactly once.
  */
 export declare function executeTool(client: PortEdenClient, descriptor: ToolDescriptor, params: Record<string, unknown>, opts?: ExecuteToolOpts): Promise<ApiResult>;
-//# sourceMappingURL=execute.d.ts.map

package/dist/execute.js

@@ -8,7 +8,11 @@ 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) } : {};
+    const timeoutMs = descriptor.requestTimeoutMs?.(params);
+    const extra = {
+        ...(descriptor.headerBuilder ? { headers: descriptor.headerBuilder(params) } : {}),
+        ...(timeoutMs === undefined ? {} : { timeoutMs }),
+    };
     if (descriptor.method === "get") {
         // Strip path params from query params
         const queryParams = descriptor.paramFilter ? descriptor.paramFilter(params) : { ...params };

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;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"]}
+{"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,SAAS,GAAG,UAAU,CAAC,gBAAgB,EAAE,CAAC,MAAM,CAAC,CAAC;IACxD,MAAM,KAAK,GAAG;QACZ,GAAG,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,UAAU,CAAC,aAAa,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAClF,GAAG,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC;KAClD,CAAC;IAEF,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 timeoutMs = descriptor.requestTimeoutMs?.(params);\n  const extra = {\n    ...(descriptor.headerBuilder ? { headers: descriptor.headerBuilder(params) } : {}),\n    ...(timeoutMs === undefined ? {} : { timeoutMs }),\n  };\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.d.ts

@@ -6,4 +6,3 @@ export type { ExecuteToolOpts } from "./execute.js";
 export { isSuccess, quotaSuffix, retryAfterSuffix } from "./errors.js";
 export { SECRET_PATTERNS, scrubSecrets } from "./redact.js";
 export { z } from "./zod.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/redact.d.ts

@@ -1,3 +1,2 @@
 export declare const SECRET_PATTERNS: readonly RegExp[];
 export declare function scrubSecrets(text: string): string;
-//# sourceMappingURL=redact.d.ts.map

package/dist/zod.d.ts

@@ -1,2 +1 @@
 export { z } from "zod";
-//# sourceMappingURL=zod.d.ts.map

package/docs/hybrid-workers.md

@@ -0,0 +1,62 @@
+# Hybrid workers
+
+A hybrid worker classifies source items with a decision model, then runs one
+language-model agent on the selected batch. For example, it can classify incoming
+email and draft replies for matching messages. One worker owns the app grants,
+configuration and run receipt.
+
+Core is an API client. It does not call model providers, launch another worker,
+run an orchestration loop or calculate wallet charges. Hybrid availability and
+the supported decision models are controlled by the connected server.
+
+## Configure
+
+Read `kit_authoring_guide` and `kit_vocabulary` for the current schema and available
+tools. A hybrid kit declares `modelType: "hybrid"`, `instructionContent`, and a
+schema-3 `decisionSpec` with `agentAction`. Validate it with `kit_validate` before
+creating or updating the kit.
+
+For an existing language worker, read `instruction_get`, then use
+`worker_decision_set` to attach, replace or remove classification:
+
+- Attaching requires `updatedAt: null`, a full `decisionSpec`, and an explicit
+  `answers` map (`{}` when there are no setup answers).
+- Replacing requires the exact current `decision.updatedAt`, a full spec and
+  replacement answers. A stale, differing update returns HTTP 409.
+- Removing requires `decisionSpec: null` and the current revision.
+
+Use `instruction_set` for prose or partial answer edits. Protected raw specs
+cannot be replaced. Decision-only workers are not converted by this operation.
+The worker's language model, instruction and app grants remain in place.
+
+## Run and read the result
+
+`worker_run` accepts classification overrides (`sourceArgs`, `answers`,
+`maxItems`) alongside the language `prompt` and `modelSlug`. An explicit
+`waitSeconds` extends only that request's timeout. Trigger POSTs are never retried
+by the client. Use `run_get` to follow an accepted run.
+
+A receipt with `kind: "hybrid"` contains:
+
+- `decision`: exact judgments, model identity, call counts and source coverage.
+- `agent`: selection counts, status and action evidence. Only confirmed actions
+  with result references establish that a draft or other result was created.
+- `usageBreakdown`: separate decision and language usage and funding.
+- `walletChargeUsd`: the server's committed charge; do not derive it from usage.
+
+No matches means no language-model calls. Treat incomplete source coverage,
+omitted rows and withheld content explicitly. Source text is untrusted data,
+not instructions. Do not automatically repeat an action with an unknown outcome.
+Hybrid runs are on demand; recurring runs are unsupported.
+
+## Model compatibility
+
+Worker kind describes behavior, not a model vendor or version. Preserve model
+identifiers and version metadata returned by the API. Use the model identity supplied by the server; do not infer confidence semantics
+or silently substitute providers. `models_list` lists language models; it is not
+a decision-model picker.
+
+Consumers should validate inputs with each descriptor's Zod schema before calling
+`executeTool`; that function maps requests and does not perform schema validation.
+`ApiResult.data` preserves the API response. `mapData` is an optional compact
+presentation for human or agent output, not the raw receipt contract.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workerkit/core",
-  "version": "0.3.7",
+  "version": "0.3.8",
   "description": "API client and tool descriptors for WorkerKit: manage AI workers and browse the public kits directory",
   "type": "module",
   "license": "MIT",
@@ -37,22 +37,27 @@
   "sideEffects": false,
   "files": [
     "dist",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "SECURITY.md",
+    "docs/hybrid-workers.md"
   ],
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
-    "build": "tsc",
+    "build": "node -e \"require('node:fs').rmSync('dist', {recursive:true, force:true})\" && tsc -p tsconfig.json",
     "typecheck": "tsc --noEmit -p tsconfig.test.json",
     "test": "vitest run",
-    "prepublishOnly": "npm run build && npm test"
+    "prepublishOnly": "npm run check:release && npm run typecheck && npm run build && npm test",
+    "check:release": "node scripts/check-release.mjs",
+    "test:package": "node scripts/test-package.mjs",
+    "prepack": "npm run build"
   },
   "engines": {
     "node": ">=22.0.0"
   },
   "dependencies": {
-    "undici": "7.29.0",
+    "undici": "7.29.1",
     "zod": "3.25.76"
   },
   "devDependencies": {

package/dist/client.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/descriptors/decision-authoring.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"decision-authoring.d.ts","sourceRoot":"","sources":["../../src/descriptors/decision-authoring.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,WAAW,CAAC;AAC9B,OAAO,EAAU,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC;AAIzD,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAO3B,CAAC;AAEH,eAAO,MAAM,oBAAoB,EAAE,cA6BlC,CAAC"}

package/dist/descriptors/decision-receipt.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"decision-receipt.d.ts","sourceRoot":"","sources":["../../src/descriptors/decision-receipt.ts"],"names":[],"mappings":"AAAA,uFAAuF;AACvF,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAO7D"}

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

@@ -1 +0,0 @@
-{"version":3,"file":"directory.d.ts","sourceRoot":"","sources":["../../src/descriptors/directory.ts"],"names":[],"mappings":"AAmBA,OAAO,EAAa,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC;AAsB5D,KAAK,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAapC;;;GAGG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,SAAS,GAAE,MAA0B,GAAG,MAAM,GAAG,SAAS,CAYhG;AAED,gFAAgF;AAChF,wBAAgB,WAAW,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,GAAG,SAAS,CAM3D;AAED,oFAAoF;AACpF,wBAAgB,aAAa,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,CAQ9F;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,GAAG,SAAS,CAclG;AAED,0FAA0F;AAC1F,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,CAYlG;AAED,8FAA8F;AAC9F,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAOrE;AAuND,eAAO,MAAM,oBAAoB,EAAE,SAAS,cAAc,EAUzD,CAAC"}

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

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/descriptors/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,MAAM,EACN,MAAM,EACN,SAAS,EACT,OAAO,EACP,MAAM,GACP,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,UAAU,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE9E,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EACL,oBAAoB,EACpB,aAAa,EACb,eAAe,EACf,WAAW,EACX,UAAU,EACV,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,gBAAgB,CAAC;AAExB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAIjD,sEAAsE;AACtE,eAAO,MAAM,cAAc,EAAE,SAAS,cAAc,EAGnD,CAAC;AAIF,6CAA6C;AAC7C,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAE/D"}

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

@@ -1 +0,0 @@
-{"version":3,"file":"manage.d.ts","sourceRoot":"","sources":["../../src/descriptors/manage.ts"],"names":[],"mappings":"AASA,OAAO,EAA8C,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC;AA29D7F,eAAO,MAAM,iBAAiB,EAAE,SAAS,cAAc,EAkFtD,CAAC"}

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

@@ -1 +0,0 @@
-{"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/types.d.ts.map

@@ -1 +0,0 @@
-{"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/errors.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExD,8EAA8E;AAC9E,wBAAgB,SAAS,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAEpD;AAKD,wBAAgB,WAAW,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,CAKpD;AAKD,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAK1D"}

package/dist/execute.d.ts.map

@@ -1 +0,0 @@
-{"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/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,OAAO,EACL,cAAc,EACd,eAAe,EACf,qBAAqB,GACtB,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,SAAS,EACT,YAAY,EACZ,aAAa,EACb,SAAS,EACT,WAAW,GACZ,MAAM,aAAa,CAAC;AAErB,cAAc,wBAAwB,CAAC;AAEvC,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,YAAY,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEpD,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"}

package/dist/redact.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"redact.d.ts","sourceRoot":"","sources":["../src/redact.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,eAAe,EAAE,SAAS,MAAM,EAG5C,CAAC;AAEF,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAMjD"}

package/dist/zod.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"zod.d.ts","sourceRoot":"","sources":["../src/zod.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC"}