@animus-labs/cortex 0.2.0

package/dist/tools/shared/safe-env.js

@@ -0,0 +1,70 @@
+/**
+ * Shared environment sanitization for child processes.
+ *
+ * Used by both the Bash tool (safety.ts) and MCP client (mcp-client.ts)
+ * to strip dangerous environment variables before spawning subprocesses.
+ */
+// ---------------------------------------------------------------------------
+// Blocked variables
+// ---------------------------------------------------------------------------
+const BLOCKED_ENV_PREFIXES = ['LD_', 'DYLD_', 'BASH_FUNC_'];
+const BLOCKED_ENV_VARS = new Set([
+    // Runtime loaders
+    'NODE_OPTIONS', 'NODE_PATH',
+    'PYTHONPATH', 'PYTHONHOME',
+    'PERL5LIB', 'PERL5OPT',
+    'RUBYLIB', 'RUBYOPT',
+    // Shell startup injection
+    'BASH_ENV', 'ENV', 'SHELLOPTS', 'PS4', 'IFS', 'PROMPT_COMMAND', 'ZDOTDIR',
+    // Git execution
+    'GIT_EXTERNAL_DIFF', 'GIT_EXEC_PATH', 'GIT_SSH_COMMAND',
+    // Security-sensitive
+    'SSLKEYLOGFILE', 'GCONV_PATH', 'OPENSSL_CONF', 'CURL_HOME', 'WGETRC',
+]);
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Build a safe environment for child processes by stripping dangerous variables.
+ *
+ * @param parentEnv - The source environment (typically process.env or a consumer-supplied map)
+ * @param marker - Optional context marker added as CORTEX_SHELL. Pass undefined to skip.
+ * @param overrides - Optional key-value pairs merged ON TOP of the sanitized env, bypassing
+ *   the blocklist. Used for consumer-set variables that must propagate (e.g., macOS dock
+ *   icon suppression vars like DYLD_INSERT_LIBRARIES).
+ * @returns A new object with dangerous variables removed and overrides applied
+ */
+export function buildSafeEnv(parentEnv, marker, overrides) {
+    const env = {};
+    for (const [key, value] of Object.entries(parentEnv)) {
+        if (value === undefined)
+            continue;
+        // Check exact match
+        if (BLOCKED_ENV_VARS.has(key))
+            continue;
+        // Check prefix match
+        let blocked = false;
+        for (const prefix of BLOCKED_ENV_PREFIXES) {
+            if (key.startsWith(prefix)) {
+                blocked = true;
+                break;
+            }
+        }
+        if (blocked)
+            continue;
+        env[key] = value;
+    }
+    if (marker !== undefined) {
+        env['CORTEX_SHELL'] = marker;
+    }
+    // Merge overrides ON TOP of the sanitized env, bypassing the blocklist.
+    // This allows consumers to restore specific blocked variables (e.g.,
+    // DYLD_INSERT_LIBRARIES for macOS dock icon suppression).
+    if (overrides) {
+        for (const [key, value] of Object.entries(overrides)) {
+            env[key] = value;
+        }
+    }
+    return env;
+}
+//# sourceMappingURL=safe-env.js.map

