@animalabs/agent-framework 0.7.0 → 0.7.3

package/dist/src/framework.js

@@ -11,11 +11,16 @@ import { FeatureSetManager } from './mcpl/feature-set-manager.js';
 import { ScopeManager } from './mcpl/scope-manager.js';
 import { HookOrchestrator } from './mcpl/hook-orchestrator.js';
 import { PushHandler } from './mcpl/push-handler.js';
+import { parseProsePrefix } from './mcpl/prose-grammar.js';
+import { ProseStreamRouter } from './mcpl/prose-stream-router.js';
 import { InferenceRouter } from './mcpl/inference-router.js';
 import { ChannelRegistry } from './mcpl/channel-registry.js';
 import { ConversationRouter } from './mcpl/conversation-router.js';
 import { safeSlice } from './safe-slice.js';
 import { toolResultDataToHistoryString } from './tool-result-history.js';
+import { randomUUID } from 'node:crypto';
+import { PyRunner, buildInjectedTools } from './code-execution/py-runner.js';
+import { buildCodeExecutionToolDefinition, CODE_EXECUTION_TOOL_NAME, } from './code-execution/tool-definition.js';
 import { splitProseSegments } from './prose-segments.js';
 /** Detect a supported image media type from magic bytes (the model API
  *  rejects mislabeled media types, so trust bytes over extensions).
@@ -110,29 +115,9 @@ function extractChannelIdFromToolResult(content) {
  * when picking a turn's frozen speech locus.
  */
 const isAddressedMessage = (tags, _metadata) => Array.isArray(tags) && tags.includes('chat:addressed');
