@animalabs/agent-framework 0.7.0 → 0.7.3

package/src/framework.ts

@@ -59,12 +59,20 @@ import { FeatureSetManager } from './mcpl/feature-set-manager.js';
 import { ScopeManager } from './mcpl/scope-manager.js';
 import { HookOrchestrator } from './mcpl/hook-orchestrator.js';
 import { PushHandler, type McplPushEvent } 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 type { WorkspaceModule } from './modules/workspace/index.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
@@ -168,33 +176,9 @@ const isAddressedMessage = (
   _metadata?: Record<string, unknown>,
 ): boolean => 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: string): {
-  kind: 'target' | 'private' | 'none';
-  target?: string;
-  continueTurn: boolean;
-  body: string;
-} {
-  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: 'explicit' | 'locus'): string {
@@ -651,6 +635,18 @@ export class AgentFramework {
   /** Forks whose TTL closure turn has been queued — disposed (removed from
    * agents/agentConfigs/conversationAgentHomes) when their stream ends. */
   private closingConversationAgents: Set<string> = 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.
+  private codeExecutionConfig: import('./types/index.js').CodeExecutionConfig | null = null;
+  private codeExecutionRunners: Map<string, PyRunner> = new Map();
+  private scriptToolWaiters: Map<string, (result: ToolResult) => void> = 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). */
+  private scriptDeferredEndTurn: Set<string> = new Set();
+
   private mcplTools: import('./types/index.js').ToolDefinition[] = [];
   private mcplToolRefreshInFlight = false;
   private mcplToolRefreshPending = false;
@@ -918,6 +914,10 @@ export class AgentFramework {
     // 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
@@ -1010,6 +1010,14 @@ export class AgentFramework {
     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' ||
@@ -1307,6 +1315,9 @@ export class AgentFramework {
       ...(this.getWorkspaceModule()
         ? [AgentFramework.SAVE_IMAGE_TOOL, AgentFramework.READ_IMAGE_TOOL]
         : []),
+      ...(this.codeExecutionConfig
+        ? [buildCodeExecutionToolDefinition(this.codeExecutionConfig)]
+        : []),
     ];
   }
 
@@ -1623,6 +1634,7 @@ export class AgentFramework {
     agentName: string,
     budgetTokens: number,
     overrides?: Record<string, unknown>,
+    opts?: { render?: boolean },
   ): unknown {
     const agent = this.agents.get(agentName);
     if (!agent) throw new Error(`Unknown agent: ${agentName}`);
@@ -1630,14 +1642,18 @@ export class AgentFramework {
       previewContext?: (
         budget: TokenBudget,
         overrides?: Record<string, unknown>,
+        opts?: { render?: boolean },
       ) => unknown;
     };
     if (typeof cm.previewContext !== 'function') return null;
     // reserveForResponse mirrors the live compile so the previewed middle is
-    // comparable to what the agent actually gets.
+    // 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,
     );
   }
 
@@ -3371,6 +3387,19 @@ 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);
@@ -4782,6 +4811,32 @@ 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: { channelId: string; delta: string }[]): void => {
+      for (const rd of deltas) {
+        this.channelRegistry!.sendOutgoingChunk(
+          rd.channelId, agent.name, outgoingInferenceId, outgoingIndex++, rd.delta,
+        );
+      }
+    };
+
     const adoptInjectedRound = (): void => {
       if (!this.midTurnInputSignals.has(agent.name)) return;
       this.midTurnInputSignals.delete(agent.name);
@@ -4808,6 +4863,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': {
@@ -5387,6 +5445,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);
@@ -5434,6 +5493,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',
@@ -5538,6 +5598,7 @@ export class AgentFramework {
         request: compiledRequest ?? { note: 'streaming request threw' },
         durationMs,
       });
