@framers/agentos 0.1.120 → 0.1.122

package/dist/emergent/CreateWorkflowTool.js

@@ -0,0 +1,307 @@
+/**
+ * @fileoverview CreateWorkflowTool — ITool implementation that enables agents
+ * to compose multi-step tool workflows at runtime and execute them as a unit.
+ *
+ * @module @framers/agentos/emergent/CreateWorkflowTool
+ *
+ * Agents call `create_workflow` to define, run, and list workflows. A workflow
+ * is a named sequence of tool invocations with reference resolution:
+ * - `$input`     — the workflow's input argument
+ * - `$prev`      — the output of the immediately preceding step
+ * - `$steps[N]`  — the output of the Nth step (zero-indexed)
+ *
+ * Constraints:
+ * - Maximum step count is enforced via `config.maxSteps`.
+ * - Only tools from `config.allowedTools` may be used in steps.
+ * - Recursive workflow creation is blocked (`create_workflow` cannot appear in steps).
+ * - Each step execution has a 30-second timeout enforced via `Promise.race`.
+ */
+// ============================================================================
+// TOOL IMPLEMENTATION
+// ============================================================================
+/** Default per-step execution timeout in milliseconds. */
+const STEP_TIMEOUT_MS = 30000;
+/**
+ * ITool implementation enabling agents to compose, execute, and list
+ * multi-step tool workflows at runtime.
+ *
+ * @example
+ * ```ts
+ * const tool = new CreateWorkflowTool({
+ *   config: { maxSteps: 10, allowedTools: ['web_search', 'summarize'] },
+ *   executeTool: (name, args) => orchestrator.execute(name, args),
+ *   listTools: () => orchestrator.listToolNames(),
+ * });
+ *
+ * // Create a workflow
+ * const createResult = await tool.execute({
+ *   action: 'create',
+ *   name: 'search-and-summarize',
+ *   description: 'Search the web and summarize results.',
+ *   steps: [
+ *     { tool: 'web_search', args: { query: '$input' } },
+ *     { tool: 'summarize', args: { text: '$prev' } },
+ *   ],
+ * }, context);
+ * ```
+ */
+export class CreateWorkflowTool {
+    /**
+     * Create a new CreateWorkflowTool.
+     *
+     * @param deps - Injected dependencies including config, tool executor,
+     *   and tool lister.
+     */
+    constructor(deps) {
+        /** @inheritdoc */
+        this.id = 'com.framers.emergent.create-workflow';
+        /** @inheritdoc */
+        this.name = 'create_workflow';
+        /** @inheritdoc */
+        this.displayName = 'Create Workflow';
+        /** @inheritdoc */
+        this.description = 'Create, run, or list multi-step tool workflows. Steps execute sequentially ' +
+            'with reference resolution ($input, $prev, $steps[N]).';
+        /** @inheritdoc */
+        this.category = 'emergent';
+        /** @inheritdoc */
+        this.hasSideEffects = true;
+        /** @inheritdoc */
+        this.inputSchema = {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: ['create', 'run', 'list'],
+                    description: 'The workflow action to perform.',
+                },
+                name: {
+                    type: 'string',
+                    description: 'Workflow name (required for create).',
+                },
+                description: {
+                    type: 'string',
+                    description: 'Workflow description (required for create).',
+                },
+                steps: {
+                    type: 'array',
+                    description: 'Ordered list of workflow steps (required for create).',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            tool: { type: 'string' },
+                            args: { type: 'object' },
+                        },
+                        required: ['tool', 'args'],
+                    },
+                },
+                workflowId: {
+                    type: 'string',
+                    description: 'Workflow ID (required for run).',
+                },
+                input: {
+                    description: 'Input data passed to the workflow when running.',
+                },
+            },
+            required: ['action'],
+        };
+        /** Session-scoped workflow storage. */
+        this.workflows = new Map();
+        /** Monotonic counter for generating workflow IDs. */
+        this.nextId = 1;
+        this.deps = deps;
+    }
+    // --------------------------------------------------------------------------
+    // EXECUTE
+    // --------------------------------------------------------------------------
+    /**
+     * Execute the requested workflow action.
+     *
+     * @param args - Action type and associated parameters.
+     * @param _context - Tool execution context (unused but required by ITool).
+     * @returns A {@link ToolExecutionResult} wrapping the action outcome.
+     */
+    async execute(args, _context) {
+        switch (args.action) {
+            case 'create':
+                return this.handleCreate(args);
+            case 'run':
+                return this.handleRun(args);
+            case 'list':
+                return this.handleList();
+            default:
+                return {
+                    success: false,
+                    error: `Unknown action "${args.action}". Must be one of: create, run, list`,
+                };
+        }
+    }
+    // --------------------------------------------------------------------------
+    // ACTION HANDLERS
+    // --------------------------------------------------------------------------
+    /**
+     * Create and store a new workflow definition.
+     *
+     * Validates:
+     * - Required fields (name, description, steps) are present
+     * - Step count does not exceed maxSteps
+     * - No step references `create_workflow` (prevent recursion)
+     * - All step tools exist in the available tool list
+     */
+    async handleCreate(args) {
+        const { name, description, steps } = args;
+        if (!name || typeof name !== 'string') {
+            return { success: false, error: 'name is required for the create action' };
+        }
+        if (!description || typeof description !== 'string') {
+            return { success: false, error: 'description is required for the create action' };
+        }
+        if (!steps || !Array.isArray(steps) || steps.length === 0) {
+            return { success: false, error: 'steps is required and must be a non-empty array' };
+        }
+        // Check maxSteps
+        if (steps.length > this.deps.config.maxSteps) {
+            return {
+                success: false,
+                error: `Workflow exceeds maxSteps limit (${steps.length} > ${this.deps.config.maxSteps})`,
+            };
+        }
+        // Block recursive workflow creation
+        for (const step of steps) {
+            if (step.tool === 'create_workflow') {
+                return {
+                    success: false,
+                    error: 'Workflows cannot contain create_workflow steps (recursion not allowed)',
+                };
+            }
+        }
+        // Validate all tools exist
+        const availableTools = this.deps.listTools();
+        for (const step of steps) {
+            if (!availableTools.includes(step.tool)) {
+                return {
+                    success: false,
+                    error: `Tool "${step.tool}" referenced in step is not available`,
+                };
+            }
+        }
+        const id = `workflow-${this.nextId++}`;
+        const workflow = {
+            id,
+            name,
+            description,
+            steps,
+            createdAt: new Date().toISOString(),
+            runCount: 0,
+        };
+        this.workflows.set(id, workflow);
+        return {
+            success: true,
+            output: { workflowId: id, name, stepCount: steps.length },
+        };
+    }
+    /**
+     * Run a stored workflow, executing steps sequentially with reference resolution.
+     *
+     * Reference resolution:
+     * - `$input`    — the workflow's input argument
+     * - `$prev`     — the output of the immediately preceding step
+     * - `$steps[N]` — the output of the Nth step (zero-indexed)
+     *
+     * Each step has a 30-second timeout enforced via Promise.race.
+     */
+    async handleRun(args) {
+        const { workflowId, input } = args;
+        if (!workflowId) {
+            return { success: false, error: 'workflowId is required for the run action' };
+        }
+        const workflow = this.workflows.get(workflowId);
+        if (!workflow) {
+            return { success: false, error: `Workflow "${workflowId}" not found` };
+        }
+        const stepResults = [];
+        let prev = undefined;
+        for (let i = 0; i < workflow.steps.length; i++) {
+            const step = workflow.steps[i];
+            // Resolve references in step args
+            const resolvedArgs = this.resolveReferences(step.args, input, prev, stepResults);
+            try {
+                // 30-second timeout per step via Promise.race
+                const result = await Promise.race([
+                    this.deps.executeTool(step.tool, resolvedArgs),
+                    new Promise((_, reject) => setTimeout(() => reject(new Error(`Step ${i} ("${step.tool}") timed out after ${STEP_TIMEOUT_MS}ms`)), STEP_TIMEOUT_MS)),
+                ]);
+                stepResults.push(result);
+                prev = result;
+            }
+            catch (err) {
+                return {
+                    success: false,
+                    error: `Workflow failed at step ${i} ("${step.tool}"): ${err.message ?? String(err)}`,
+                    output: { completedSteps: i, stepResults },
+                };
+            }
+        }
+        workflow.runCount++;
+        return {
+            success: true,
+            output: {
+                workflowId: workflow.id,
+                runCount: workflow.runCount,
+                stepResults,
+                finalOutput: prev,
+            },
+        };
+    }
+    /**
+     * List all stored workflows.
+     */
+    async handleList() {
+        const workflows = Array.from(this.workflows.values()).map((w) => ({
+            id: w.id,
+            name: w.name,
+            description: w.description,
+            stepCount: w.steps.length,
+            runCount: w.runCount,
+            createdAt: w.createdAt,
+        }));
+        return { success: true, output: { workflows } };
+    }
+    // --------------------------------------------------------------------------
+    // REFERENCE RESOLUTION
+    // --------------------------------------------------------------------------
+    /**
+     * Resolve `$input`, `$prev`, and `$steps[N]` references in step arguments.
+     *
+     * Uses JSON.stringify → string replacement → JSON.parse cycle for simple
+     * reference resolution. References appearing as standalone string values
+     * are replaced with the actual object; references embedded in larger strings
+     * are serialized inline.
+     *
+     * @param args - The step arguments potentially containing references.
+     * @param input - The workflow input value.
+     * @param prev - The output of the previous step.
+     * @param stepResults - Array of all completed step outputs.
+     * @returns Resolved arguments with references replaced by actual values.
+     */
+    resolveReferences(args, input, prev, stepResults) {
+        const serialized = JSON.stringify(args);
+        // Replace $steps[N] references first (more specific pattern)
+        let resolved = serialized.replace(/"\$steps\[(\d+)\]"/g, (_match, idx) => {
+            const index = parseInt(idx, 10);
+            return JSON.stringify(stepResults[index] ?? null);
+        });
+        // Replace $input references
+        resolved = resolved.replace(/"\$input"/g, JSON.stringify(input ?? null));
+        // Replace $prev references
+        resolved = resolved.replace(/"\$prev"/g, JSON.stringify(prev ?? null));
+        try {
+            return JSON.parse(resolved);
+        }
+        catch {
+            // If parsing fails (unlikely), return original args
+            return args;
+        }
+    }
+}
+//# sourceMappingURL=CreateWorkflowTool.js.map