package/dist/tools/shared/safe-env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-env.js","sourceRoot":"","sources":["../../../src/tools/shared/safe-env.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,8EAA8E;AAC9E,oBAAoB;AACpB,8EAA8E;AAE9E,MAAM,oBAAoB,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC;AAE5D,MAAM,gBAAgB,GAAG,IAAI,GAAG,CAAC;IAC/B,kBAAkB;IAClB,cAAc,EAAE,WAAW;IAC3B,YAAY,EAAE,YAAY;IAC1B,UAAU,EAAE,UAAU;IACtB,SAAS,EAAE,SAAS;IACpB,0BAA0B;IAC1B,UAAU,EAAE,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,KAAK,EAAE,gBAAgB,EAAE,SAAS;IACzE,gBAAgB;IAChB,mBAAmB,EAAE,eAAe,EAAE,iBAAiB;IACvD,qBAAqB;IACrB,eAAe,EAAE,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,QAAQ;CACrE,CAAC,CAAC;AAEH,8EAA8E;AAC9E,aAAa;AACb,8EAA8E;AAE9E;;;;;;;;;GASG;AACH,MAAM,UAAU,YAAY,CAC1B,SAAqD,EACrD,MAA2B,EAC3B,SAA8C;IAE9C,MAAM,GAAG,GAA2B,EAAE,CAAC;IAEvC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;QACrD,IAAI,KAAK,KAAK,SAAS;YAAE,SAAS;QAElC,oBAAoB;QACpB,IAAI,gBAAgB,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,SAAS;QAExC,qBAAqB;QACrB,IAAI,OAAO,GAAG,KAAK,CAAC;QACpB,KAAK,MAAM,MAAM,IAAI,oBAAoB,EAAE,CAAC;YAC1C,IAAI,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;gBAC3B,OAAO,GAAG,IAAI,CAAC;gBACf,MAAM;YACR,CAAC;QACH,CAAC;QACD,IAAI,OAAO;YAAE,SAAS;QAEtB,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IACnB,CAAC;IAED,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,GAAG,CAAC,cAAc,CAAC,GAAG,MAAM,CAAC;IAC/B,CAAC;IAED,wEAAwE;IACxE,qEAAqE;IACrE,0DAA0D;IAC1D,IAAI,SAAS,EAAE,CAAC;QACd,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;YACrD,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QACnB,CAAC;IACH,CAAC;IAED,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/tools/sub-agent.d.ts

@@ -0,0 +1,91 @@
+/**
+ * SubAgent tool: spawn independent cortex-based sub-agents for delegated work.
+ *
+ * Supports foreground (blocking) and background (async) execution modes.
+ * Each sub-agent is an independent CortexAgent with its own message array
+ * and empty context slots.
+ *
+ * The SubAgent tool is ALWAYS excluded from child agents to prevent
+ * recursive spawning.
+ *
+ * References:
+ *   - docs/cortex/tools/sub-agent.md
+ *   - docs/cortex/plans/phase-4-sub-agents-and-skills.md
+ */
+import { Type, type Static } from 'typebox';
+export declare const SubAgentParams: Type.TObject<{
+    instructions: Type.TString;
+    tools: Type.TOptional<Type.TArray<Type.TString>>;
+    systemPrompt: Type.TOptional<Type.TString>;
+    maxTurns: Type.TOptional<Type.TNumber>;
+    maxCost: Type.TOptional<Type.TNumber>;
+    background: Type.TOptional<Type.TBoolean>;
+}>;
+export type SubAgentParamsType = Static<typeof SubAgentParams>;
+export interface SubAgentDetails {
+    taskId: string;
+    background: boolean;
+    status: string;
+    durationMs: number | null;
+    turns: number | null;
+    cost: number | null;
+    /** Model ID used by the sub-agent (inherited from parent). */
+    modelId?: string;
+}
+/**
+ * Configuration passed to the SubAgent tool factory.
+ * The CortexAgent provides all of these at tool registration time.
+ */
+export interface SubAgentToolConfig {
+    /**
+     * Spawn a sub-agent and run it. Returns the result when complete.
+     * The factory function handles CortexAgent creation, budget guard
+     * inheritance, tool filtering, and lifecycle management.
+     */
+    spawnSubAgent: (params: SubAgentParamsType) => Promise<{
+        taskId: string;
+        output: string;
+        status: string;
+        usage: {
+            turns: number;
+            cost: number;
+            durationMs: number;
+        };
+    }>;
+    /**
+     * Spawn a background sub-agent. Returns the task ID immediately.
+     */
+    spawnBackgroundSubAgent: (params: SubAgentParamsType) => Promise<{
+        taskId: string;
+    }>;
+    /**
+     * Check if another sub-agent can be spawned.
+     */
+    canSpawn: () => boolean;
+    /**
+     * Get concurrency info for error messages.
+     */
+    getConcurrencyInfo: () => {
+        active: number;
+        limit: number;
+    };
+    /**
+     * Get the model ID for the child agent.
+     * Child agents inherit the parent's primary model.
+     */
+    getModelId: () => string;
+}
+export declare const SUB_AGENT_TOOL_NAME = "SubAgent";
+/**
+ * Create the SubAgent tool.
+ *
+ * Returns a Cortex-native tool. CortexAgent adapts it to pi-agent-core's
+ * execute signature when synchronizing the tool inventory.
+ */
+export declare function createSubAgentTool(config: SubAgentToolConfig): {
+    name: string;
+    description: string;
+    parameters: typeof SubAgentParams;
+    execute: (args: unknown) => Promise<unknown>;
+};
+//# sourceMappingURL=sub-agent.d.ts.map

