@mono-agent/agent-runtime 0.4.0 → 0.4.1

package/src/ai/providers/pi-native/structured-output.js

@@ -0,0 +1,130 @@
+// @ts-check
+// Structured-output enforcement for the pi-native bridge.
+//
+// Pure moves out of pi-native.js: the system-prompt instruction append, the
+// finalization re-prompt text, the retry predicate, the retry diagnostics, and
+// the single-re-prompt finalization executor. No session or run state lives
+// here — the executor takes its harness/tool/warnings deps explicitly and the
+// caller owns the `structuredResult` closure the tool populates.
+
+/**
+ * Append the StructuredOutput usage instruction to the system prompt when an
+ * output schema is active. No schema → the prompt is returned unchanged. A host
+ * or run `prompts.structuredOutputInstruction(systemPrompt)` override, when
+ * supplied, replaces the default instruction text (it receives the raw system
+ * prompt and returns the augmented one); otherwise the default below is used.
+ * @param {string} systemPrompt
+ * @param {unknown} outputSchema
+ * @param {import('../../types.js').RuntimePromptOverrides} [prompts]
+ * @returns {string}
+ */
+export function appendStructuredOutputInstruction(systemPrompt, outputSchema, prompts) {
+  if (!outputSchema) return systemPrompt;
+  if (typeof prompts?.structuredOutputInstruction === "function") {
+    return prompts.structuredOutputInstruction(systemPrompt);
+  }
+  return [
+    systemPrompt,
+    "",
+    "Structured output is available through the `StructuredOutput` tool.",
+    "When the final result is ready, call `StructuredOutput` with the complete JSON object matching the requested schema.",
+    "Do not also print the same JSON as prose unless tool calling is unavailable.",
+  ].join("\n");
+}
+
+/**
+ * The finalization re-prompt issued when a turn ended without submitting the
+ * required structured result. A `prompts.structuredOutputFinalization()`
+ * override, when supplied, replaces the default text.
+ * @param {import('../../types.js').RuntimePromptOverrides} [prompts]
+ * @returns {string}
+ */
+export function structuredOutputFinalizationPrompt(prompts) {
+  if (typeof prompts?.structuredOutputFinalization === "function") {
+    return prompts.structuredOutputFinalization();
+  }
+  return [
+    "The previous assistant turn ended without submitting the required structured result.",
+    "Do not run tools, inspect files, or redo work.",
+    "Call only `StructuredOutput` once with the final object matching the requested schema, based on the completed transcript above.",
+    "Do not print prose before or after the tool call.",
+  ].join("\n");
+}
+
+/**
+ * Whether the run should re-prompt once for structured-output finalization: a
+ * schema is active, no structured result was produced, the turn ended with no
+ * text, the run was not aborted / did not hit max turns, and the stop reason is
+ * not an error/abort.
+ * @param {{outputSchema: unknown, structuredResult: unknown, finalText: unknown, stopReason: unknown, externalAbort: boolean, maxTurnsHit: boolean}} params
+ * @returns {boolean}
+ */
+export function shouldRetryStructuredOutputFinalization({
+  outputSchema,
+  structuredResult,
+  finalText,
+  stopReason,
+  externalAbort,
+  maxTurnsHit,
+}) {
+  if (!outputSchema) return false;
+  if (structuredResult !== null && structuredResult !== undefined) return false;
+  if (String(finalText || "").trim()) return false;
+  if (externalAbort || maxTurnsHit) return false;
+  return stopReason !== "error" && stopReason !== "aborted";
+}
+
+/**
+ * The structured-output finalization diagnostics spread into the run's
+ * diagnostics/errorDetails. Empty when no retry was attempted.
+ * @param {number} attempts
+ * @param {string|null} reason
+ * @param {boolean} failed
+ * @returns {Record<string, unknown>}
+ */
+export function structuredOutputRetryDiagnostics(attempts, reason, failed) {
+  if (!attempts) return {};
+  return {
+    structured_output_finalization_retry_attempts: attempts,
+    structured_output_finalization_retry_reason: reason,
+    structured_output_finalization_retry_failed: !!failed,
+  };
+}
+
+/**
+ * Run the single structured-output finalization re-prompt in the same session.
+ *
+ * The harness is idle after waitForIdle(), so re-prompt (not followUp, which
+ * only queues onto an active run) with only StructuredOutput active. This
+ * re-prompts ONCE in the same session, matching the legacy single
+ * agent.continue() finalization re-prompt. Tools are restored in finally.
+ *
+ * Returns the retry bookkeeping ({attempts, reason}); the caller computes
+ * `failed` from the (closure-owned) structuredResult after re-capturing state.
+ * @param {{harness: any, structuredTool: {name: string}|null, runtimeWarnings: Array<Record<string, unknown>>, prompts?: import('../../types.js').RuntimePromptOverrides}} deps
+ * @returns {Promise<{attempts: number, reason: string}>}
+ */
+export async function runStructuredOutputFinalizationRetry({ harness, structuredTool, runtimeWarnings, prompts }) {
+  const reason = "empty_final_output";
+  runtimeWarnings.push({
+    warning_kind: "structured_output_finalization_retry",
+    source: "pi",
+    reason,
+    message: "Pi stopped without text or structured output; retrying once in the same session with only StructuredOutput enabled.",
+  });
+  const previousActive = harness.getActiveTools().map((/** @type {{name: string}} */ toolDef) => toolDef.name);
+  try {
+    await harness.setActiveTools(structuredTool ? [structuredTool.name] : []);
+    await harness.prompt(structuredOutputFinalizationPrompt(prompts));
+    await harness.waitForIdle();
+  } catch (err) {
+    runtimeWarnings.push({
+      warning_kind: "structured_output_finalization_retry_failed",
+      source: "pi",
+      message: (/** @type {any} */ (err))?.message || String(err),
+    });
+  } finally {
+    try { await harness.setActiveTools(previousActive); } catch { /* best-effort */ }
+  }
+  return { attempts: 1, reason };
+}

