@framers/agentos 0.1.93 → 0.1.95

package/dist/emergent/ComposableToolBuilder.js

@@ -0,0 +1,318 @@
+/**
+ * @fileoverview ComposableToolBuilder — DSL for constructing higher-order tools
+ * by chaining existing tool invocations in a sequential pipeline.
+ *
+ * @module @framers/agentos/emergent/ComposableToolBuilder
+ *
+ * Overview:
+ * - Accepts a {@link ComposableToolSpec} describing a sequence of {@link ComposableStep}s.
+ * - At runtime each step's `inputMapping` is resolved against a shared evaluation
+ *   context consisting of the original tool input (`$input.*`), the previous step's
+ *   output (`$prev.*`), and any named step output (`$steps[N].*`).
+ * - Steps execute sequentially; the first failure aborts the pipeline and surfaces
+ *   the error immediately.
+ * - The composite tool's final output is the last step's raw output value.
+ * - Safe by construction: all tool invocations are delegated to a caller-supplied
+ *   `executeTool` callback, so the builder never touches an external registry directly.
+ */
+// ============================================================================
+// COMPOSABLE TOOL BUILDER
+// ============================================================================
+/**
+ * Builds composite {@link ITool} instances by chaining existing tool invocations.
+ *
+ * Each invocation is described by a {@link ComposableStep} that maps values from
+ * a shared pipeline context into the step tool's arguments via a lightweight
+ * reference expression syntax:
+ *
+ * | Expression | Resolves to |
+ * |---|---|
+ * | `"$input.foo"` | `args.foo` from the composite tool's own input |
+ * | `"$input"` | the whole input object |
+ * | `"$prev.bar"` | `bar` from the previous step's output |
+ * | `"$prev"` | the previous step's full output |
+ * | `"$steps[0].output.data"` | `output.data` from the first step's output |
+ * | `"$steps[0]"` | the first step's full output |
+ * | anything else | used as a literal value without transformation |
+ *
+ * Reference expressions nested inside plain objects are resolved recursively, so
+ * `{ query: "$input.topic", limit: 10 }` becomes `{ query: "actual-topic", limit: 10 }`.
+ *
+ * Safe by construction — all tool invocations are delegated to the `executeTool`
+ * callback supplied at construction time. The builder never holds a reference to
+ * any tool registry.
+ *
+ * @example
+ * ```ts
+ * const builder = new ComposableToolBuilder(async (toolName, args, ctx) => {
+ *   const tool = registry.get(toolName);
+ *   return tool.execute(args, ctx);
+ * });
+ *
+ * const spec: ComposableToolSpec = {
+ *   mode: 'compose',
+ *   steps: [
+ *     { name: 'search', tool: 'web_search', inputMapping: { query: '$input.topic' } },
+ *     { name: 'summarise', tool: 'summarise_text', inputMapping: { text: '$prev.snippet' } },
+ *   ],
+ * };
+ *
+ * const tool = builder.build('research', 'Search then summarise a topic', schema, spec);
+ * const result = await tool.execute({ topic: 'quantum computing' }, ctx);
+ * ```
+ */
+export class ComposableToolBuilder {
+    /**
+     * @param executeTool - Callback invoked for each pipeline step. Receives the
+     *   target tool name, the resolved argument object, and the outer execution
+     *   context forwarded from the composite tool's own `execute` call.
+     *   Must return a {@link ToolExecutionResult}; a `success: false` result aborts
+     *   the remainder of the pipeline.
+     */
+    constructor(executeTool) {
+        this.executeTool = executeTool;
+    }
+    // --------------------------------------------------------------------------
+    // PUBLIC API
+    // --------------------------------------------------------------------------
+    /**
+     * Build an {@link ITool}-compatible object from a {@link ComposableToolSpec}.
+     *
+     * The returned tool can be registered directly with any tool orchestrator that
+     * accepts `ITool`. Its `execute` method runs the step pipeline sequentially,
+     * threading outputs through the reference resolution system.
+     *
+     * @param name - Machine-readable tool name exposed to the LLM (e.g. `"research_topic"`).
+     * @param description - Natural language description of what the composite tool does.
+     * @param inputSchema - JSON Schema describing the arguments the composite tool accepts.
+     * @param spec - The composable pipeline specification to execute.
+     * @returns A fully-formed {@link ITool} instance whose `execute` method runs the pipeline.
+     *
+     * @example
+     * ```ts
+     * const tool = builder.build(
+     *   'fetch_and_summarise',
+     *   'Fetch a URL then return a one-paragraph summary.',
+     *   { type: 'object', properties: { url: { type: 'string' } }, required: ['url'] },
+     *   spec,
+     * );
+     * ```
+     */
+    build(name, description, inputSchema, spec) {
+        // Capture `this.executeTool` in a local binding so that the returned object's
+        // `execute` closure does not retain a reference to `this` beyond what is needed.
+        const executeTool = this.executeTool;
+        return {
+            // -----------------------------------------------------------------------
+            // Identity fields required by ITool
+            // -----------------------------------------------------------------------
+            id: `composable:${name}`,
+            name,
+            displayName: name,
+            description,
+            inputSchema,
+            hasSideEffects: true,
+            // -----------------------------------------------------------------------
+            // Core execution — runs the pipeline defined in spec
+            // -----------------------------------------------------------------------
+            async execute(args, context) {
+                /** Shared evaluation context threaded through each step. */
+                const pipelineCtx = {
+                    input: args,
+                    prev: null,
+                    steps: {},
+                };
+                let lastOutput = null;
+                for (const step of spec.steps) {
+                    // Resolve the step's inputMapping against the current pipeline context.
+                    const resolvedArgs = resolveMapping(step.inputMapping, pipelineCtx);
+                    // Invoke the underlying tool via the caller-supplied executor.
+                    const result = await executeTool(step.tool, resolvedArgs, context);
+                    if (!result.success) {
+                        // Abort the pipeline on first failure, surfacing the step's error.
+                        return {
+                            success: false,
+                            error: `Step "${step.name}" (tool: "${step.tool}") failed: ${result.error ?? 'unknown error'}`,
+                        };
+                    }
+                    lastOutput = result.output;
+                    // Advance the pipeline context so subsequent steps can reference this step.
+                    pipelineCtx.prev = lastOutput;
+                    pipelineCtx.steps[step.name] = lastOutput;
+                }
+                return { success: true, output: lastOutput };
+            },
+        };
+    }
+    /**
+     * Validate a {@link ComposableToolSpec} before building.
+     *
+     * Performs structural checks only — it does not verify that the referenced tool
+     * names are actually registered in any registry. Use this method to give early,
+     * actionable feedback before attempting to {@link build} a tool.
+     *
+     * Checks performed:
+     * 1. `spec.steps` must be a non-empty array.
+     * 2. Every step must have a non-empty `tool` string.
+     *
+     * @param spec - The spec to validate.
+     * @returns `{ valid: true }` when the spec passes all checks, or
+     *   `{ valid: false, errors: string[] }` with one message per failing check.
+     *
+     * @example
+     * ```ts
+     * const result = builder.validate(spec);
+     * if (!result.valid) {
+     *   console.error('Invalid spec:', result.errors);
+     * }
+     * ```
+     */
+    validate(spec) {
+        const errors = [];
+        if (!Array.isArray(spec.steps) || spec.steps.length === 0) {
+            errors.push('ComposableToolSpec.steps must be a non-empty array.');
+        }
+        else {
+            for (let i = 0; i < spec.steps.length; i++) {
+                const step = spec.steps[i];
+                if (typeof step.tool !== 'string' || step.tool.trim() === '') {
+                    errors.push(`Step at index ${i} has an empty or missing "tool" name.`);
+                }
+            }
+        }
+        return errors.length === 0 ? { valid: true } : { valid: false, errors };
+    }
+}
+// ============================================================================
+// INTERNAL HELPERS — not exported
+// ============================================================================
+/**
+ * Resolve an entire `inputMapping` object against the current pipeline context.
+ *
+ * Iterates over each key-value pair in `mapping`. String values that match the
+ * reference expression grammar are substituted with their runtime value; all other
+ * values (numbers, booleans, `null`, nested objects, arrays) are kept as-is, with
+ * nested objects resolved recursively.
+ *
+ * @param mapping - The raw `inputMapping` from a {@link ComposableStep}.
+ * @param ctx - The current pipeline evaluation context.
+ * @returns A new plain object with all reference expressions replaced.
+ */
+function resolveMapping(mapping, ctx) {
+    const resolved = {};
+    for (const [key, value] of Object.entries(mapping)) {
+        resolved[key] = resolveValue(value, ctx);
+    }
+    return resolved;
+}
+/**
+ * Resolve a single value against the pipeline context.
+ *
+ * - If `value` is a `string` beginning with `$`, attempt reference resolution.
+ * - If `value` is a plain object (`Record<string, unknown>`), resolve recursively.
+ * - All other values are returned unchanged.
+ *
+ * @param value - The raw value to resolve.
+ * @param ctx - The current pipeline evaluation context.
+ * @returns The resolved runtime value.
+ */
+function resolveValue(value, ctx) {
+    if (typeof value === 'string' && value.startsWith('$')) {
+        return resolveExpression(value, ctx);
+    }
+    if (isPlainObject(value)) {
+        return resolveMapping(value, ctx);
+    }
+    return value;
+}
+/**
+ * Resolve a single reference expression string.
+ *
+ * Supported expression forms:
+ * - `"$input"` → the whole input object
+ * - `"$input.a.b"` → `ctx.input.a.b` (dotted path)
+ * - `"$prev"` → the previous step's output
+ * - `"$prev.a.b"` → dotted path into `ctx.prev`
+ * - `"$steps[N]"` → the Nth named-step's output (index-based, insertion order)
+ * - `"$steps[N].a.b"` → dotted path into that step's output
+ *
+ * If the expression does not match any of these forms the original string is
+ * returned unchanged, preventing accidental silent failures.
+ *
+ * @param expr - The `$`-prefixed expression string.
+ * @param ctx - The current pipeline evaluation context.
+ * @returns The resolved runtime value, or the original `expr` string if unmatched.
+ */
+function resolveExpression(expr, ctx) {
+    // --- $input or $input.path ---
+    if (expr === '$input') {
+        return ctx.input;
+    }
+    if (expr.startsWith('$input.')) {
+        const path = expr.slice('$input.'.length);
+        return resolvePath(ctx.input, path);
+    }
+    // --- $prev or $prev.path ---
+    if (expr === '$prev') {
+        return ctx.prev;
+    }
+    if (expr.startsWith('$prev.')) {
+        const path = expr.slice('$prev.'.length);
+        return resolvePath(ctx.prev, path);
+    }
+    // --- $steps[N] or $steps[N].path ---
+    const stepsMatch = expr.match(/^\$steps\[(\d+)\](.*)$/);
+    if (stepsMatch) {
+        const index = parseInt(stepsMatch[1], 10);
+        const remainder = stepsMatch[2]; // either '' or '.some.path'
+        // Step outputs are stored by name in insertion order.
+        const stepValues = Object.values(ctx.steps);
+        if (index >= stepValues.length) {
+            // Out-of-bounds — return undefined to signal the reference doesn't exist yet.
+            return undefined;
+        }
+        const stepOutput = stepValues[index];
+        if (remainder === '' || remainder === undefined) {
+            return stepOutput;
+        }
+        if (remainder.startsWith('.')) {
+            return resolvePath(stepOutput, remainder.slice(1));
+        }
+    }
+    // Unrecognised expression — return as literal.
+    return expr;
+}
+/**
+ * Walk a dotted path string into an arbitrary value.
+ *
+ * Given `root = { a: { b: 42 } }` and `path = "a.b"`, returns `42`.
+ * Returns `undefined` for any missing segment rather than throwing.
+ *
+ * @param root - The root value to traverse.
+ * @param path - A dot-separated sequence of property names (e.g. `"output.data"`).
+ * @returns The value at the resolved path, or `undefined` if any segment is absent.
+ */
+function resolvePath(root, path) {
+    const segments = path.split('.');
+    let current = root;
+    for (const segment of segments) {
+        if (current == null || typeof current !== 'object') {
+            return undefined;
+        }
+        current = current[segment];
+    }
+    return current;
+}
+/**
+ * Returns `true` when `value` is a plain (non-array, non-null) object.
+ * Used to distinguish nested mapping objects from other value types.
+ *
+ * @param value - The value to test.
+ */
+function isPlainObject(value) {
+    return (value !== null &&
+        typeof value === 'object' &&
+        !Array.isArray(value) &&
+        Object.getPrototypeOf(value) === Object.prototype);
+}
+//# sourceMappingURL=ComposableToolBuilder.js.map

