digital-tools 2.1.3 → 2.4.0

package/.turbo/turbo-build.log

@@ -1,4 +1,4 @@
 
-> digital-tools@2.1.3 build /Users/nathanclevenger/projects/primitives.org.ai/packages/digital-tools
+> digital-tools@2.3.0 build /Users/nathanclevenger/projects/primitives.org.ai/packages/digital-tools
 > tsc
 

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # digital-tools
 
+## 2.4.0
+
+### Patch Changes
+
+- Updated dependencies [4d58f5f]
+- Updated dependencies [d30c2e8]
+  - ai-functions@2.4.0
+  - business-as-code@2.4.0
+  - ai-database@2.4.0
+
+## 2.3.0
+
+### Patch Changes
+
+- Updated dependencies [9e2779a]
+- Updated dependencies [b7c7c57]
+  - ai-functions@2.3.0
+  - ai-database@2.3.0
+
 ## 2.1.3
 
 ### Patch Changes

package/README.md

@@ -1,5 +1,7 @@
 # Digital Tools
 
+![Stability: Experimental](https://img.shields.io/badge/stability-experimental-red)
+
 Entity types (Nouns) and providers for digital tools usable by both humans and AI agents.
 
 ## Categories

package/dist/client.d.ts

@@ -0,0 +1,109 @@
+/**
+ * RPC Client for digital-tools worker
+ *
+ * Connects to a deployed digital-tools worker using rpc.do,
+ * providing a fully typed client for tool discovery, execution,
+ * and MCP conversion.
+ *
+ * @example
+ * ```ts
+ * import { createToolClient } from 'digital-tools/client'
+ *
+ * const client = createToolClient('https://digital-tools.workers.dev')
+ * const tools = await client.list()
+ * const result = await client.executeTool('data.json.parse', { text: '{}' })
+ * ```
+ *
+ * @packageDocumentation
+ */
+import type { AnyTool, ToolCategory, ToolQuery, MCPTool, ToolSubcategory } from './types.js';
+/**
+ * Client options for connecting to a digital-tools worker
+ */
+export interface ToolClientOptions {
+    /** Authentication token */
+    token?: string;
+    /** Custom headers */
+    headers?: Record<string, string>;
+}
+/**
+ * API type matching ToolServiceCore's public RPC methods
+ *
+ * This interface mirrors the public methods of ToolServiceCore
+ * from the worker, providing a typed contract for the RPC client.
+ */
+export interface ToolServiceAPI {
+    /** Register a tool in the service registry */
+    register(tool: AnyTool): void;
+    /** Unregister a tool */
+    unregister(id: string): boolean;
+    /** Get a tool by ID */
+    get(id: string): AnyTool | undefined;
+    /** Check if a tool exists */
+    has(id: string): boolean;
+    /** List all tool IDs */
+    list(): string[];
+    /** Query tools with filtering */
+    query(options: ToolQuery): AnyTool[];
+    /** Get tools by category */
+    byCategory(category: ToolCategory): AnyTool[];
+    /** Execute a tool by ID */
+    executeTool<TInput = unknown, TOutput = unknown>(id: string, input: TInput): Promise<TOutput>;
+    /** Convert a tool to MCP format */
+    toMCP(tool: AnyTool): MCPTool;
+    /** Convert all registered tools to MCP format */
+    listMCPTools(): MCPTool[];
+    /** Import a tool from MCP format */
+    fromMCP(mcpTool: MCPTool, handler: (input: unknown) => unknown | Promise<unknown>, options?: {
+        category?: ToolCategory;
+        subcategory?: ToolSubcategory;
+        tags?: string[];
+    }): AnyTool;
+    /** Clear all tools */
+    clear(keepBuiltins?: boolean): void;
+}
+/**
+ * Create an RPC client that connects to a deployed digital-tools worker
+ *
+ * @param url - The URL of the deployed digital-tools worker
+ * @param options - Optional client configuration
+ * @returns A typed RPC client for the tool service
+ *
+ * @example
+ * ```ts
+ * import { createToolClient } from 'digital-tools/client'
+ *
+ * // Connect to default worker
+ * const client = createToolClient()
+ *
+ * // Connect to custom deployment
+ * const client = createToolClient('https://my-tools.example.com')
+ *
+ * // List available tools
+ * const toolIds = await client.list()
+ *
+ * // Execute a tool
+ * const result = await client.executeTool('data.json.parse', { text: '{"key": "value"}' })
+ *
+ * // Query tools by category
+ * const dataTools = await client.query({ category: 'data' })
+ *
+ * // Get MCP-compatible tool definitions
+ * const mcpTools = await client.listMCPTools()
+ * ```
+ */
+export declare function createToolClient(url?: string, options?: ToolClientOptions): import("rpc.do").RPCProxy<ToolServiceAPI>;
+/**
+ * Default RPC client connected to the standard digital-tools worker deployment
+ *
+ * @example
+ * ```ts
+ * import client from 'digital-tools/client'
+ *
+ * const tools = await client.list()
+ * const result = await client.executeTool('data.json.parse', { text: '{}' })
+ * ```
+ */
+declare const client: import("rpc.do").RPCProxy<ToolServiceAPI>;
+export default client;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAE5F;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,2BAA2B;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,qBAAqB;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACjC;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,8CAA8C;IAC9C,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAAA;IAE7B,wBAAwB;IACxB,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAA;IAE/B,uBAAuB;IACvB,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAAA;IAEpC,6BAA6B;IAC7B,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAA;IAExB,wBAAwB;IACxB,IAAI,IAAI,MAAM,EAAE,CAAA;IAEhB,iCAAiC;IACjC,KAAK,CAAC,OAAO,EAAE,SAAS,GAAG,OAAO,EAAE,CAAA;IAEpC,4BAA4B;IAC5B,UAAU,CAAC,QAAQ,EAAE,YAAY,GAAG,OAAO,EAAE,CAAA;IAE7C,2BAA2B;IAC3B,WAAW,CAAC,MAAM,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAE7F,mCAAmC;IACnC,KAAK,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAA;IAE7B,iDAAiD;IACjD,YAAY,IAAI,OAAO,EAAE,CAAA;IAEzB,oCAAoC;IACpC,OAAO,CACL,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,EACvD,OAAO,CAAC,EAAE;QACR,QAAQ,CAAC,EAAE,YAAY,CAAA;QACvB,WAAW,CAAC,EAAE,eAAe,CAAA;QAC7B,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;KAChB,GACA,OAAO,CAAA;IAEV,sBAAsB;IACtB,KAAK,CAAC,YAAY,CAAC,EAAE,OAAO,GAAG,IAAI,CAAA;CACpC;AAKD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,GAAE,MAAoB,EAAE,OAAO,CAAC,EAAE,iBAAiB,6CAGtF;AAED;;;;;;;;;;GAUG;AACH,QAAA,MAAM,MAAM,2CAAqB,CAAA;AAEjC,eAAe,MAAM,CAAA"}

package/dist/client.js

@@ -0,0 +1,69 @@
+/**
+ * RPC Client for digital-tools worker
+ *
+ * Connects to a deployed digital-tools worker using rpc.do,
+ * providing a fully typed client for tool discovery, execution,
+ * and MCP conversion.
+ *
+ * @example
+ * ```ts
+ * import { createToolClient } from 'digital-tools/client'
+ *
+ * const client = createToolClient('https://digital-tools.workers.dev')
+ * const tools = await client.list()
+ * const result = await client.executeTool('data.json.parse', { text: '{}' })
+ * ```
+ *
+ * @packageDocumentation
+ */
+import { RPC, http } from 'rpc.do';
+/** Default worker URL for digital-tools */
+const DEFAULT_URL = 'https://digital-tools.workers.dev';
+/**
+ * Create an RPC client that connects to a deployed digital-tools worker
+ *
+ * @param url - The URL of the deployed digital-tools worker
+ * @param options - Optional client configuration
+ * @returns A typed RPC client for the tool service
+ *
+ * @example
+ * ```ts
+ * import { createToolClient } from 'digital-tools/client'
+ *
+ * // Connect to default worker
+ * const client = createToolClient()
+ *
+ * // Connect to custom deployment
+ * const client = createToolClient('https://my-tools.example.com')
+ *
+ * // List available tools
+ * const toolIds = await client.list()
+ *
+ * // Execute a tool
+ * const result = await client.executeTool('data.json.parse', { text: '{"key": "value"}' })
+ *
+ * // Query tools by category
+ * const dataTools = await client.query({ category: 'data' })
+ *
+ * // Get MCP-compatible tool definitions
+ * const mcpTools = await client.listMCPTools()
+ * ```
+ */
+export function createToolClient(url = DEFAULT_URL, options) {
+    const token = options?.token;
+    return RPC(http(url, token));
+}
+/**
+ * Default RPC client connected to the standard digital-tools worker deployment
+ *
+ * @example
+ * ```ts
+ * import client from 'digital-tools/client'
+ *
+ * const tools = await client.list()
+ * const result = await client.executeTool('data.json.parse', { text: '{}' })
+ * ```
+ */
+const client = createToolClient();
+export default client;
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAA;AAiElC,2CAA2C;AAC3C,MAAM,WAAW,GAAG,mCAAmC,CAAA;AAEvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAc,WAAW,EAAE,OAA2B;IACrF,MAAM,KAAK,GAAG,OAAO,EAAE,KAAK,CAAA;IAC5B,OAAO,GAAG,CAAiB,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,CAAA;AAC9C,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,GAAG,gBAAgB,EAAE,CAAA;AAEjC,eAAe,MAAM,CAAA"}

package/dist/define.d.ts

@@ -94,7 +94,7 @@ export declare function toolBuilder(id: string): {
     name(name: string): /*elided*/ any;
     description(description: string): /*elided*/ any;
     category(category: DefineToolOptions<unknown, unknown>["category"]): /*elided*/ any;
-    subcategory(subcategory: DefineToolOptions<unknown, unknown>["subcategory"]): /*elided*/ any;
+    subcategory(subcategory: NonNullable<DefineToolOptions<unknown, unknown>["subcategory"]>): /*elided*/ any;
     input(schema: Schema): /*elided*/ any;
     output(schema: Schema): /*elided*/ any;
     handler<TInput, TOutput>(fn: (input: TInput) => TOutput | Promise<TOutput>): {
@@ -102,7 +102,7 @@ export declare function toolBuilder(id: string): {
         register(): Tool<TInput, TOutput>;
         options(opts: Partial<AnyTool>): ReturnType<typeof toolBuilder>;
     };
-    options(opts: Partial<AnyTool>): /*elided*/ any;
+    options(opts: NonNullable<DefineToolOptions<unknown, unknown>["options"]>): /*elided*/ any;
     build<TInput, TOutput>(): Tool<TInput, TOutput>;
     register<TInput, TOutput>(): Tool<TInput, TOutput>;
 };

package/dist/define.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"define.d.ts","sourceRoot":"","sources":["../src/define.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EACV,OAAO,EACP,IAAI,EAEJ,iBAAiB,EACjB,WAAW,EACX,UAAU,EACV,MAAM,EACP,MAAM,YAAY,CAAA;AAgDnB;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,OAAO,EACxC,OAAO,EAAE,iBAAiB,CAAC,MAAM,EAAE,OAAO,CAAC,GAC1C,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,CAmBvB;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,OAAO,EAC/C,OAAO,EAAE,iBAAiB,CAAC,MAAM,EAAE,OAAO,CAAC,GAC1C,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,CAIvB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,WAAW;IAEnD;;OAEG;YACW,MAAM,EAAE,OAAO,UACnB,MAAM,SACP,MAAM,GACZ,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;IA4D/B;;OAEG;qBACc,OAAO,EAAE;EAM7B;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM;eAIvB,MAAM;6BAKQ,MAAM;uBAKZ,iBAAiB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,UAAU,CAAC;6BAKzC,iBAAiB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,aAAa,CAAC;kBAK7D,MAAM;mBAKL,MAAM;YAKb,MAAM,EAAE,OAAO,MAAM,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,GAE9C;QACxB,KAAK,IAAI,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;QAC9B,QAAQ,IAAI,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;QACjC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,UAAU,CAAC,OAAO,WAAW,CAAC,CAAA;KAChE;kBAGW,OAAO,CAAC,OAAO,CAAC;UAKxB,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC;aAOtC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC;EAMrD"}
+{"version":3,"file":"define.d.ts","sourceRoot":"","sources":["../src/define.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EACV,OAAO,EACP,IAAI,EAEJ,iBAAiB,EACjB,WAAW,EACX,UAAU,EACV,MAAM,EACP,MAAM,YAAY,CAAA;AA+CnB;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,OAAO,EACxC,OAAO,EAAE,iBAAiB,CAAC,MAAM,EAAE,OAAO,CAAC,GAC1C,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,CA2BvB;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,OAAO,EAC/C,OAAO,EAAE,iBAAiB,CAAC,MAAM,EAAE,OAAO,CAAC,GAC1C,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,CAIvB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,WAAW;IAEnD;;OAEG;YACW,MAAM,EAAE,OAAO,UAAU,MAAM,SAAS,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;IAwD3F;;OAEG;qBACc,OAAO,EAAE;EAM7B;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM;eAIvB,MAAM;6BAKQ,MAAM;uBAKZ,iBAAiB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,UAAU,CAAC;6BAKzC,WAAW,CAAC,iBAAiB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,aAAa,CAAC,CAAC;kBAK1E,MAAM;mBAKL,MAAM;YAKb,MAAM,EAAE,OAAO,MAAM,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,GAE9C;QACxB,KAAK,IAAI,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;QAC9B,QAAQ,IAAI,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;QACjC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,UAAU,CAAC,OAAO,WAAW,CAAC,CAAA;KAChE;kBAGW,WAAW,CAAC,iBAAiB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,SAAS,CAAC,CAAC;UAKnE,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC;aAatC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC;EAMrD"}

package/dist/define.js

@@ -80,14 +80,22 @@ export function defineTool(options) {
         name: options.name,
         description: options.description,
         category: options.category,
-        subcategory: options.subcategory,
+        ...(options.subcategory !== undefined && { subcategory: options.subcategory }),
+        // SVO co-design (aip-oejp) — all optional. Verb auto-registration in
+        // digital-objects is intentionally deferred (see bead aip-oejp follow-up):
+        // we store the metadata here so dispatchers can resolve it, but we don't
+        // mutate the cross-package Verb registry from a `defineTool()` side-effect.
+        ...(options.verb !== undefined && { verb: options.verb }),
+        ...(options.frame !== undefined && { frame: options.frame }),
+        ...(options.auth !== undefined && { auth: options.auth }),
+        ...(options.pricing !== undefined && { pricing: options.pricing }),
         parameters: schemaToParameters(options.input),
-        output: options.output
-            ? {
+        ...(options.output && {
+            output: {
                 description: 'Tool output',
                 schema: options.output,
-            }
-            : undefined,
+            },
+        }),
         handler: options.handler,
         ...options.options,
     };
@@ -135,9 +143,7 @@ export function createToolExecutor(context) {
                 };
             }
             // Check audience restrictions
-            if (tool.audience &&
-                tool.audience !== 'both' &&
-                tool.audience !== context.executor.type) {
+            if (tool.audience && tool.audience !== 'both' && tool.audience !== context.executor.type) {
                 return {
                     success: false,
                     error: {
@@ -155,7 +161,7 @@ export function createToolExecutor(context) {
                     data,
                     metadata: {
                         duration,
-                        requestId: context.requestId,
+                        ...(context.requestId !== undefined && { requestId: context.requestId }),
                     },
                 };
             }
@@ -170,7 +176,7 @@ export function createToolExecutor(context) {
                     },
                     metadata: {
                         duration,
-                        requestId: context.requestId,
+                        ...(context.requestId !== undefined && { requestId: context.requestId }),
                     },
                 };
             }
@@ -245,7 +251,11 @@ export function toolBuilder(id) {
             return this;
         },
         build() {
-            if (!config.name || !config.description || !config.category || !config.input || !config.handler) {
+            if (!config.name ||
+                !config.description ||
+                !config.category ||
+                !config.input ||
+                !config.handler) {
                 throw new Error('Tool requires id, name, description, category, input, and handler');
             }
             return defineTool(config);

package/dist/define.js.map

@@ -1 +1 @@
-{"version":3,"file":"define.js","sourceRoot":"","sources":["../src/define.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,WAAW,EAAmB,MAAM,cAAc,CAAA;AAU3D,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAExC;;GAEG;AACH,SAAS,YAAY,CAAC,MAAc;IAClC,IAAI,WAAW,CAAC,MAAM,CAAC,EAAE,CAAC;QACxB,6DAA6D;QAC7D,yCAAyC;QACzC,OAAO;YACL,IAAI,EAAE,QAAQ;YACd,WAAW,EAAE,8CAA8C;SAC5D,CAAA;IACH,CAAC;IACD,OAAO,MAAoB,CAAA;AAC7B,CAAC;AAED;;GAEG;AACH,SAAS,kBAAkB,CAAC,MAAc;IACxC,MAAM,UAAU,GAAG,YAAY,CAAC,MAAM,CAAC,CAAA;IAEvC,IAAI,UAAU,CAAC,IAAI,KAAK,QAAQ,IAAI,CAAC,UAAU,CAAC,UAAU,EAAE,CAAC;QAC3D,mBAAmB;QACnB,OAAO;YACL;gBACE,IAAI,EAAE,OAAO;gBACb,WAAW,EAAE,UAAU,CAAC,WAAW,IAAI,aAAa;gBACpD,MAAM,EAAE,UAAU;gBAClB,QAAQ,EAAE,IAAI;aACf;SACF,CAAA;IACH,CAAC;IAED,MAAM,QAAQ,GAAG,UAAU,CAAC,QAAQ,IAAI,EAAE,CAAA;IAE1C,OAAO,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,UAAU,CAAC,EAAE,EAAE,CAAC,CAAC;QACxE,IAAI;QACJ,WAAW,EACR,UAAyB,CAAC,WAAW,IAAI,cAAc,IAAI,EAAE;QAChE,MAAM,EAAE,UAAwB;QAChC,QAAQ,EAAE,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC;QACjC,OAAO,EAAG,UAAyB,CAAC,OAAO;KAC5C,CAAC,CAAC,CAAA;AACL,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,UAAU,CACxB,OAA2C;IAE3C,MAAM,IAAI,GAA0B;QAClC,EAAE,EAAE,OAAO,CAAC,EAAE;QACd,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,UAAU,EAAE,kBAAkB,CAAC,OAAO,CAAC,KAAK,CAAC;QAC7C,MAAM,EAAE,OAAO,CAAC,MAAM;YACpB,CAAC,CAAC;gBACE,WAAW,EAAE,aAAa;gBAC1B,MAAM,EAAE,OAAO,CAAC,MAAM;aACvB;YACH,CAAC,CAAC,SAAS;QACb,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,GAAG,OAAO,CAAC,OAAO;KACnB,CAAA;IAED,OAAO,IAAI,CAAA;AACb,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAC/B,OAA2C;IAE3C,MAAM,IAAI,GAAG,UAAU,CAAC,OAAO,CAAC,CAAA;IAChC,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAA;IACvB,OAAO,IAAI,CAAA;AACb,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAoB;IACrD,OAAO;QACL;;WAEG;QACH,KAAK,CAAC,OAAO,CACX,MAAc,EACd,KAAa;YAEb,MAAM,IAAI,GAAG,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;YAEjC,IAAI,CAAC,IAAI,EAAE,CAAC;gBACV,OAAO;oBACL,OAAO,EAAE,KAAK;oBACd,KAAK,EAAE;wBACL,IAAI,EAAE,gBAAgB;wBACtB,OAAO,EAAE,SAAS,MAAM,aAAa;qBACtC;iBACF,CAAA;YACH,CAAC;YAED,8BAA8B;YAC9B,IACE,IAAI,CAAC,QAAQ;gBACb,IAAI,CAAC,QAAQ,KAAK,MAAM;gBACxB,IAAI,CAAC,QAAQ,KAAK,OAAO,CAAC,QAAQ,CAAC,IAAI,EACvC,CAAC;gBACD,OAAO;oBACL,OAAO,EAAE,KAAK;oBACd,KAAK,EAAE;wBACL,IAAI,EAAE,eAAe;wBACrB,OAAO,EAAE,SAAS,MAAM,0BAA0B,OAAO,CAAC,QAAQ,CAAC,IAAI,EAAE;qBAC1E;iBACF,CAAA;YACH,CAAC;YAED,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAA;YAE5B,IAAI,CAAC;gBACH,MAAM,IAAI,GAAG,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAY,CAAA;gBACnD,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAA;gBAEvC,OAAO;oBACL,OAAO,EAAE,IAAI;oBACb,IAAI;oBACJ,QAAQ,EAAE;wBACR,QAAQ;wBACR,SAAS,EAAE,OAAO,CAAC,SAAS;qBAC7B;iBACF,CAAA;YACH,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAA;gBAEvC,OAAO;oBACL,OAAO,EAAE,KAAK;oBACd,KAAK,EAAE;wBACL,IAAI,EAAE,iBAAiB;wBACvB,OAAO,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;wBAC/D,OAAO,EAAE,KAAK;qBACf;oBACD,QAAQ,EAAE;wBACR,QAAQ;wBACR,SAAS,EAAE,OAAO,CAAC,SAAS;qBAC7B;iBACF,CAAA;YACH,CAAC;QACH,CAAC;QAED;;WAEG;QACH,aAAa;YACX,OAAO,QAAQ,CAAC,KAAK,CAAC;gBACpB,QAAQ,EAAE,OAAO,CAAC,QAAQ,CAAC,IAAI;aAChC,CAAC,CAAA;QACJ,CAAC;KACF,CAAA;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,WAAW,CAAC,EAAU;IACpC,MAAM,MAAM,GAAiD,EAAE,EAAE,EAAE,CAAA;IAEnE,OAAO;QACL,IAAI,CAAC,IAAY;YACf,MAAM,CAAC,IAAI,GAAG,IAAI,CAAA;YAClB,OAAO,IAAI,CAAA;QACb,CAAC;QAED,WAAW,CAAC,WAAmB;YAC7B,MAAM,CAAC,WAAW,GAAG,WAAW,CAAA;YAChC,OAAO,IAAI,CAAA;QACb,CAAC;QAED,QAAQ,CAAC,QAAyD;YAChE,MAAM,CAAC,QAAQ,GAAG,QAAQ,CAAA;YAC1B,OAAO,IAAI,CAAA;QACb,CAAC;QAED,WAAW,CAAC,WAA+D;YACzE,MAAM,CAAC,WAAW,GAAG,WAAW,CAAA;YAChC,OAAO,IAAI,CAAA;QACb,CAAC;QAED,KAAK,CAAC,MAAc;YAClB,MAAM,CAAC,KAAK,GAAG,MAAM,CAAA;YACrB,OAAO,IAAI,CAAA;QACb,CAAC;QAED,MAAM,CAAC,MAAc;YACnB,MAAM,CAAC,MAAM,GAAG,MAAM,CAAA;YACtB,OAAO,IAAI,CAAA;QACb,CAAC;QAED,OAAO,CAAkB,EAAiD;YACxE,MAAM,CAAC,OAAO,GAAG,EAAoD,CAAA;YACrE,OAAO,IAIN,CAAA;QACH,CAAC;QAED,OAAO,CAAC,IAAsB;YAC5B,MAAM,CAAC,OAAO,GAAG,IAAsD,CAAA;YACvE,OAAO,IAAI,CAAA;QACb,CAAC;QAED,KAAK;YACH,IAAI,CAAC,MAAM,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,WAAW,IAAI,CAAC,MAAM,CAAC,QAAQ,IAAI,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;gBAChG,MAAM,IAAI,KAAK,CAAC,mEAAmE,CAAC,CAAA;YACtF,CAAC;YACD,OAAO,UAAU,CAAC,MAA4C,CAAC,CAAA;QACjE,CAAC;QAED,QAAQ;YACN,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,EAAmB,CAAA;YAC1C,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAA;YACvB,OAAO,IAAI,CAAA;QACb,CAAC;KACF,CAAA;AACH,CAAC"}
+{"version":3,"file":"define.js","sourceRoot":"","sources":["../src/define.ts"],"names":[],"mappings":"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"}

package/dist/function-ref.d.ts

@@ -0,0 +1,229 @@
+/**
+ * FunctionRef — discriminated union of the Four Functions (v3 §6).
+ *
+ * The Services-as-Software book decomposes any cascade step into one of four
+ * Function kinds:
+ *
+ *   - `code`        — deterministic, programmable. A pure function or a
+ *                     reference to a code Action.
+ *   - `generative`  — single-shot LLM call (no tool use, no agentic loop).
+ *   - `agentic`     — looping, tool-using AI worker with a persona.
+ *   - `human`       — work that *must* be performed by a person, with a
+ *                     declared rationale + expiration policy describing the
+ *                     conditions under which the Function may be migrated to
+ *                     a non-human kind.
+ *
+ * Each kind carries the same per-Function knobs the v3 design pins:
+ * a {@link RewardSignal} reference, a {@link CostModel}, an
+ * {@link OversightPolicy}, and a {@link TrackRecord}. The agentic and human
+ * variants additionally carry kind-specific shape (mode/persona vs.
+ * rationale/expiration).
+ *
+ * This type is *additive* alongside the legacy {@link Tool} interface.
+ * Existing tools are not migrated; new SaS cascades use `FunctionRef` directly.
+ *
+ * @packageDocumentation
+ */
+import type { ActionRef } from 'digital-objects';
+import type { CostModel } from 'business-as-code/finance';
+import type { AgentMode, PromotionPolicy, TrackRecord } from './track-record.js';
+/**
+ * Placeholder reward signal — the canonical type ships in `business-as-code`
+ * once the OKR / KeyResult primitives land. Until then, a Function declares
+ * the KeyResult it should be rewarded against by reference.
+ *
+ * The string form is an MDXLD `$id` that resolves to a KeyResult node in the
+ * BaC graph (e.g. `'kr:revenue.q3.signups'`).
+ */
+export interface RewardSignal {
+    /** `$id` of the KeyResult the Function moves the needle on. */
+    keyResultRef: string;
+}
+/**
+ * Reusable persona reference for an agentic Function — typically a string
+ * `$id` into the persona library shipped by `ai-evaluate`. Kept opaque here
+ * to avoid a layer-up dependency on `ai-evaluate`.
+ */
+export type PersonaRef = string;
+/**
+ * Sign-off policy on the output of an agentic Function before it is released
+ * downstream. `none` means no per-invocation sign-off (autonomous);
+ * `self` means the Function reviews its own output against its persona;
+ * `peer` requires another agentic Function to approve; `human` requires a
+ * human reviewer; `panel` defers to an EvaluatorPanel reference.
+ */
+export type SignOffMode = 'none' | 'self' | 'peer' | 'human' | 'panel';
+/**
+ * Declarative oversight gate applied per-invocation to a Function.
+ *
+ * `mode` selects the {@link AgentMode} the Function is currently operating in;
+ * `promotion` (when present) is the {@link PromotionPolicy} that may move the
+ * Function up or down the ladder based on its {@link TrackRecord}.
+ */
+export interface OversightPolicy {
+    mode: AgentMode;
+    promotion?: PromotionPolicy;
+}
+/**
+ * Fields common to every Function kind. The discriminator (`kind`) is added
+ * by each variant so consumers can narrow with a single switch.
+ */
+export interface BaseFunctionRef {
+    /** MDXLD `$id` (e.g. `'fn:code:summarize'`). */
+    $id: string;
+    /** Human-readable name used by the registry / UI. */
+    name: string;
+    /** Optional one-line description rendered by catalog UIs. */
+    description?: string;
+    /** Reward this Function is optimised against, when known. */
+    reward?: RewardSignal;
+    /** Declared cost model — used for budgeting and price quoting. */
+    costModel?: CostModel;
+    /** Per-Function oversight + autonomy policy. */
+    oversight?: OversightPolicy;
+    /**
+     * Accumulated quality / cost / override signal. Present on materialised
+     * (registered) Functions; omitted on the spec passed to a sugar factory.
+     */
+    track?: TrackRecord;
+}
+/**
+ * Code Function — deterministic, programmable.
+ *
+ * `handler` may be either an inline function (preferred for in-process
+ * Services) or an {@link ActionRef} string pointing at a registered Action
+ * in `digital-objects` (preferred for cross-process / serialisable cascades).
+ */
+export interface CodeFunctionRef<TInput = unknown, TOutput = unknown> extends BaseFunctionRef {
+    kind: 'code';
+    handler: ((input: TInput) => TOutput | Promise<TOutput>) | ActionRef;
+}
+/**
+ * Generative Function — single-shot LLM call. No tool use, no loop.
+ *
+ * `modelHint` is an optional preferred model spec (e.g. `'claude-opus-4'`);
+ * the runtime is free to substitute based on cost/availability policy.
+ *
+ * `outputSchema` (round-13) is an optional per-step output contract used by
+ * the cascade walker to constrain mid-cascade Generative output. When
+ * present, the walker passes it to `ai-functions.generateObject` for that
+ * step; when absent, the walker falls back to the Service's
+ * `schema.output` for the LAST Generative step and `z.string()` for earlier
+ * ones. Typed as `unknown` because the canonical Standard Schema type lives
+ * in `services-as-software` and `digital-tools` shouldn't pull that
+ * dependency — call sites cast to their concrete schema type.
+ */
+export interface GenerativeFunctionRef extends BaseFunctionRef {
+    kind: 'generative';
+    modelHint?: string;
+    outputSchema?: unknown;
+}
+/**
+ * Agentic Function — looping, tool-using AI worker with a persona and a
+ * sign-off rule.
+ */
+export interface AgenticFunctionRef extends BaseFunctionRef {
+    kind: 'agentic';
+    /**
+     * Operating mode for this Function specifically. Mirrors
+     * {@link OversightPolicy.mode}; declared inline because the agentic kind is
+     * the primary consumer of the autonomy ladder.
+     */
+    mode: AgentMode;
+    /**
+     * Optional preferred model spec (e.g. `'claude-opus-4'`, `'sonnet'`).
+     * Mirrors {@link GenerativeFunctionRef.modelHint}; the runtime is free to
+     * substitute based on cost/availability/track-record policy. The
+     * `services-as-software` cascade walker forwards this to
+     * `ai-functions.generateText` for the agentic tool-use loop.
+     */
+    modelHint?: string;
+    /**
+     * Tool ids registered with `digital-tools.defineTool`. Each id resolves to
+     * exactly one {@link Tool} via the global registry. Scope-style strings
+     * (e.g. `'github.repos'`) are accepted but treated as literal tool ids,
+     * not permission scopes — the runtime does not expand `'github.repos'`
+     * into the set of github repo tools. True scope→tools resolution
+     * (capability-based permission expansion) is round-9+ work; until then,
+     * list each concrete tool id explicitly.
+     */
+    toolPermissions?: string[];
+    /**
+     * Concurrency policy for this Function:
+     *
+     *   - `number`     — hard cap on concurrent invocations (caller picks N).
+     *   - `'serial'`   — one invocation at a time (semantic alias for `1`).
+     *   - `'fan-out'`  — semantic "fan out as wide as upstream emits"; the
+     *                    cascade compiler chooses N at runtime based on the
+     *                    upstream step's emitted batch size and ambient
+     *                    cost-budget policy.
+     *
+     * Used by the runtime to bound cost on bursty workloads.
+     */
+    concurrency?: number | 'serial' | 'fan-out';
+    /** Persona reference (typically into the `ai-evaluate` persona library). */
+    persona?: PersonaRef;
+    /**
+     * Sign-off requirement before the Function's output is released downstream.
+     * Defaults to `'none'` for `mode === 'autonomous'`, `'human'` for
+     * `mode === 'supervised'`, and `'human'` for `mode === 'manual'`.
+     */
+    signOff?: SignOffMode;
+}
+/**
+ * Reasons a step in the cascade *must* be performed by a human. Drives both
+ * UX copy ("why is a human reviewing this?") and the migration policy
+ * ({@link HumanFunctionRef.expirationPolicy} declares when the human step
+ * may be replaced by a non-human Function).
+ */
+export type HumanRationale = 'approval' | 'physical' | 'regulatory' | 'trust' | 'premium';
+/**
+ * Conditions under which a {@link HumanFunctionRef} may be migrated to a
+ * non-human Function (typically an {@link AgenticFunctionRef}).
+ *
+ * The expiration is *declarative*: the policy is checked against the
+ * Function's accumulated {@link TrackRecord} (and any sibling-Function
+ * record indicated by `migrateTo`). When the predicate holds, the cascade
+ * compiler may swap the Human Function for the named target Function with
+ * the catalog operator's confirmation.
+ */
+export interface HumanExpirationPolicy {
+    /** `$id` of the Function the human step should migrate to once eligible. */
+    migrateTo?: string;
+    /**
+     * Migrate when the cascade-without-the-human's accuracy exceeds this
+     * threshold (0–1). The bookkeeper case ("could AI have decided this
+     * correctly?") is the canonical example — see v3 §14 open decision.
+     */
+    whenAccuracyExceeds?: number;
+    /** Migrate when total samples exceed this count. */
+    whenSamplesExceed?: number;
+}
+/**
+ * Channel used to dispatch work to a human. Opaque string so concrete
+ * channels (Slack DM, email, in-app inbox, paging system, …) can be wired
+ * by the runtime without a type change here.
+ */
+export type HumanChannel = string;
+/**
+ * Human Function — work that must be performed by a person.
+ *
+ * Carries a declared {@link HumanRationale} (so UX can explain *why* a human
+ * is in the loop) and an {@link HumanExpirationPolicy} (so the cascade can
+ * eventually be migrated to a non-human Function once track-record allows).
+ */
+export interface HumanFunctionRef extends BaseFunctionRef {
+    kind: 'human';
+    rationale: HumanRationale;
+    expirationPolicy: HumanExpirationPolicy;
+    channel?: HumanChannel;
+}
+/**
+ * Discriminated union of the Four Functions. Narrow with `switch (fn.kind)`.
+ */
+export type FunctionRef = CodeFunctionRef | GenerativeFunctionRef | AgenticFunctionRef | HumanFunctionRef;
+/**
+ * Discriminator string union — convenient for table-driven dispatchers.
+ */
+export type FunctionKind = FunctionRef['kind'];
+//# sourceMappingURL=function-ref.d.ts.map

package/dist/function-ref.d.ts.map

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

package/dist/function-ref.js

@@ -0,0 +1,28 @@
+/**
+ * FunctionRef — discriminated union of the Four Functions (v3 §6).
+ *
+ * The Services-as-Software book decomposes any cascade step into one of four
+ * Function kinds:
+ *
+ *   - `code`        — deterministic, programmable. A pure function or a
+ *                     reference to a code Action.
+ *   - `generative`  — single-shot LLM call (no tool use, no agentic loop).
+ *   - `agentic`     — looping, tool-using AI worker with a persona.
+ *   - `human`       — work that *must* be performed by a person, with a
+ *                     declared rationale + expiration policy describing the
+ *                     conditions under which the Function may be migrated to
+ *                     a non-human kind.
+ *
+ * Each kind carries the same per-Function knobs the v3 design pins:
+ * a {@link RewardSignal} reference, a {@link CostModel}, an
+ * {@link OversightPolicy}, and a {@link TrackRecord}. The agentic and human
+ * variants additionally carry kind-specific shape (mode/persona vs.
+ * rationale/expiration).
+ *
+ * This type is *additive* alongside the legacy {@link Tool} interface.
+ * Existing tools are not migrated; new SaS cascades use `FunctionRef` directly.
+ *
+ * @packageDocumentation
+ */
+export {};
+//# sourceMappingURL=function-ref.js.map

package/dist/function-ref.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"function-ref.js","sourceRoot":"","sources":["../src/function-ref.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG"}