-/**
- * Parse a prose segment's routing prefix (explicit prose routing —
- * docs/explicit-prose-routing.md). The FIRST line may be:
- *   `>>target [!] [body…]`   — target = channel spec or `private`
- * The ` !` continuation modifier must immediately follow the target,
- * whitespace-separated. Body may start on the same line or the next.
- */
-function parseProsePrefix(text) {
-    const m = /^>>(\S+)([ \t]+!)?[ \t]*\n?/.exec(text);
-    if (!m)
-        return { kind: 'none', continueTurn: false, body: text };
-    const target = m[1];
-    const continueTurn = m[2] !== undefined;
-    const body = text.slice(m[0].length);
-    // `skip_reply` mirrors the tool the model already knows: text stays in
-    // context, nothing is delivered. (Deliberately NOT called "private"/"note" —
-    // that vocabulary sat adjacent to signed thinking in a live window and drew
-    // a reasoning_extraction classifier hit, 2026-07-24 Fable.)
-    if (target === 'skip_reply') {
-        return { kind: 'private', continueTurn, body };
-    }
-    return { kind: 'target', target, continueTurn, body };
-}
+// parseProsePrefix moved to ./mcpl/prose-grammar.ts — ONE grammar shared with
+// the outgoing-stream router (Spec 14.3), so streamed chunks and delivered
+// envelopes can never disagree on what is a prefix.
 /** One-time primer appended when an agent's proseRouting mode changes. */
 function proseModePrimer(mode) {
     if (mode === 'locus') {
@@ -442,6 +427,17 @@ export class AgentFramework {
     /** Forks whose TTL closure turn has been queued — disposed (removed from
      * agents/agentConfigs/conversationAgentHomes) when their stream ends. */
     closingConversationAgents = new Set();
+    // Client-side programmatic tool calling (`code_execution`). Null unless
+    // config.codeExecution.enabled. One PyRunner per agent (interpreter state
+    // is per-agent, like a per-agent container); waiters resolve script-inner
+    // tool calls dispatched through the normal dispatchToolCall path.
+    codeExecutionConfig = null;
+    codeExecutionRunners = new Map();
+    scriptToolWaiters = new Map();
+    /** Agents whose running script hit an endTurn-carrying inner result —
+     *  deferred and applied to the final code_execution result instead of
+     *  cancelling the stream mid-script (which would wedge the turn). */
+    scriptDeferredEndTurn = new Set();
     mcplTools = [];
     mcplToolRefreshInFlight = false;
     mcplToolRefreshPending = false;
@@ -659,6 +655,9 @@ export class AgentFramework {
         // Stored for lazy MCPL initialization (connectMcplServer on a framework
         // that started with zero configured servers).
         framework.mcplInferenceRoutingConfig = config.inferenceRouting ?? null;
+        // Client-side programmatic tool calling (code_execution). Config is only
+        // retained when enabled — everything downstream gates on the field.
+        framework.codeExecutionConfig = config.codeExecution?.enabled ? config.codeExecution : null;
         // Initialize MCPL subsystems if configured
         if (config.mcplServers && config.mcplServers.length > 0) {
             // Validate tool prefixes: no collisions with module names or between servers
@@ -739,6 +738,13 @@ export class AgentFramework {
     async stop() {
         this.running = false;
         this.queue.close();
+        // Kill running code_execution scripts before cancelling streams: a
+        // zombie script must not keep firing side-effectful tool calls into a
+        // framework that is shutting down.
+        for (const runner of this.codeExecutionRunners.values()) {
+            runner.dispose();
+        }
+        this.codeExecutionRunners.clear();
         // Cancel all active streams
         for (const agent of this.agents.values()) {
             if (agent.state.status === 'streaming' ||
@@ -1004,6 +1010,9 @@ export class AgentFramework {
             ...(this.getWorkspaceModule()
                 ? [AgentFramework.SAVE_IMAGE_TOOL, AgentFramework.READ_IMAGE_TOOL]
                 : []),
+            ...(this.codeExecutionConfig
+                ? [buildCodeExecutionToolDefinition(this.codeExecutionConfig)]
+                : []),
         ];
     }
     /** The registered workspace module, if any (used by save_image). */
@@ -1274,7 +1283,7 @@ export class AgentFramework {
      *
      * Returns null when the agent's strategy has no fold plan (non-adaptive).
      */
-    previewContextSettings(agentName, budgetTokens, overrides) {
+    previewContextSettings(agentName, budgetTokens, overrides, opts) {
         const agent = this.agents.get(agentName);
         if (!agent)
             throw new Error(`Unknown agent: ${agentName}`);
@@ -1282,8 +1291,10 @@ export class AgentFramework {
         if (typeof cm.previewContext !== 'function')
             return null;
         // reserveForResponse mirrors the live compile so the previewed middle is
-        // comparable to what the agent actually gets.
-        return cm.previewContext({ maxTokens: budgetTokens, reserveForResponse: agent.maxTokens }, overrides);
+        // comparable to what the agent actually gets. `opts.render` additionally
+        // returns the rendered entries — opt-in, since they are megabytes on a
+        // large store, and older context-manager builds ignore the argument.
+        return cm.previewContext({ maxTokens: budgetTokens, reserveForResponse: agent.maxTokens }, overrides, opts);
     }
     /**
      * Check if process logging is enabled.
@@ -2785,6 +2796,18 @@ export class AgentFramework {
         // Anthropic API.  If we let modules or MCPL handlers run first they may add
         // messages between tool_use and tool_result, causing a 400 error.
         if (event.type === 'tool-result') {
+            // Script-inner tool calls (client-side programmatic tool calling):
+            // resolve the waiter and stop. These calls belong to a RUNNING
+            // code_execution script, not to the agent's pending tool round — they
+            // must not touch agent state (and must resolve even for ephemeral
+            // agents that aren't in this.agents, or after the agent's own round
+            // has already settled).
+            const scriptWaiter = this.scriptToolWaiters.get(event.callId);
+            if (scriptWaiter) {
+                this.scriptToolWaiters.delete(event.callId);
+                scriptWaiter(event.result);
+                return;
+            }
             const agent = this.agents.get(event.agentName);
             if (agent) {
                 this.touchEphemeralRun(event.agentName, true);
@@ -4029,6 +4052,29 @@ export class AgentFramework {
             : resolveTurnLocus();
         if (typingChannel)
             this.channelRegistry.startTyping(typingChannel);
+        // MCPL Spec 14.3 outgoing streaming: route text deltas to their
+        // destination server AS THEY GENERATE (voice synthesis, live message
+        // rendering). Pure observer surface — suppression is fail-closed (nothing
+        // streams that delivery would refuse), emission is capability-gated in
+        // the registry (`channels.streaming`), and delivery via deliverProse
+        // remains the sole authoritative send.
+        const outgoingInferenceId = `inf_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+        let outgoingIndex = 0;
+        const proseStream = this.channelRegistry
+            ? new ProseStreamRouter({
+                mode: agent.proseRouting === 'explicit' ? 'explicit' : 'locus',
+                initialTarget: typingChannel,
+                resolve: (spec) => {
+                    const r = this.channelRegistry.resolveProseTarget(spec);
+                    return 'channelId' in r ? r.channelId : null;
+                },
+            })
+            : null;
+        const emitOutgoing = (deltas) => {
+            for (const rd of deltas) {
+                this.channelRegistry.sendOutgoingChunk(rd.channelId, agent.name, outgoingInferenceId, outgoingIndex++, rd.delta);
+            }
+        };
         const adoptInjectedRound = () => {
             if (!this.midTurnInputSignals.has(agent.name))
                 return;
@@ -4054,6 +4100,9 @@ export class AgentFramework {
                             // turn's prose is bound for, without re-deriving routing.
                             channelId: typingChannel ?? undefined,
                         });
+                        if (proseStream && event.meta.type === 'text') {
+                            emitOutgoing(proseStream.feed(event.content));
+                        }
                         break;
                     case 'block': {
                         const { event: phase, index, block } = event.event;
@@ -4570,6 +4619,7 @@ export class AgentFramework {
                         // Only reset + retry if this is still the active stream
                         if (agent.streamId !== myStreamId)
                             break;
+                        this.abortAgentScript(agent.name, 'stream error');
                         agent.reset();
                         const action = this.errorPolicy.onInferenceError(err, agent.name, attempt);
                         if (action.retry) {
@@ -4616,6 +4666,7 @@ export class AgentFramework {
                         // may have already started a new stream, bumping streamId)
                         if (agent.streamId === myStreamId) {
                             const durationMs = Date.now() - startTime;
+                            this.abortAgentScript(agent.name, `stream aborted (${reason})`);
                             agent.reset();
                             this.settleAgent(agent.name, {
                                 stopReason: 'exhausted',
@@ -4714,6 +4765,7 @@ export class AgentFramework {
                 request: compiledRequest ?? { note: 'streaming request threw' },
                 durationMs,
             });
+            this.abortAgentScript(agent.name, 'stream threw');
             agent.reset();
             this.eventGate?.onInferenceEnded(agent.name);
         }
@@ -4730,6 +4782,15 @@ export class AgentFramework {
             // Stop the typing indicator on every exit path (complete, error,
             // exhausted, abort) so it never sticks after the turn ends.
             this.channelRegistry?.stopTyping();
+            // Spec 14.3: flush any held line-start text, then close each streamed
+            // channel with its final moderated content — the consumer's signal to
+            // finalize (end the TTS utterance, settle the rendered message).
+            if (proseStream) {
+                emitOutgoing(proseStream.finish());
+                for (const [channelId, text] of proseStream.byChannel()) {
+                    this.channelRegistry.sendOutgoingComplete(channelId, agent.name, outgoingInferenceId, text);
+                }
+            }
             this.frameworkCancelledStreams.delete(`${agent.name}:${myStreamId}`);
             this.activeStreams.delete(agent.name);
             this.pendingAssistantBlocks.delete(agent.name);
@@ -4753,6 +4814,12 @@ export class AgentFramework {
      * Used by SubagentModule to dispatch tool calls for ephemeral agents.
      */
     async executeToolCall(call) {
+        // Client-side programmatic tool calling for promise-based callers
+        // (SubagentModule ephemerals). Keyed by callerAgentName so each ephemeral
+        // gets its own interpreter state.
+        if (call.name === CODE_EXECUTION_TOOL_NAME && this.codeExecutionConfig) {
+            return this.runCodeExecution(call.callerAgentName ?? '__ephemeral__', call);
+        }
         // MCPL tools are dispatched via the MCPL subsystem
         if (this.mcplServerRegistry) {
             // Check if this is an MCPL-prefixed tool
@@ -4800,6 +4867,180 @@ export class AgentFramework {
             };
         }
     }
+    // ---------------------------------------------------------------------------
+    // Client-side programmatic tool calling (code_execution)
+    // ---------------------------------------------------------------------------
+    /** Event-pushing wrapper for the model-driven dispatch path. */
+    dispatchCodeExecutionToolCall(agentName, call) {
+        this.emitTrace({
+            type: 'tool:started',
+            module: 'code_execution',
+            tool: call.name,
+            callId: call.id,
+            input: call.input,
+        });
+        const startTime = Date.now();
+        this.runCodeExecution(agentName, call)
+            .catch((error) => {
+            // runCodeExecution is designed not to reject; this is the last-resort
+            // guard so a bug here can never strand the agent in waiting_for_tools.
+            const err = error instanceof Error ? error : new Error(String(error));
+            return { success: false, error: `code_execution failed: ${err.message}`, isError: true };
+        })
+            .then((result) => {
+            if (result.isError) {
+                this.emitTrace({
+                    type: 'tool:failed',
+                    module: 'code_execution',
+                    tool: call.name,
+                    callId: call.id,
+                    error: result.error ?? 'unknown error',
+                });
+            }
+            else {
+                this.emitTrace({
+                    type: 'tool:completed',
+                    module: 'code_execution',
+                    tool: call.name,
+                    callId: call.id,
+                    durationMs: Date.now() - startTime,
+                });
+            }
+            this.pushEvent({
+                type: 'tool-result',
+                callId: call.id,
+                agentName,
+                moduleName: 'code_execution',
+                result,
+            });
+        });
+    }
+    /**
+     * Run one code_execution script for an agent. Never rejects.
+     *
+     * The script runs in the agent's persistent python interpreter with every
+     * tool on the agent's CURRENT surface injected (minus code_execution
+     * itself). Inner tool calls are dispatched through dispatchToolCall — the
+     * exact model path, including MCPL state/checkpoint handling, channel
+     * routing, and traces — and resolved via scriptToolWaiters, so their
+     * results reach the running script and never the model context.
+     */
+    async runCodeExecution(agentName, call) {
+        const input = (call.input ?? {});
+        if (typeof input.code !== 'string' || input.code.trim() === '') {
+            return {
+                success: false,
+                error: 'code_execution requires a non-empty `code` string',
+                isError: true,
+            };
+        }
+        const agent = this.agents.get(agentName);
+        const surface = agent
+            ? this.getToolsForAgent(agentName).filter((t) => agent.canUseTool(t.name))
+            : this.getAllTools(); // ephemeral agents: full surface, matching executeToolCall
+        const injected = buildInjectedTools(surface.map((t) => t.name).filter((name) => name !== CODE_EXECUTION_TOOL_NAME));
+        const runner = this.getOrCreateScriptRunner(agentName);
+        this.scriptDeferredEndTurn.delete(agentName);
+        const exec = await runner.exec(input.code, injected);
+        const endTurn = this.scriptDeferredEndTurn.delete(agentName);
+        return {
+            success: true,
+            data: { stdout: exec.stdout, stderr: exec.stderr, return_code: exec.returnCode },
+            isError: false,
+            ...(endTurn ? { endTurn: true } : {}),
+        };
+    }
+    getOrCreateScriptRunner(agentName) {
+        let runner = this.codeExecutionRunners.get(agentName);
+        if (!runner) {
+            const cfg = this.codeExecutionConfig;
+            runner = new PyRunner({
+                pythonPath: cfg?.pythonPath,
+                toolCallTimeoutMs: cfg?.toolCallTimeoutMs,
+                scriptTimeoutMs: cfg?.scriptTimeoutMs,
+                idleReclaimMs: cfg?.idleReclaimMs,
+                label: agentName,
+                onToolCall: (toolName, args) => this.handleScriptToolCall(agentName, toolName, args),
+            });
+            this.codeExecutionRunners.set(agentName, runner);
+        }
+        return runner;
+    }
+    /**
+     * Resolve one script-inner tool call to the string the script's tool
+     * function returns. Never rejects — errors become "Error: ..." strings,
+     * matching the managed PTC runtime ("Claude's code receives this error").
+     *
+     * Results are serialized with the HISTORY serializer (images become
+     * placeholders): programmatic tool results are text-only by contract, and
+     * a script variable holding megabytes of base64 helps nobody.
+     */
+    async handleScriptToolCall(agentName, toolName, args) {
+        if (toolName === CODE_EXECUTION_TOOL_NAME) {
+            return 'Error: code_execution cannot be called from within a script';
+        }
+        const result = await this.dispatchScriptToolCall(agentName, toolName, args);
+        if (result.endTurn) {
+            // Deferred: applied to the final code_execution result (see
+            // scriptDeferredEndTurn) — ending the turn mid-script would cancel the
+            // stream while the script still runs and wedge the tool round.
+            this.scriptDeferredEndTurn.add(agentName);
+        }
+        if (result.isError) {
+            return `Error: ${result.error ?? 'tool call failed'}`;
+        }
+        if (result.data === undefined)
+            return '';
+        const agent = this.agents.get(agentName);
+        const maxChars = agent ? this.getMaxToolResultChars(agent) : undefined;
+        return toolResultDataToHistoryString(result.data, maxChars);
+    }
+    /**
+     * Dispatch a script-inner tool call through the NORMAL dispatch path and
+     * resolve with its result. The waiter intercept in handleProcessEvent
+     * (keyed by the pytc- call ID) routes the tool-result event here instead
+     * of into the agent's pending tool round.
+     */
+    dispatchScriptToolCall(agentName, toolName, args) {
+        return new Promise((resolve) => {
+            const callId = `pytc-${randomUUID()}`;
+            // Host-side leak guard: the python runtime already raises TimeoutError
+            // at toolCallTimeoutMs; this only reclaims the waiter if a dispatch path
+            // loses the result entirely (so the map cannot grow unboundedly).
+            const safetyMs = (this.codeExecutionConfig?.toolCallTimeoutMs ?? 270_000) + 30_000;
+            const safety = setTimeout(() => {
+                if (this.scriptToolWaiters.delete(callId)) {
+                    resolve({
+                        success: false,
+                        error: `tool '${toolName}' produced no result within ${Math.round(safetyMs / 1000)}s`,
+                        isError: true,
+                    });
+                }
+            }, safetyMs);
+            safety.unref?.();
+            this.scriptToolWaiters.set(callId, (result) => {
+                clearTimeout(safety);
+                resolve(result);
+            });
+            try {
+                this.dispatchToolCall(agentName, { id: callId, name: toolName, input: args });
+            }
+            catch (error) {
+                if (this.scriptToolWaiters.delete(callId)) {
+                    clearTimeout(safety);
+                    const err = error instanceof Error ? error : new Error(String(error));
+                    resolve({ success: false, error: err.message, isError: true });
+                }
+            }
+        });
+    }
+    /** Abort a running script when the agent's turn dies underneath it. */
+    abortAgentScript(agentName, reason) {
+        const runner = this.codeExecutionRunners.get(agentName);
+        if (runner?.busy) {
+            runner.abort(reason);
+        }
+    }
     toMembraneToolResult(callId, afResult, maxChars) {
         if (afResult.isError) {
             return { toolUseId: callId, content: afResult.error ?? 'Unknown error', isError: true };
@@ -5018,6 +5259,13 @@ export class AgentFramework {
             this.dispatchChannelToolCall(agentName, enrichedCall);
             return;
         }
+        // Client-side programmatic tool calling: run a python script that calls
+        // the agent's other tools in-process (script-inner calls come back through
+        // this very dispatcher with waiter-tracked call IDs).
+        if (enrichedCall.name === CODE_EXECUTION_TOOL_NAME && this.codeExecutionConfig) {
+            this.dispatchCodeExecutionToolCall(agentName, enrichedCall);
+            return;
+        }
         // prose_help: on-demand routing reference for explicit-prose agents.
         // Answered inline — the grammar is a tool RESULT (model-requested), never
         // ambient context (see PROSE_ROUTING_HELP / teach-by-bounce).