package/dist/tools/sub-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sub-agent.d.ts","sourceRoot":"","sources":["../../src/tools/sub-agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,IAAI,EAAE,KAAK,MAAM,EAAE,MAAM,SAAS,CAAC;AAM5C,eAAO,MAAM,cAAc;;;;;;;EAmBzB,CAAC;AAEH,MAAM,MAAM,kBAAkB,GAAG,MAAM,CAAC,OAAO,cAAc,CAAC,CAAC;AAM/D,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,OAAO,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,8DAA8D;IAC9D,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAMD;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,aAAa,EAAE,CAAC,MAAM,EAAE,kBAAkB,KAAK,OAAO,CAAC;QACrD,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,EAAE,MAAM,CAAC;QACf,KAAK,EAAE;YAAE,KAAK,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAC;YAAC,UAAU,EAAE,MAAM,CAAA;SAAE,CAAC;KAC5D,CAAC,CAAC;IAEH;;OAEG;IACH,uBAAuB,EAAE,CAAC,MAAM,EAAE,kBAAkB,KAAK,OAAO,CAAC;QAC/D,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC,CAAC;IAEH;;OAEG;IACH,QAAQ,EAAE,MAAM,OAAO,CAAC;IAExB;;OAEG;IACH,kBAAkB,EAAE,MAAM;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAE5D;;;OAGG;IACH,UAAU,EAAE,MAAM,MAAM,CAAC;CAC1B;AAMD,eAAO,MAAM,mBAAmB,aAAa,CAAC;AAM9C;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,kBAAkB,GAAG;IAC9D,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,OAAO,cAAc,CAAC;IAClC,OAAO,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAC9C,CA6CA"}

package/dist/tools/sub-agent.js

@@ -0,0 +1,89 @@
+/**
+ * SubAgent tool: spawn independent cortex-based sub-agents for delegated work.
+ *
+ * Supports foreground (blocking) and background (async) execution modes.
+ * Each sub-agent is an independent CortexAgent with its own message array
+ * and empty context slots.
+ *
+ * The SubAgent tool is ALWAYS excluded from child agents to prevent
+ * recursive spawning.
+ *
+ * References:
+ *   - docs/cortex/tools/sub-agent.md
+ *   - docs/cortex/plans/phase-4-sub-agents-and-skills.md
+ */
+import { Type } from 'typebox';
+// ---------------------------------------------------------------------------
+// Schema
+// ---------------------------------------------------------------------------
+export const SubAgentParams = Type.Object({
+    instructions: Type.String({
+        description: 'What the sub-agent should do. This becomes the sub-agent\'s initial prompt.',
+    }),
+    tools: Type.Optional(Type.Array(Type.String(), {
+        description: 'Tool names to make available. Default: inherits parent\'s registered tools.',
+    })),
+    systemPrompt: Type.Optional(Type.String({
+        description: 'Custom system prompt. Default: inherits parent\'s full system prompt.',
+    })),
+    maxTurns: Type.Optional(Type.Number({
+        description: 'Maximum LLM turns. Default: inherits parent\'s budget guard config.',
+    })),
+    maxCost: Type.Optional(Type.Number({
+        description: 'Maximum cost in USD. Default: inherits parent\'s budget guard config.',
+    })),
+    background: Type.Optional(Type.Boolean({
+        description: 'Run asynchronously. Default: false (blocks until complete).',
+    })),
+});
+// ---------------------------------------------------------------------------
+// Tool name constant
+// ---------------------------------------------------------------------------
+export const SUB_AGENT_TOOL_NAME = 'SubAgent';
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+/**
+ * Create the SubAgent tool.
+ *
+ * Returns a Cortex-native tool. CortexAgent adapts it to pi-agent-core's
+ * execute signature when synchronizing the tool inventory.
+ */
+export function createSubAgentTool(config) {
+    return {
+        name: SUB_AGENT_TOOL_NAME,
+        description: `Spawn a sub-agent to handle a delegated task independently. Use for tasks that are complex, long-running, or can proceed in parallel with your main work.
+
+Foreground mode (default): Blocks until the sub-agent completes and returns its result directly. Use for quick, focused tasks where you need the result to continue.
+
+Background mode (background: true): Returns a task ID immediately. The sub-agent runs independently. You will be notified when it completes. Use for long-running research, analysis, or multi-step work.
+
+Sub-agents are independent: they have their own conversation, do not share your context, and cannot spawn further sub-agents. Give them clear, self-contained instructions.`,
+        parameters: SubAgentParams,
+        execute: async (args) => {
+            const params = args;
+            // Check concurrency limit
+            if (!config.canSpawn()) {
+                const info = config.getConcurrencyInfo();
+                return `Cannot spawn sub-agent: concurrency limit reached (${info.active}/${info.limit} active). Wait for a running sub-agent to complete or cancel one to free a slot.`;
+            }
+            // Background mode: spawn and return immediately
+            if (params.background) {
+                const { taskId } = await config.spawnBackgroundSubAgent(params);
+                return `Sub-agent spawned in background. Task ID: ${taskId}\nYou will be notified when it completes. Continue with other work.`;
+            }
+            // Foreground mode: block until complete
+            const result = await config.spawnSubAgent(params);
+            // Format result for the parent agent
+            const statusLine = result.status === 'completed'
+                ? 'Sub-agent completed successfully.'
+                : `Sub-agent finished with status: ${result.status}`;
+            const usageLine = `(${result.usage.turns} turns, $${result.usage.cost.toFixed(4)}, ${(result.usage.durationMs / 1000).toFixed(1)}s)`;
+            if (result.output) {
+                return `${statusLine} ${usageLine}\n\n${result.output}`;
+            }
+            return `${statusLine} ${usageLine}\n\nNo output was produced.`;
+        },
+    };
+}
+//# sourceMappingURL=sub-agent.js.map