package/dist/emergent/ComposableToolBuilder.js.map

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

package/dist/emergent/EmergentCapabilityEngine.d.ts

@@ -0,0 +1,168 @@
+/**
+ * @fileoverview EmergentCapabilityEngine — orchestrates runtime tool creation.
+ * @module @framers/agentos/emergent/EmergentCapabilityEngine
+ *
+ * Provides the top-level pipeline that ties the forge subsystem together:
+ *
+ *   forge request → build tool → run tests → judge review → register
+ *
+ * Supports two creation modes:
+ * - **Compose**: chains existing tools via {@link ComposableToolBuilder} (safe by construction).
+ * - **Sandbox**: runs agent-written code via {@link SandboxedToolForge} (judge-gated).
+ *
+ * After registration the engine tracks usage and auto-promotes tools that
+ * meet the configured {@link EmergentConfig.promotionThreshold} criteria.
+ */
+import type { EmergentConfig, ForgeToolRequest, ForgeResult, PromotionResult, EmergentTool } from './types.js';
+import type { ITool } from '../core/tools/ITool.js';
+import { ComposableToolBuilder } from './ComposableToolBuilder.js';
+import { SandboxedToolForge } from './SandboxedToolForge.js';
+import { EmergentJudge } from './EmergentJudge.js';
+import { EmergentToolRegistry } from './EmergentToolRegistry.js';
+/**
+ * Dependencies injected into the {@link EmergentCapabilityEngine} constructor.
+ *
+ * All collaborators are provided externally so the engine is trivially testable
+ * with mocks — no real LLM calls, no real sandbox execution.
+ */
+export interface EmergentCapabilityEngineDeps {
+    /** Resolved emergent capability configuration. */
+    config: EmergentConfig;
+    /** Builder for composable (tool-chaining) implementations. */
+    composableBuilder: ComposableToolBuilder;
+    /** Sandboxed code executor for arbitrary-code implementations. */
+    sandboxForge: SandboxedToolForge;
+    /** LLM-as-judge evaluator for creation and promotion reviews. */
+    judge: EmergentJudge;
+    /** Tiered registry for storing and querying emergent tools. */
+    registry: EmergentToolRegistry;
+    /** Optional callback used to activate a newly forged tool immediately. */
+    onToolForged?: (tool: EmergentTool, executable: ITool) => Promise<void>;
+    /** Optional callback used when a tool is promoted to a persisted tier. */
+    onToolPromoted?: (tool: EmergentTool) => Promise<void>;
+}
+/**
+ * Orchestrates runtime tool creation for agents with emergent capabilities.
+ *
+ * Pipeline: forge request → build tool → run tests → judge review → register.
+ *
+ * Supports two creation modes:
+ * - **Compose**: chains existing tools via {@link ComposableToolBuilder} (safe by construction).
+ * - **Sandbox**: runs agent-written code via {@link SandboxedToolForge} (judge-gated).
+ *
+ * @example
+ * ```ts
+ * const engine = new EmergentCapabilityEngine({
+ *   config: { ...DEFAULT_EMERGENT_CONFIG, enabled: true },
+ *   composableBuilder,
+ *   sandboxForge,
+ *   judge,
+ *   registry,
+ * });
+ *
+ * const result = await engine.forge(request, { agentId: 'gmi-1', sessionId: 'sess-1' });
+ * if (result.success) {
+ *   console.log('Registered tool:', result.toolId);
+ * }
+ * ```
+ */
+export declare class EmergentCapabilityEngine {
+    /** Injected dependencies. */
+    private readonly config;
+    private readonly composableBuilder;
+    private readonly sandboxForge;
+    private readonly judge;
+    private readonly registry;
+    private readonly onToolForged?;
+    private readonly onToolPromoted?;
+    /** Internal index for fast session/agent → tool lookups. */
+    private readonly index;
+    /**
+     * Create a new EmergentCapabilityEngine.
+     *
+     * @param deps - All collaborator dependencies. See {@link EmergentCapabilityEngineDeps}.
+     */
+    constructor(deps: EmergentCapabilityEngineDeps);
+    /**
+     * Forge a new tool from a request.
+     *
+     * Runs test cases, submits the candidate to the LLM judge, and registers the
+     * tool at the `'session'` tier if approved. Returns a {@link ForgeResult} with
+     * the tool ID on success, or an error / rejection verdict on failure.
+     *
+     * Pipeline:
+     * 1. Generate unique tool ID.
+     * 2. Build or validate implementation (compose vs. sandbox).
+     * 3. Execute all declared test cases and collect results.
+     * 4. Submit candidate to the judge for creation review.
+     * 5. If approved: create {@link EmergentTool}, register at session tier, index.
+     * 6. If rejected: return failure with the judge's reasoning.
+     *
+     * @param request - The forge request describing the desired tool.
+     * @param context - Caller context containing the agent and session IDs.
+     * @returns A {@link ForgeResult} indicating success or failure.
+     */
+    forge(request: ForgeToolRequest, context: {
+        agentId: string;
+        sessionId: string;
+    }): Promise<ForgeResult>;
+    /**
+     * Check if a tool is eligible for promotion and auto-promote if the threshold
+     * is met.
+     *
+     * A tool qualifies for promotion when:
+     * 1. It is at the `'session'` tier.
+     * 2. Its usage stats meet {@link EmergentConfig.promotionThreshold}:
+     *    - `totalUses >= threshold.uses`
+     *    - `confidenceScore >= threshold.confidence`
+     *
+     * When eligible, the engine submits the tool to the judge's promotion panel.
+     * If both reviewers approve, the tool is promoted to `'agent'` tier.
+     *
+     * @param toolId - The ID of the tool to check.
+     * @returns A {@link PromotionResult} if promotion was attempted, or `null` if
+     *   the tool is not eligible or does not exist.
+     */
+    checkPromotion(toolId: string): Promise<PromotionResult | null>;
+    /**
+     * Get all session-scoped tools for a given session ID.
+     *
+     * @param sessionId - The session identifier.
+     * @returns An array of {@link EmergentTool} objects belonging to the session.
+     */
+    getSessionTools(sessionId: string): EmergentTool[];
+    /**
+     * Get all agent-tier tools for a given agent ID.
+     *
+     * @param agentId - The agent identifier.
+     * @returns An array of {@link EmergentTool} objects created by the agent.
+     */
+    getAgentTools(agentId: string): EmergentTool[];
+    /**
+     * Clean up all session tools for a given session.
+     *
+     * Delegates to the registry's {@link EmergentToolRegistry.cleanupSession}
+     * method and clears the local session index.
+     *
+     * @param sessionId - The session identifier to clean up.
+     */
+    cleanupSession(sessionId: string): EmergentTool[];
+    /**
+     * Create an executable ITool wrapper for a forged emergent tool.
+     *
+     * The wrapper performs runtime output validation, usage tracking, and
+     * promotion checks after each successful execution.
+     */
+    createExecutableTool(tool: EmergentTool): ITool<Record<string, unknown>, unknown>;
+    /**
+     * Add a tool ID to the session and agent indexes for fast future lookup.
+     *
+     * @param toolId - The tool ID to index.
+     * @param agentId - The agent that created the tool.
+     * @param sessionId - The session in which the tool was created.
+     */
+    private indexTool;
+    private removeIndexedTool;
+    private buildSandboxExecutable;
+}
+//# sourceMappingURL=EmergentCapabilityEngine.d.ts.map