+      this.abortAgentScript(agent.name, 'stream threw');
       agent.reset();
       this.eventGate?.onInferenceEnded(agent.name);
     } finally {
@@ -5554,6 +5615,16 @@ 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);
@@ -5580,6 +5651,13 @@ export class AgentFramework {
    * Used by SubagentModule to dispatch tool calls for ephemeral agents.
    */
   async executeToolCall(call: ToolCall): Promise<ToolResult> {
+    // 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
@@ -5629,6 +5707,199 @@ export class AgentFramework {
     }
   }
 
+  // ---------------------------------------------------------------------------
+  // Client-side programmatic tool calling (code_execution)
+  // ---------------------------------------------------------------------------
+
+  /** Event-pushing wrapper for the model-driven dispatch path. */
+  private dispatchCodeExecutionToolCall(agentName: string, call: ToolCall): void {
+    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): ToolResult => {
+        // 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.
+   */
+  private async runCodeExecution(agentName: string, call: ToolCall): Promise<ToolResult> {
+    const input = (call.input ?? {}) as { code?: unknown };
+    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 } : {}),
+    };
+  }
+
+  private getOrCreateScriptRunner(agentName: string): PyRunner {
+    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.
+   */
+  private async handleScriptToolCall(
+    agentName: string,
+    toolName: string,
+    args: Record<string, unknown>,
+  ): Promise<string> {
+    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.
+   */
+  private dispatchScriptToolCall(
+    agentName: string,
+    toolName: string,
+    args: Record<string, unknown>,
+  ): Promise<ToolResult> {
+    return new Promise<ToolResult>((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. */
+  private abortAgentScript(agentName: string, reason: string): void {
+    const runner = this.codeExecutionRunners.get(agentName);
+    if (runner?.busy) {
+      runner.abort(reason);
+    }
+  }
+
   private toMembraneToolResult(callId: string, afResult: ToolResult, maxChars?: number): MembraneToolResult {
     if (afResult.isError) {
       return { toolUseId: callId, content: afResult.error ?? 'Unknown error', isError: true };
@@ -5868,6 +6139,14 @@ export class AgentFramework {
       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).

package/src/index.ts

@@ -55,6 +55,23 @@ export type {
 
 // Usage tracking
 export { UsageTracker } from './usage/index.js';
+
+// Client-side programmatic tool calling (code_execution): exposed so external
+// tooling can drive the python runtime the way the framework does (protocol
+// harnesses, runtime smoke tests).
+export {
+  PyRunner,
+  buildInjectedTools,
+  buildCodeExecutionToolDefinition,
+  CODE_EXECUTION_TOOL_NAME,
+  PYTHON_RUNTIME_SOURCE,
+} from './code-execution/index.js';
+export type {
+  InjectedTool,
+  ExecResult,
+  PyRunnerOptions,
+  ScriptToolCallHandler,
+} from './code-execution/index.js';
 export type { SessionUsage, AgentUsage, SessionUsageSnapshot, UsageUpdatedEvent } from './usage/index.js';
 
 // EventGate

package/src/mcpl/channel-registry.ts

@@ -1764,6 +1764,59 @@ export class ChannelRegistry {
   /** Resolve the outbound locus (fork HOME → this-turn's TRIGGERING channel →
    *  process-global default). Public so a multi-segment caller can snapshot it
    *  ONCE and pin every segment to it via routeSpeech's `overrideChannelId`. */
+  /**
+   * MCPL Spec 14.3 outgoing streaming: forward a moderated text delta to the
+   * server owning the channel, AS THE MODEL GENERATES. Emitted only when that
+   * server declared `channels.streaming` in its initialize capabilities —
+   * servers that never opted in (the whole existing fleet) receive nothing.
+   * Fire-and-forget and never throws: streaming is an observer surface; the
+   * authoritative delivery is the eventual channels/publish.
+   */
+  sendOutgoingChunk(
+    channelId: string,
+    conversationId: string,
+    inferenceId: string,
+    index: number,
+    delta: string,
+  ): void {
+    const server = this.streamingServerFor(channelId);
+    if (!server) return;
+    try {
+      server.sendChannelsOutgoingChunk({ inferenceId, conversationId, channelId, index, delta });
+    } catch { /* observer surface — never disturb the turn */ }
+  }
+
+  /** Spec 14.3 companion: final moderated content per channel at stream end. */
+  sendOutgoingComplete(
+    channelId: string,
+    conversationId: string,
+    inferenceId: string,
+    text: string,
+  ): void {
+    const server = this.streamingServerFor(channelId);
+    if (!server) return;
+    try {
+      server.sendChannelsOutgoingComplete({
+        inferenceId,
+        conversationId,
+        channelId,
+        content: [{ type: 'text', text }],
+      });
+    } catch { /* observer surface — never disturb the turn */ }
+  }
+
+  private streamingServerFor(channelId: string) {
+    // The map is keyed `${serverId}:${channelId}`; stream targets arrive as
+    // bare descriptor ids (what resolveProseTarget returns). Scan like the
+    // resolver does, and fail closed on cross-server ambiguity — the same
+    // never-guess rule that governs delivery.
+    const matches = [...this.channels.values()].filter((e) => e.descriptor.id === channelId);
+    if (matches.length !== 1) return null;
+    const server = this.serverRegistry.getServer(matches[0]!.serverId);
+    if (!server?.capabilities?.channels?.streaming) return null;
+    return server;
+  }
+
   resolveLocus(conversationId: string): string | null {
     const home = this.homeChannelResolver?.(conversationId);
     return home ?? this.activeChannelResolver?.(conversationId) ?? this.defaultPublishChannel ?? null;

package/src/mcpl/prose-grammar.ts

@@ -0,0 +1,40 @@
+/**
+ * Explicit-prose routing grammar — the SINGLE definition shared by the
+ * delivery path (framework.deliverProse*) and the outgoing-stream router
+ * (prose-stream-router.ts). Extracted from framework.ts verbatim so the two
+ * parsers cannot drift: a streamed chunk and its eventual delivery must agree
+ * on what is a prefix, what is a modifier, and what is body.
+ *
+ * Grammar (docs/explicit-prose-routing.md):
+ *   `>>target [!] [body…]`  — target = channel spec or `skip_reply`
+ *   The ` !` continuation modifier must immediately follow the target,
+ *   whitespace-separated. Body may start on the same line or the next.
+ *   A line's `>>` counts only when immediately followed by a target token
+ *   (`>> quoted arrow` stays body text).
+ */
+
+export interface ProsePrefix {
+  kind: 'target' | 'private' | 'none';
+  target?: string;
+  continueTurn: boolean;
+  body: string;
+}
+
+/** A REAL prefix line: `>>` immediately followed by a target token. */
+export const PROSE_PREFIX_LINE = /^>>\S/;
+
+export function parseProsePrefix(text: string): ProsePrefix {
+  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 };
+}