package/dist/tools/sub-agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sub-agent.js","sourceRoot":"","sources":["../../src/tools/sub-agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,IAAI,EAAe,MAAM,SAAS,CAAC;AAE5C,8EAA8E;AAC9E,SAAS;AACT,8EAA8E;AAE9E,MAAM,CAAC,MAAM,cAAc,GAAG,IAAI,CAAC,MAAM,CAAC;IACxC,YAAY,EAAE,IAAI,CAAC,MAAM,CAAC;QACxB,WAAW,EAAE,6EAA6E;KAC3F,CAAC;IACF,KAAK,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE;QAC7C,WAAW,EAAE,6EAA6E;KAC3F,CAAC,CAAC;IACH,YAAY,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC;QACtC,WAAW,EAAE,uEAAuE;KACrF,CAAC,CAAC;IACH,QAAQ,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC;QAClC,WAAW,EAAE,qEAAqE;KACnF,CAAC,CAAC;IACH,OAAO,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC;QACjC,WAAW,EAAE,uEAAuE;KACrF,CAAC,CAAC;IACH,UAAU,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC;QACrC,WAAW,EAAE,6DAA6D;KAC3E,CAAC,CAAC;CACJ,CAAC,CAAC;AAgEH,8EAA8E;AAC9E,qBAAqB;AACrB,8EAA8E;AAE9E,MAAM,CAAC,MAAM,mBAAmB,GAAG,UAAU,CAAC;AAE9C,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAA0B;IAM3D,OAAO;QACL,IAAI,EAAE,mBAAmB;QACzB,WAAW,EAAE;;;;;;4KAM2J;QAExK,UAAU,EAAE,cAAc;QAE1B,OAAO,EAAE,KAAK,EAAE,IAAa,EAAoB,EAAE;YACjD,MAAM,MAAM,GAAG,IAA0B,CAAC;YAE1C,0BAA0B;YAC1B,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,EAAE,CAAC;gBACvB,MAAM,IAAI,GAAG,MAAM,CAAC,kBAAkB,EAAE,CAAC;gBACzC,OAAO,sDAAsD,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,KAAK,kFAAkF,CAAC;YAC3K,CAAC;YAED,gDAAgD;YAChD,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;gBACtB,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,MAAM,CAAC,uBAAuB,CAAC,MAAM,CAAC,CAAC;gBAChE,OAAO,6CAA6C,MAAM,qEAAqE,CAAC;YAClI,CAAC;YAED,wCAAwC;YACxC,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC;YAElD,qCAAqC;YACrC,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,KAAK,WAAW;gBAC9C,CAAC,CAAC,mCAAmC;gBACrC,CAAC,CAAC,mCAAmC,MAAM,CAAC,MAAM,EAAE,CAAC;YAEvD,MAAM,SAAS,GAAG,IAAI,MAAM,CAAC,KAAK,CAAC,KAAK,YAAY,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC;YAErI,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;gBAClB,OAAO,GAAG,UAAU,IAAI,SAAS,OAAO,MAAM,CAAC,MAAM,EAAE,CAAC;YAC1D,CAAC;YAED,OAAO,GAAG,UAAU,IAAI,SAAS,6BAA6B,CAAC;QACjE,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/tools/task-output.d.ts