package/dist/emergent/EmergentCapabilityEngine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EmergentCapabilityEngine.d.ts","sourceRoot":"","sources":["../../src/emergent/EmergentCapabilityEngine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,gBAAgB,EAChB,WAAW,EACX,eAAe,EACf,YAAY,EAEb,MAAM,YAAY,CAAC;AAEpB,OAAO,KAAK,EACV,KAAK,EAGN,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACnE,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAMjE;;;;;GAKG;AACH,MAAM,WAAW,4BAA4B;IAC3C,kDAAkD;IAClD,MAAM,EAAE,cAAc,CAAC;IAEvB,8DAA8D;IAC9D,iBAAiB,EAAE,qBAAqB,CAAC;IAEzC,kEAAkE;IAClE,YAAY,EAAE,kBAAkB,CAAC;IAEjC,iEAAiE;IACjE,KAAK,EAAE,aAAa,CAAC;IAErB,+DAA+D;IAC/D,QAAQ,EAAE,oBAAoB,CAAC;IAE/B,0EAA0E;IAC1E,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,YAAY,EAAE,UAAU,EAAE,KAAK,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAExE,0EAA0E;IAC1E,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACxD;AAsBD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,wBAAwB;IACnC,6BAA6B;IAC7B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiB;IACxC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAwB;IAC1D,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAqB;IAClD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgB;IACtC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAuB;IAChD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,CAA2D;IACzF,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAwC;IAExE,4DAA4D;IAC5D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAGpB;IAEF;;;;OAIG;gBACS,IAAI,EAAE,4BAA4B;IAc9C;;;;;;;;;;;;;;;;;;OAkBG;IACG,KAAK,CACT,OAAO,EAAE,gBAAgB,EACzB,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,GAC9C,OAAO,CAAC,WAAW,CAAC;IA+KvB;;;;;;;;;;;;;;;;OAgBG;IACG,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;IAkDrE;;;;;OAKG;IACH,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,YAAY,EAAE;IAoBlD;;;;;OAKG;IACH,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,EAAE;IAQ9C;;;;;;;OAOG;IACH,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,YAAY,EAAE;IAOjD;;;;;OAKG;IACH,oBAAoB,CAAC,IAAI,EAAE,YAAY,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC;IAsEjF;;;;;;OAMG;IACH,OAAO,CAAC,SAAS;IAkBjB,OAAO,CAAC,iBAAiB;IASzB,OAAO,CAAC,sBAAsB;CAkC/B"}