package/src/ai/providers/pi-native/turn-runner.js

@@ -0,0 +1,278 @@
+// @ts-check
+// Turn execution for the pi-native bridge.
+//
+// Pure moves out of pi-native.js: effort→thinkingLevel mapping, harness
+// construction + stream-subscriber wiring + abort wiring, the live-input
+// steering consumer, and the prompt/waitForIdle run. No module-level mutable
+// state; run state (harness, removeAbortHandler, externalAbort) lives on the
+// caller-owned runState.
+
+import { AgentHarness } from "@earendil-works/pi-agent-core";
+import { NodeExecutionEnv } from "@earendil-works/pi-agent-core/node";
+import {
+  createStructuredOutputTool,
+  getPiBuiltinTools,
+  initPiMcpTools,
+} from "../../../agent/tools/pi-bridge.js";
+import { readToolRuntime } from "../../../agent/tools/shared/runtime-context.js";
+import { formatLiveInputGuidance } from "../../live-input-prompt.js";
+import { appendStructuredOutputInstruction } from "./structured-output.js";
+import { createStreamSubscriber } from "./stream-subscriber.js";
+
+/**
+ * Build the turn's tool set: the sandboxed/allowlisted/bloat-guarded builtin
+ * tools, the MCP tool bridge, and the StructuredOutput tool (whose callback
+ * writes runState.structuredResult). Surfaces MCP init/list failures to both the
+ * event stream and runtimeWarnings. Returns the assembled tools plus the MCP
+ * clients (closed by the caller's finally) and the structured tool.
+ * @param {any} runState
+ * @param {any} params
+ * @returns {Promise<{tools: any[], structuredTool: any, mcpClients: any[]}>}
+ */
+export async function buildTurnTools(runState, {
+  options,
+  capabilities,
+  toolLimits,
+  approvalManager,
+  runtime,
+  resolved,
+  onEvent,
+  runtimeWarnings,
+}) {
+  const onTruncate = (info) => {
+    try {
+      onEvent({
+        type: "runtime_warning",
+        warning_kind: "tool_payload_truncated",
+        source: "tool_bloat_guard",
+        ...info,
+      });
+    } catch { /* best-effort */ }
+  };
+  const persistArtifact = options.persistArtifact || null;
+  const qaOutputDir = options.qaOutputDir || options.runArtifactDir || null;
+
+  // Per-run sandbox override (item 7): precedence run impl > host impl >
+  // passthrough. When the run supplies its own RuntimeSandbox, thread a ctx copy
+  // whose `.sandbox` is that impl so this run's tools/MCP-stdio launcher enforce
+  // through it; otherwise the host/default ToolContext is used unchanged. The
+  // per-run policy DATA (sandboxPolicy) still merges monotonically inside
+  // resolveSandboxPolicy (I13) regardless of which impl is chosen.
+  const runCtx = options.sandbox
+    ? { ...(options.toolContext ?? readToolRuntime()), sandbox: options.sandbox }
+    : options.toolContext;
+  const sandboxEngine = options.sandboxEngine ?? runCtx?.sandboxEngine;
+
+  // REUSED custom pieces: built-in tool sandboxing + allowlist/bloat filter +
+  // approval gates. These are identical to the legacy bridge.
+  // Cast: pi-bridge's tool-builder option bags are not precisely typed (their
+  // no-default destructured keys drop out of structural inference), so the
+  // caller's full bag is passed through an `any` boundary — matching how the
+  // pre-split (non-@ts-check) orchestrator called these.
+  const builtIns = capabilities.tool_use === false
+    ? []
+    : getPiBuiltinTools(options.allowedTools, /** @type {any} */ ({
+      skillNames: (options.skills || []).map((/** @type {{name: string}} */ skill) => skill.name),
+      // Full skill objects so read_skill can honor pi's neutral Skill shape
+      // ({name, filePath, ...}) and derive each skill's root from its own
+      // filePath when no shared skillsRoot is threaded.
+      skills: options.skills || [],
+      // Progressive skill disclosure: when the harness threads the skills root
+      // (the directory holding `<name>/SKILL.md`) the read_skill tool resolves
+      // bodies directly from there. `dataDir` (skills under `<dataDir>/skills`)
+      // remains the back-compat fallback; a per-skill filePath is the third path.
+      skillsRoot: options.skillsRoot,
+      dataDir: options.dataDir,
+      cwd: options.cwd,
+      onEvent,
+      persistArtifact,
+      onTruncate,
+      toolLimits,
+      toolPayloadMaxBytes: toolLimits.toolPayloadMaxBytes,
+      imageInlineMaxBytes: toolLimits.imageInlineMaxBytes,
+      toolPolicy: options.toolPolicy,
+      sandboxPolicy: options.sandboxPolicy,
+      sandboxEngine,
+      approvalManager,
+      approvalModel: runtime.model?.id || runtime.model?.name || resolved.model,
+      ctx: runCtx,
+    }));
+
+  const structuredTool = createStructuredOutputTool(options.outputSchema, (value) => {
+    runState.structuredResult = value;
+  });
+  const reservedNames = new Set(builtIns.map((/** @type {{name: string}} */ toolDef) => toolDef.name));
+  if (structuredTool) reservedNames.add(structuredTool.name);
+
+  // REUSED MCP tool bridge: same initPiMcpTools sandboxing path (see the cast
+  // note above — the option bag crosses the same untyped pi-bridge boundary).
+  const mcpInit = capabilities.tool_use === false
+    ? { clients: [], tools: [], warnings: [] }
+    : await initPiMcpTools(options.mcpServers || {}, reservedNames, /** @type {any} */ ({
+      cwd: options.cwd,
+      persistArtifact,
+      qaOutputDir,
+      onTruncate,
+      limits: toolLimits,
+      toolPayloadMaxBytes: toolLimits.toolPayloadMaxBytes,
+      sandboxPolicy: options.sandboxPolicy,
+      sandboxEngine,
+      ctx: runCtx,
+    }));
+  // Surface MCP init/list failures BOTH to the live event stream and to runtimeWarnings, so a
+  // failed server (e.g. an stdio adapter-send child that closed on startup) lands in the run
+  // summary's runtimeWarnings instead of being buried as a transient event the summary drops.
+  for (const warning of mcpInit.warnings || []) {
+    onEvent(warning);
+    runtimeWarnings.push(warning);
+  }
+
+  const tools = [
+    ...builtIns,
+    ...mcpInit.tools,
+    ...(structuredTool ? [structuredTool] : []),
+  ];
+  return { tools, structuredTool, mcpClients: mcpInit.clients };
+}
+
+/**
+ * Map an effort level to the harness thinkingLevel, respecting model reasoning
+ * capability (no reasoning / reasoning_mode "none" → "off").
+ * @param {string} effort
+ * @param {any} capabilities
+ * @returns {string}
+ */
+export function thinkingLevelForEffort(effort, capabilities) {
+  if (!capabilities?.reasoning || capabilities.reasoning_mode === "none") return "off";
+  if (effort === "none") return "off";
+  if (effort === "max") return "xhigh";
+  if (effort === "xhigh") return "xhigh";
+  if (effort === "high") return "high";
+  if (effort === "medium") return "medium";
+  return "low";
+}
+
+/**
+ * Construct the AgentHarness for this turn, subscribe the stream-subscriber, and
+ * wire the external abort handler. Sets runState.harness and
+ * runState.removeAbortHandler; the abort handler sets runState.externalAbort and
+ * aborts the harness. Returns the harness.
+ * @param {any} runState
+ * @param {any} params
+ * @returns {any}
+ */
+export function buildTurnHarness(runState, {
+  cwd,
+  session,
+  piModels,
+  model,
+  thinkingLevel,
+  systemPrompt,
+  outputSchema,
+  tools,
+  maxRetries,
+  maxRetryDelayMs,
+  steeringMode,
+  onEvent,
+  options,
+  toolLimits,
+}) {
+  const harness = new AgentHarness({
+    env: new NodeExecutionEnv({ cwd: cwd || process.cwd() }),
+    session,
+    models: piModels,
+    model,
+    thinkingLevel,
+    systemPrompt: appendStructuredOutputInstruction(systemPrompt, outputSchema, options.prompts),
+    tools,
+    streamOptions: { maxRetries, maxRetryDelayMs },
+    steeringMode,
+    followUpMode: steeringMode,
+  });
+  runState.harness = harness;
+
+  harness.subscribe(createStreamSubscriber(runState, { onEvent, options, toolLimits, harness }));
+
+  const abortHandler = () => {
+    runState.externalAbort = true;
+    harness.abort();
+  };
+  if (options.abortSignal) {
+    options.abortSignal.addEventListener("abort", abortHandler, { once: true });
+    runState.removeAbortHandler = () => options.abortSignal.removeEventListener?.("abort", abortHandler);
+  }
+  return harness;
+}
+
+/**
+ * Start the live-input steering consumer. Consumes follow-up messages and steers
+ * the harness mid-run; the consumer is tied to run completion (an internal
+ * runComplete flag) so it stops steering once the run finishes and does not
+ * swallow a follow-up meant for a later turn. Returns a `stop()` teardown.
+ * @param {{harness: any, options: any, onEvent: (event: any) => void}} deps
+ * @returns {{stop: () => Promise<void>}}
+ */
+export function startLiveInput({ harness, options, onEvent }) {
+  if (!options.liveInput) return { stop: async () => {} };
+  const iterator = typeof options.liveInput[Symbol.asyncIterator] === "function"
+    ? options.liveInput[Symbol.asyncIterator]()
+    : options.liveInput;
+  let runComplete = false;
+  const task = (async () => {
+    try {
+      while (!runComplete && !options.abortSignal?.aborted) {
+        const next = await iterator.next();
+        if (next.done || runComplete || options.abortSignal?.aborted) break;
+        await harness.steer(formatLiveInputGuidance(next.value.body, options.prompts));
+      }
+    } catch (err) {
+      onEvent({
+        type: "runtime_warning",
+        warning_kind: "live_input_failed",
+        message: (/** @type {any} */ (err))?.message || String(err),
+      });
+    }
+  })();
+  return {
+    // The run is done: stop the live-steering consumer so it cannot steer a
+    // finished harness or swallow a follow-up meant for the next turn. We signal
+    // completion, then best-effort return() the iterator to unblock a pending
+    // next(). We do NOT await the task (it could block on next() if the source
+    // has no return()), but the runComplete guard prevents any further steering.
+    stop: async () => {
+      runComplete = true;
+      if (iterator && typeof iterator.return === "function") {
+        try { await iterator.return(); } catch { /* best-effort */ }
+      }
+      void task;
+    },
+  };
+}
+
+/**
+ * Run a single prompt on the harness and wait for it to go idle. A stream error
+ * surfaces on the harness (not a throw), so a thrown prompt is captured as
+ * runError; waitForIdle always runs afterward.
+ * @param {any} harness
+ * @param {string} promptText
+ * @param {Array<any>} promptImages
+ * @returns {Promise<{runError: any}>}
+ */
+export async function runHarnessPrompt(harness, promptText, promptImages) {
+  let runError = null;
+  try {
+    // Pass structured images (when present) so multimodal input reaches the
+    // model as image blocks rather than stringified text. AgentHarness.prompt
+    // takes them under an options object (`{ images }`); a bare array would be
+    // read as `options` and silently dropped (options?.images === undefined).
+    if (Array.isArray(promptImages) && promptImages.length > 0) {
+      await harness.prompt(promptText, { images: promptImages });
+    } else {
+      await harness.prompt(promptText);
+    }
+  } catch (err) {
+    runError = err;
+  }
+  await harness.waitForIdle();
+  return { runError };
+}