@@ -0,0 +1,38 @@
+/**
+ * TaskOutput tool: companion tool for polling backgrounded processes.
+ *
+ * Auto-registered alongside the Bash tool. Provides three actions:
+ * - poll: get latest output and status
+ * - send: send input to process stdin
+ * - kill: send a signal to the process
+ *
+ * Reference: docs/cortex/tools/bash.md (Background Execution)
+ */
+import { Type, type Static } from 'typebox';
+import type { ToolContentDetails } from '../types.js';
+import type { CortexToolRuntime } from './runtime.js';
+export declare const TaskOutputParams: Type.TObject<{
+    task_id: Type.TString;
+    action: Type.TUnion<[Type.TLiteral<"poll">, Type.TLiteral<"send">, Type.TLiteral<"kill">]>;
+    input: Type.TOptional<Type.TString>;
+    signal: Type.TOptional<Type.TString>;
+}>;
+export type TaskOutputParamsType = Static<typeof TaskOutputParams>;
+export interface TaskOutputDetails {
+    taskId: string;
+    action: string;
+    status: 'running' | 'completed' | 'failed' | 'not_found';
+    exitCode: number | null;
+    stdout: string;
+    stderr: string;
+}
+export interface TaskOutputToolConfig {
+    runtime?: CortexToolRuntime | undefined;
+}
+export declare function createTaskOutputTool(config?: TaskOutputToolConfig): {
+    name: string;
+    description: string;
+    parameters: typeof TaskOutputParams;
+    execute: (params: TaskOutputParamsType) => Promise<ToolContentDetails<TaskOutputDetails>>;
+};
+//# sourceMappingURL=task-output.d.ts.map

package/dist/tools/task-output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-output.d.ts","sourceRoot":"","sources":["../../src/tools/task-output.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,IAAI,EAAE,KAAK,MAAM,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAUtD,eAAO,MAAM,gBAAgB;;;;;EAa3B,CAAC;AAEH,MAAM,MAAM,oBAAoB,GAAG,MAAM,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAMnE,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,SAAS,GAAG,WAAW,GAAG,QAAQ,GAAG,WAAW,CAAC;IACzD,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAMD,MAAM,WAAW,oBAAoB;IACnC,OAAO,CAAC,EAAE,iBAAiB,GAAG,SAAS,CAAC;CACzC;AAED,wBAAgB,oBAAoB,CAAC,MAAM,CAAC,EAAE,oBAAoB,GAAG;IACnE,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,OAAO,gBAAgB,CAAC;IACpC,OAAO,EAAE,CAAC,MAAM,EAAE,oBAAoB,KAAK,OAAO,CAAC,kBAAkB,CAAC,iBAAiB,CAAC,CAAC,CAAC;CAC3F,CAyKA"}

package/dist/tools/task-output.js