package/dist/emergent/CreateWorkflowTool.js.map

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

package/dist/emergent/ManageSkillsTool.d.ts

@@ -0,0 +1,154 @@
+/**
+ * @fileoverview ManageSkillsTool — ITool implementation that enables agents to
+ * dynamically enable, disable, and search for skills at runtime.
+ *
+ * @module @framers/agentos/emergent/ManageSkillsTool
+ *
+ * Agents call `manage_skills` to self-modify their active skill set. The tool
+ * enforces an allowlist-based permission model:
+ * - Wildcard (`'*'`) allows all skills unconditionally.
+ * - Exact skill ID matches are always permitted.
+ * - Category-based allowlist entries (`'category:X'`) permit any skill in that category.
+ * - Same-category expansion: if any skill in category X is already active, other
+ *   skills in X are also permitted without explicit allowlist entry.
+ * - New categories may require approval when `requireApprovalForNewCategories` is set.
+ *
+ * Locked skills cannot be disabled.
+ */
+import type { ITool, ToolExecutionResult, ToolExecutionContext, JSONSchemaObject } from '../core/tools/ITool.js';
+/**
+ * Minimal skill descriptor used for active skill listing and search results.
+ */
+export interface SkillDescriptor {
+    /** Unique skill identifier. */
+    skillId: string;
+    /** Human-readable skill name. */
+    name: string;
+    /** Category the skill belongs to. */
+    category: string;
+}
+/**
+ * Extended skill descriptor returned by search, including a description.
+ */
+export interface SkillSearchResult extends SkillDescriptor {
+    /** Natural language description of the skill's purpose. */
+    description: string;
+}
+/**
+ * Input arguments accepted by the `manage_skills` tool.
+ * Discriminated on the `action` field.
+ */
+export interface ManageSkillsInput extends Record<string, any> {
+    /** The action to perform: enable, disable, search, or list. */
+    action: 'enable' | 'disable' | 'search' | 'list';
+    /** Skill ID to enable or disable (required for enable/disable). */
+    skillId?: string;
+    /** Search query string (required for search). */
+    query?: string;
+}
+/**
+ * Dependencies injected into the {@link ManageSkillsTool} constructor.
+ */
+export interface ManageSkillsDeps {
+    /** Configuration controlling allowlist and approval requirements. */
+    config: {
+        /**
+         * Allowlist of permitted skill IDs or patterns.
+         * - `['*']` → all skills allowed.
+         * - Exact skill IDs are matched literally.
+         * - `'category:X'` → any skill in category X is allowed.
+         */
+        allowlist: string[];
+        /** Whether enabling skills in new categories requires approval. */
+        requireApprovalForNewCategories: boolean;
+    };
+    /** Returns the currently active skills for the agent. */
+    getActiveSkills: () => SkillDescriptor[];
+    /** Returns the list of skill IDs that cannot be disabled. */
+    getLockedSkills: () => string[];
+    /** Load and activate a skill by its ID. Returns the skill descriptor. */
+    loadSkill: (id: string) => Promise<SkillDescriptor>;
+    /** Unload and deactivate a skill by its ID. */
+    unloadSkill: (id: string) => void;
+    /** Search for available skills matching a query string. */
+    searchSkills: (query: string) => SkillSearchResult[];
+}
+/**
+ * ITool implementation enabling agents to dynamically manage their skill set
+ * at runtime, subject to allowlist and lock constraints.
+ *
+ * @example
+ * ```ts
+ * const tool = new ManageSkillsTool({
+ *   config: { allowlist: ['*'], requireApprovalForNewCategories: false },
+ *   getActiveSkills: () => agent.skills,
+ *   getLockedSkills: () => ['core-reasoning'],
+ *   loadSkill: (id) => skillRegistry.load(id),
+ *   unloadSkill: (id) => skillRegistry.unload(id),
+ *   searchSkills: (q) => skillRegistry.search(q),
+ * });
+ * ```
+ */
+export declare class ManageSkillsTool implements ITool<ManageSkillsInput> {
+    /** @inheritdoc */
+    readonly id = "com.framers.emergent.manage-skills";
+    /** @inheritdoc */
+    readonly name = "manage_skills";
+    /** @inheritdoc */
+    readonly displayName = "Manage Skills";
+    /** @inheritdoc */
+    readonly description: string;
+    /** @inheritdoc */
+    readonly category = "emergent";
+    /** @inheritdoc */
+    readonly hasSideEffects = true;
+    /** @inheritdoc */
+    readonly inputSchema: JSONSchemaObject;
+    /** Injected dependencies. */
+    private readonly deps;
+    /**
+     * Create a new ManageSkillsTool.
+     *
+     * @param deps - Injected dependencies including config, skill accessors,
+     *   and loader/unloader functions.
+     */
+    constructor(deps: ManageSkillsDeps);
+    /**
+     * Execute the requested skill management action.
+     *
+     * @param args - Action type and associated parameters.
+     * @param _context - Tool execution context (unused but required by ITool).
+     * @returns A {@link ToolExecutionResult} wrapping the action outcome.
+     */
+    execute(args: ManageSkillsInput, _context: ToolExecutionContext): Promise<ToolExecutionResult>;
+    /**
+     * Enable a skill after checking allowlist permissions.
+     *
+     * Allowlist resolution order:
+     * 1. `['*']` → always allowed
+     * 2. Exact skillId match → allowed
+     * 3. `'category:X'` in allowlist and skill.category === X → allowed
+     * 4. Skill's category already represented in active skills → allowed (same-category expansion)
+     * 5. Otherwise → `requires_approval` if requireApprovalForNewCategories, else `denied`
+     */
+    private handleEnable;
+    /**
+     * Resolve whether a skill is permitted by the allowlist configuration.
+     *
+     * @returns `'allowed'`, `'requires_approval'`, or `'denied'`
+     */
+    private resolvePermission;
+    /**
+     * Disable a skill, rejecting if it is locked.
+     */
+    private handleDisable;
+    /**
+     * Search for available skills by query string.
+     */
+    private handleSearch;
+    /**
+     * List currently active skills.
+     */
+    private handleList;
+}
+//# sourceMappingURL=ManageSkillsTool.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ManageSkillsTool.d.ts","sourceRoot":"","sources":["../../src/emergent/ManageSkillsTool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EACV,KAAK,EACL,mBAAmB,EACnB,oBAAoB,EACpB,gBAAgB,EACjB,MAAM,wBAAwB,CAAC;AAMhC;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,+BAA+B;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,qCAAqC;IACrC,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAkB,SAAQ,eAAe;IACxD,2DAA2D;IAC3D,WAAW,EAAE,MAAM,CAAC;CACrB;AAMD;;;GAGG;AACH,MAAM,WAAW,iBAAkB,SAAQ,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAC5D,+DAA+D;IAC/D,MAAM,EAAE,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,MAAM,CAAC;IACjD,mEAAmE;IACnE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iDAAiD;IACjD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAMD;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,qEAAqE;IACrE,MAAM,EAAE;QACN;;;;;WAKG;QACH,SAAS,EAAE,MAAM,EAAE,CAAC;QACpB,mEAAmE;QACnE,+BAA+B,EAAE,OAAO,CAAC;KAC1C,CAAC;IACF,yDAAyD;IACzD,eAAe,EAAE,MAAM,eAAe,EAAE,CAAC;IACzC,6DAA6D;IAC7D,eAAe,EAAE,MAAM,MAAM,EAAE,CAAC;IAChC,yEAAyE;IACzE,SAAS,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,eAAe,CAAC,CAAC;IACpD,+CAA+C;IAC/C,WAAW,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC,2DAA2D;IAC3D,YAAY,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,iBAAiB,EAAE,CAAC;CACtD;AAMD;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,gBAAiB,YAAW,KAAK,CAAC,iBAAiB,CAAC;IAC/D,kBAAkB;IAClB,QAAQ,CAAC,EAAE,wCAAwC;IAEnD,kBAAkB;IAClB,QAAQ,CAAC,IAAI,mBAAmB;IAEhC,kBAAkB;IAClB,QAAQ,CAAC,WAAW,mBAAmB;IAEvC,kBAAkB;IAClB,QAAQ,CAAC,WAAW,SAE2B;IAE/C,kBAAkB;IAClB,QAAQ,CAAC,QAAQ,cAAc;IAE/B,kBAAkB;IAClB,QAAQ,CAAC,cAAc,QAAQ;IAE/B,kBAAkB;IAClB,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CAkBpC;IAEF,6BAA6B;IAC7B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAmB;IAExC;;;;;OAKG;gBACS,IAAI,EAAE,gBAAgB;IAQlC;;;;;;OAMG;IACG,OAAO,CACX,IAAI,EAAE,iBAAiB,EACvB,QAAQ,EAAE,oBAAoB,GAC7B,OAAO,CAAC,mBAAmB,CAAC;IAsB/B;;;;;;;;;OASG;YACW,YAAY;IAwD1B;;;;OAIG;IACH,OAAO,CAAC,iBAAiB;IA+BzB;;OAEG;YACW,aAAa;IAuB3B;;OAEG;YACW,YAAY;IAe1B;;OAEG;YACW,UAAU;CAQzB"}