@@ -0,0 +1,186 @@
+/**
+ * TaskOutput tool: companion tool for polling backgrounded processes.
+ *
+ * Auto-registered alongside the Bash tool. Provides three actions:
+ * - poll: get latest output and status
+ * - send: send input to process stdin
+ * - kill: send a signal to the process
+ *
+ * Reference: docs/cortex/tools/bash.md (Background Execution)
+ */
+import { Type } from 'typebox';
+import { attachRuntimeAwareTool, globalBackgroundTaskStore, } from './runtime.js';
+// ---------------------------------------------------------------------------
+// Schema
+// ---------------------------------------------------------------------------
+export const TaskOutputParams = Type.Object({
+    task_id: Type.String({ description: 'The task ID returned by a backgrounded Bash command' }),
+    action: Type.Union([
+        Type.Literal('poll'),
+        Type.Literal('send'),
+        Type.Literal('kill'),
+    ], { description: 'Action to perform: poll (get output), send (send input), or kill (terminate)' }),
+    input: Type.Optional(Type.String({ description: 'Input to send to the process stdin (only for "send" action)' })),
+    signal: Type.Optional(Type.String({ description: 'Signal to send (only for "kill" action). Default: SIGTERM. Options: SIGINT, SIGTERM, SIGKILL' })),
+});
+export function createTaskOutputTool(config) {
+    const backgroundTasks = config?.runtime?.backgroundTasks ?? globalBackgroundTaskStore;
+    const tool = {
+        name: 'TaskOutput',
+        description: 'Poll, send input to, or kill a backgrounded process.',
+        parameters: TaskOutputParams,
+        async execute(params) {
+            const { task_id: taskId, action } = params;
+            const task = backgroundTasks.get(taskId);
+            if (!task) {
+                return {
+                    content: [{ type: 'text', text: `Task not found: ${taskId}` }],
+                    details: {
+                        taskId,
+                        action,
+                        status: 'not_found',
+                        exitCode: null,
+                        stdout: '',
+                        stderr: '',
+                    },
+                };
+            }
+            switch (action) {
+                case 'poll': {
+                    const status = task.completed
+                        ? (task.exitCode === 0 ? 'completed' : 'failed')
+                        : 'running';
+                    let text = `Status: ${status}`;
+                    if (task.completed && task.exitCode !== null) {
+                        text += ` (exit code: ${task.exitCode})`;
+                    }
+                    if (task.stdout) {
+                        const output = task.stdout.length > 30000
+                            ? task.stdout.slice(-30000)
+                            : task.stdout;
+                        text += `\n\nOutput:\n${output}`;
+                    }
+                    if (task.stderr) {
+                        text += `\n\nStderr:\n${task.stderr}`;
+                    }
+                    return {
+                        content: [{ type: 'text', text }],
+                        details: {
+                            taskId,
+                            action,
+                            status: status,
+                            exitCode: task.exitCode,
+                            stdout: task.stdout,
+                            stderr: task.stderr,
+                        },
+                    };
+                }
+                case 'send': {
+                    if (task.completed) {
+                        return {
+                            content: [{ type: 'text', text: `Task ${taskId} has already completed. Cannot send input.` }],
+                            details: {
+                                taskId,
+                                action,
+                                status: task.exitCode === 0 ? 'completed' : 'failed',
+                                exitCode: task.exitCode,
+                                stdout: task.stdout,
+                                stderr: task.stderr,
+                            },
+                        };
+                    }
+                    const input = params.input ?? '';
+                    try {
+                        task.process.stdin?.write(input + '\n');
+                        return {
+                            content: [{ type: 'text', text: `Sent input to task ${taskId}.` }],
+                            details: {
+                                taskId,
+                                action,
+                                status: 'running',
+                                exitCode: null,
+                                stdout: task.stdout,
+                                stderr: task.stderr,
+                            },
+                        };
+                    }
+                    catch (err) {
+                        const msg = err instanceof Error ? err.message : String(err);
+                        return {
+                            content: [{ type: 'text', text: `Failed to send input to task ${taskId}: ${msg}` }],
+                            details: {
+                                taskId,
+                                action,
+                                status: 'running',
+                                exitCode: null,
+                                stdout: task.stdout,
+                                stderr: task.stderr,
+                            },
+                        };
+                    }
+                }
+                case 'kill': {
+                    if (task.completed) {
+                        return {
+                            content: [{ type: 'text', text: `Task ${taskId} has already completed.` }],
+                            details: {
+                                taskId,
+                                action,
+                                status: task.exitCode === 0 ? 'completed' : 'failed',
+                                exitCode: task.exitCode,
+                                stdout: task.stdout,
+                                stderr: task.stderr,
+                            },
+                        };
+                    }
+                    const signal = (params.signal ?? 'SIGTERM');
+                    try {
+                        task.process.kill(signal);
+                        return {
+                            content: [{ type: 'text', text: `Sent ${signal} to task ${taskId}.` }],
+                            details: {
+                                taskId,
+                                action,
+                                status: 'running',
+                                exitCode: null,
+                                stdout: task.stdout,
+                                stderr: task.stderr,
+                            },
+                        };
+                    }
+                    catch (err) {
+                        const msg = err instanceof Error ? err.message : String(err);
+                        return {
+                            content: [{ type: 'text', text: `Failed to kill task ${taskId}: ${msg}` }],
+                            details: {
+                                taskId,
+                                action,
+                                status: 'running',
+                                exitCode: null,
+                                stdout: task.stdout,
+                                stderr: task.stderr,
+                            },
+                        };
+                    }
+                }
+                default:
+                    return {
+                        content: [{ type: 'text', text: `Unknown action: ${action}` }],
+                        details: {
+                            taskId,
+                            action,
+                            status: 'not_found',
+                            exitCode: null,
+                            stdout: '',
+                            stderr: '',
+                        },
+                    };
+            }
+        },
+    };
+    return attachRuntimeAwareTool(tool, {
+        toolKind: 'TaskOutput',
+        cloneForRuntime: (runtime) => createTaskOutputTool({ runtime }),
+    });
+}
+//# sourceMappingURL=task-output.js.map

package/dist/tools/task-output.js.map

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

package/dist/tools/tool-search/index.d.ts

@@ -0,0 +1,40 @@
+/**
+ * ToolSearch tool: load full tool schemas on demand.
+ *
+ * Auto-registered when `deferredTools.enabled` is true. The model uses this
+ * tool to discover and load tools that appear by name in the
+ * `_available_tools` slot but whose schemas are not yet in the agent's
+ * tools array.
+ *
+ * Once a tool is loaded, it persists in the agent's tools array for the
+ * rest of the session and can be called normally.
+ */
+import { Type, type Static } from 'typebox';
+import type { CortexTool } from '../../tool-contract.js';
+import type { ToolContentDetails } from '../../types.js';
+import type { DeferredToolRegistry } from './registry.js';
+export declare const TOOL_SEARCH_TOOL_NAME = "ToolSearch";
+export declare const ToolSearchParams: Type.TObject<{
+    query: Type.TString;
+    max_results: Type.TOptional<Type.TNumber>;
+}>;
+export type ToolSearchParamsType = Static<typeof ToolSearchParams>;
+export interface ToolSearchDetails {
+    query: string;
+    loaded: string[];
+    alreadyAvailable: string[];
+    notFound: string[];
+    totalDeferred: number;
+}
+export interface ToolSearchToolConfig {
+    /** The deferred tool registry shared with CortexAgent. */
+    registry: DeferredToolRegistry;
+    /**
+     * Called after the registry is updated. The agent uses this to refresh
+     * its tools array (so the newly discovered tools appear in the next API
+     * call) and update the `_available_tools` slot.
+     */
+    onAfterDiscovery: () => void;
+}
+export declare function createToolSearchTool(config: ToolSearchToolConfig): CortexTool<ToolSearchParamsType, ToolContentDetails<ToolSearchDetails>>;
+//# sourceMappingURL=index.d.ts.map

package/dist/tools/tool-search/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/tools/tool-search/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,IAAI,EAAE,KAAK,MAAM,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACzD,OAAO,KAAK,EAAE,oBAAoB,EAAoB,MAAM,eAAe,CAAC;AAM5E,eAAO,MAAM,qBAAqB,eAAe,CAAC;AAgBlD,eAAO,MAAM,gBAAgB;;;EAQ3B,CAAC;AAEH,MAAM,MAAM,oBAAoB,GAAG,MAAM,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAMnE,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;CACvB;AAMD,MAAM,WAAW,oBAAoB;IACnC,0DAA0D;IAC1D,QAAQ,EAAE,oBAAoB,CAAC;IAC/B;;;;OAIG;IACH,gBAAgB,EAAE,MAAM,IAAI,CAAC;CAC9B;AAED,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,oBAAoB,GAC3B,UAAU,CAAC,oBAAoB,EAAE,kBAAkB,CAAC,iBAAiB,CAAC,CAAC,CA0CzE"}