@mono-agent/agent-runtime 0.20.11 → 0.21.0

package/src/ai/providers/pi-native/harness-adapter.js

@@ -0,0 +1,376 @@
+// @ts-check
+// Compatibility boundary between mono-agent's Pi-native bridge and the
+// lane-based AgentHarness API introduced in pi-agent-core 0.85.
+
+import {
+  AgentHarness,
+  BACKGROUND_CONTEXT,
+  createBranchSummaryMessage,
+  createCompactionSummaryMessage,
+  getOrThrow,
+} from "@earendil-works/pi-agent-core";
+import { installPromptCacheDiagnostics, promptCacheRequest } from "./prompt-cache-diagnostics.js";
+
+export const PI_CONTEXT = BACKGROUND_CONTEXT;
+
+function operationError(record, fallback) {
+  const error = new Error(record?.error?.message || fallback);
+  if (record?.error?.code) /** @type {any} */ (error).code = record.error.code;
+  return error;
+}
+
+function isContextMessage(message) {
+  return message?.role !== "assistant"
+    || !["error", "aborted", "deferred"].includes(message.stopReason);
+}
+
+/**
+ * Pi 0.85 no longer exports its session-context projector. Reproduce the
+ * public entry contract here so transcript accounting uses the same latest-
+ * compaction and failed-assistant filtering rules as the harness.
+ * @param {any[]} pathEntries
+ * @param {{includeFailed?: boolean}} [options]
+ */
+export function buildPiSessionContext(pathEntries, { includeFailed = false } = {}) {
+  let start = 0;
+  for (let index = pathEntries.length - 1; index >= 0; index -= 1) {
+    if (pathEntries[index]?.type === "compaction") {
+      start = index;
+      break;
+    }
+  }
+  const entries = start > 0 ? pathEntries.slice(start) : pathEntries;
+  const messages = [];
+  for (const entry of entries) {
+    if (entry?.type === "message") {
+      if (includeFailed || isContextMessage(entry.message)) messages.push(entry.message);
+    } else if (entry?.type === "compaction") {
+      messages.push(createCompactionSummaryMessage(entry.summary, entry.tokensBefore, entry.timestamp));
+      messages.push(...(includeFailed
+        ? (entry.retainedTail || [])
+        : (entry.retainedTail || []).filter(isContextMessage)));
+    } else if (entry?.type === "branch_summary" && entry.summary) {
+      messages.push(createBranchSummaryMessage(entry.summary, entry.fromId, entry.timestamp));
+    }
+  }
+  return messages;
+}
+
+/**
+ * Give the surrounding bridge the small session surface it used before Pi
+ * moved branch operations onto AgentLane. The raw session remains available to
+ * AgentHarness.create(), while all transcript reads and writes use the attached
+ * main lane once the harness exists.
+ * @param {any} rawSession
+ */
+export function createPiSessionAdapter(rawSession) {
+  let lane = null;
+  let harness = null;
+  let closePromise = null;
+
+  const requireLane = () => {
+    if (!lane) throw new Error("Pi session lane is not attached");
+    return lane;
+  };
+
+  return {
+    rawSession,
+    get metadata() { return rawSession.metadata; },
+    attach(nextHarness, nextLane) {
+      harness = nextHarness;
+      lane = nextLane;
+    },
+    async buildContext() {
+      const entries = await requireLane().findEntries({ order: "oldestFirst" }, PI_CONTEXT);
+      // This bridge-facing transcript includes terminal error/abort messages so
+      // result classification can observe them. Pi filters those only when it
+      // constructs the next provider request.
+      return { messages: buildPiSessionContext(entries, { includeFailed: true }) };
+    },
+    getEntries() {
+      return requireLane().findEntries({ order: "oldestFirst" }, PI_CONTEXT);
+    },
+    getLeafId() {
+      return requireLane().getTipId(PI_CONTEXT);
+    },
+    appendMessage(message) {
+      return requireLane().appendMessage(message, PI_CONTEXT);
+    },
+    async moveTo(targetId) {
+      const result = getOrThrow(await requireLane().navigateTree(
+        targetId,
+        { summarize: false },
+        PI_CONTEXT,
+      ));
+      const record = result.navigation;
+      if (record.status === "failed") throw operationError(record, "Pi session navigation failed");
+      if (record.status !== "completed") throw operationError(record, "Pi session navigation was not completed");
+      return record.tipId;
+    },
+    getMetadata() {
+      return Promise.resolve(rawSession.metadata);
+    },
+    close() {
+      if (!closePromise) {
+        closePromise = (harness
+          ? harness.close(PI_CONTEXT)
+          : rawSession.close(PI_CONTEXT));
+      }
+      return closePromise;
+    },
+  };
+}
+
+function adaptTool(tool) {
+  return {
+    ...tool,
+    async execute(toolCallId, params, onUpdate, _toolContext, _invocation, context) {
+      return tool.execute(toolCallId, params, context.abortSignal, onUpdate);
+    },
+  };
+}
+
+const FORWARDED_EVENT_TYPES = [
+  "run_start",
+  "run_resume",
+  "run_suspend",
+  "operation_abort",
+  "run_end",
+  "fault",
+  "handler_error",
+  "turn_start",
+  "turn_end",
+  "retry_scheduled",
+  "retry_start",
+  "retry_end",
+  "message_start",
+  "message_update",
+  "message_end",
+  "tool_start",
+  "tool_update",
+  "tool_end",
+  "entry_added",
+  "queue_update",
+  "value_update",
+  "config_update",
+  "compaction_start",
+  "compaction_end",
+  "navigation_start",
+  "navigation_end",
+  "lane_created",
+  "usage",
+];
+
+function legacyEvent(event) {
+  // appendMessage() emits runless lifecycle events for transcript seeding.
+  // They are persistence notifications, not output from the active provider
+  // run, and forwarding them would manufacture assistant boundaries/usage for
+  // prior history. Real run-owned message events always carry runId in Pi 0.85.
+  if ((event.type === "message_start" || event.type === "message_end") && !event.runId) {
+    return null;
+  }
+  if (event.type === "message_update") {
+    return { ...event, assistantMessageEvent: event.event };
+  }
+  if (event.type === "tool_start") return { ...event, type: "tool_execution_start" };
+  if (event.type === "tool_update") return { ...event, type: "tool_execution_update" };
+  if (event.type === "tool_end") return { ...event, type: "tool_execution_end" };
+  return event;
+}
+
+/**
+ * Attach Pi 0.85's harness to one session and expose the intentionally small
+ * surface consumed by mono-agent's turn runner.
+ * @param {any} session
+ * @param {any} options
+ */
+export async function createPiHarnessAdapter(session, options) {
+  const originalTools = Array.isArray(options.tools) ? options.tools : [];
+  const adaptedTools = originalTools.map(adaptTool);
+  const activeToolNames = originalTools.map((tool) => tool.name);
+  // Pi 0.85 removed mixed per-tool scheduling from AgentHarness: its runner
+  // consults only this global setting. Preserve the safety contract by
+  // serializing the batch whenever any offered tool is stateful, mutating, or
+  // MCP-backed. Read-only-only tool sets can still overlap in safe-parallel.
+  const toolExecution = originalTools.some((tool) => tool?.executionMode === "sequential")
+    ? "sequential"
+    : "parallel";
+
+  /** @type {any} */
+  let created;
+  /** @type {any} */
+  let rawHarness;
+  /** @type {any} */
+  let lane;
+  let removePromptCacheDiagnostics = () => {};
+  try {
+    created = await AgentHarness.create({
+      ...options,
+      session: session.rawSession,
+      tools: adaptedTools,
+      activeToolNames,
+      toolExecution,
+      // mono-agent owns proactive/reactive compaction policy. The permanent hook
+      // below also declines Pi's overflow recovery so one bridge never runs two
+      // competing policies.
+      compaction: { enabled: false, reserveTokens: 16_384, keepRecentTokens: 20_000 },
+    }, PI_CONTEXT);
+    rawHarness = created.harness;
+    // Attach the harness before lane/configuration awaits so any later failure
+    // can close the partially constructed handle instead of wedging the repo.
+    session.attach(rawHarness, null);
+    lane = await rawHarness.lane("main", PI_CONTEXT);
+    session.attach(rawHarness, lane);
+
+    // A restored lane carries its prior configuration, so explicitly bind it to
+    // this run's model, effort, and available tools. Legacy v3 transcripts import
+    // with an empty active-tool list and are upgraded atomically by Pi on write.
+    await rawHarness.setTools(adaptedTools, PI_CONTEXT);
+    await lane.setModel({ provider: options.model.provider, modelId: options.model.id }, PI_CONTEXT);
+    await lane.setThinkingLevel(options.thinkingLevel ?? "off", PI_CONTEXT);
+    await lane.setActiveTools(activeToolNames, PI_CONTEXT);
+
+    rawHarness.hooks.on("before_compaction", (event) => (
+      event.reason === "manual" ? undefined : { decline: true }
+    ), { id: "mono-agent-compaction-owner" });
+    removePromptCacheDiagnostics = installPromptCacheDiagnostics(rawHarness, options);
+  } catch (error) {
+    try { await session.close(); } catch { /* preserve the construction error */ }
+    throw error;
+  }
+
+  let closed = false;
+  let currentModel = options.model;
+  let currentThinkingLevel = options.thinkingLevel ?? "off";
+  let currentActiveToolNames = [...activeToolNames];
+  const manuallyAppendedEntryIds = new Set();
+
+  const adapter = {
+    getPromptCacheRequest: () => promptCacheRequest(rawHarness),
+    models: options.models,
+    getModel: () => currentModel,
+    getThinkingLevel: () => currentThinkingLevel,
+    getActiveTools: () => originalTools.filter((tool) => currentActiveToolNames.includes(tool.name)),
+    async setActiveTools(names) {
+      await lane.setActiveTools(names, PI_CONTEXT);
+      currentActiveToolNames = [...names];
+    },
+    async setCompactionSettings(settings) {
+      await rawHarness.setCompactionSettings(settings, PI_CONTEXT);
+    },
+    async appendMessage(message) {
+      const entryId = await lane.appendMessage(message, PI_CONTEXT);
+      manuallyAppendedEntryIds.add(entryId);
+      return entryId;
+    },
+    // Mirror pi's own lane.prompt() (accept → drive) rather than calling it,
+    // so the operation id is known the moment Pi admits the run instead of
+    // only when it settles. The live-input epoch needs it up front: without
+    // it every steer consumed mid-run stays "pending" until the whole run
+    // ends and is only acknowledged in one batch at the end.
+    async prompt(text, promptOptions) {
+      const images = promptOptions?.images;
+      const admission = getOrThrow(await lane.accept({
+        kind: "prompt",
+        prompt: text,
+        ...(Array.isArray(images) && images.length > 0 ? { images } : {}),
+      }, PI_CONTEXT));
+      const { operationId } = admission;
+      if (typeof operationId !== "string" || operationId.length === 0) {
+        throw new Error("Pi run was admitted without an operation id");
+      }
+      promptOptions?.onOperationAdmitted?.(operationId);
+      const driven = getOrThrow(await lane.drive({ operationId, waitForRetry: true }, PI_CONTEXT));
+      if (driven.kind === "settled") return driven.outcome;
+      if (driven.kind === "waiting" && driven.reason === "deferred") {
+        return { operationId, status: "suspended", deferred: driven.deferred };
+      }
+      throw new Error(`Pi run ${operationId} returned an unwaited retry`);
+    },
+    // Pi's QueueResult carries `{ entryId }`; the live-input runner keys prompt
+    // epoch registration, `cancelQueued` and `message_end` correlation on the
+    // bare entry id, so unwrap it here (as appendMessage does) rather than hand
+    // the runner an object it would settle as "uncertain" without ever
+    // registering the steer.
+    async steer(message) {
+      const { entryId } = getOrThrow(await lane.steer(message, undefined, PI_CONTEXT));
+      if (typeof entryId !== "string" || entryId.length === 0) {
+        throw new Error("Pi steer settled without a queue entry id");
+      }
+      return entryId;
+    },
+    async cancelQueued(entryId) {
+      return getOrThrow(await lane.cancelQueued(entryId, PI_CONTEXT));
+    },
+    async abort() {
+      const result = await lane.abort(PI_CONTEXT);
+      // Aborting an already-idle lane is a benign race with prompt settlement.
+      if (!result.ok) {
+        const error = /** @type {{error: any}} */ (result).error;
+        if (error?._tag !== "NoActiveOperation") throw error;
+      }
+    },
+    waitForIdle() {
+      return lane.waitForIdle(PI_CONTEXT);
+    },
+    async compact() {
+      const value = getOrThrow(await lane.compact(undefined, PI_CONTEXT));
+      const record = value.compaction;
+      if (record.status === "failed") throw operationError(record, "Pi compaction failed");
+      if (record.status !== "completed") throw operationError(record, "Pi compaction cancelled");
+      const entry = record.tipId
+        ? await session.rawSession.getEntry(record.tipId, PI_CONTEXT)
+        : undefined;
+      if (!entry || entry.type !== "compaction") {
+        throw new Error("Pi compaction completed without a compaction entry");
+      }
+      return entry;
+    },
+    on(type, handler) {
+      if (type === "tool_result") {
+        return rawHarness.hooks.on("after_tool", (event) => handler(event));
+      }
+      if (type === "session_before_compact") {
+        return rawHarness.hooks.on("before_compaction", async (event, context) => {
+          const branchEntries = await lane.findEntries({ order: "oldestFirst" }, context);
+          const result = await handler({
+            ...event,
+            branchEntries,
+            signal: context.abortSignal,
+            context,
+          });
+          if (result?.cancel) return { decline: true };
+          return result?.compaction === undefined ? undefined : { compaction: result.compaction };
+        });
+      }
+      throw new Error(`Unsupported Pi harness hook: ${String(type)}`);
+    },
+    subscribe(listener) {
+      const removes = FORWARDED_EVENT_TYPES.map((type) => rawHarness.events.on(
+        /** @type {any} */ (type),
+        (event) => {
+          if (event.type === "message_end" && manuallyAppendedEntryIds.has(event.entryId)) return;
+          const converted = legacyEvent(event);
+          if (converted) listener(converted);
+        },
+      ));
+      return () => removes.forEach((remove) => remove());
+    },
+    async abortOpenOperations() {
+      if (!created.open.some((operation) => operation.lane === "main")) return;
+      // mono-agent tools predate Pi's invocation memo/checkpoint API, so replaying
+      // an interrupted durable operation could repeat an external side effect.
+      // Fail closed by settling it as aborted before admitting a new prompt.
+      getOrThrow(await lane.abort(PI_CONTEXT));
+      await lane.waitForIdle(PI_CONTEXT);
+    },
+    async close() {
+      if (closed) return;
+      closed = true;
+      removePromptCacheDiagnostics();
+      await session.close();
+    },
+  };
+
+  return adapter;
+}

package/src/ai/providers/pi-native/prompt-cache-diagnostics.js

@@ -0,0 +1,103 @@
+import { createHash, randomUUID } from "node:crypto";
+
+const activeRequests = new WeakMap();
+export const promptCacheRequest = (harness) => activeRequests.get(harness);
+
+const MAX_MESSAGE_FINGERPRINTS = 128;
+const safeString = (value) => typeof value === "string" ? value.slice(0, 160) : undefined;
+const serialized = (value) => JSON.stringify(value) ?? "null";
+const fingerprint = (value) => createHash("sha256").update(serialized(value)).digest("hex").slice(0, 16);
+const bytes = (value) => value == null ? 0 : Buffer.byteLength(typeof value === "string" ? value : serialized(value));
+const record = (value) => value !== null && typeof value === "object" && !Array.isArray(value) ? value : undefined;
+const list = (value) => Array.isArray(value) ? value : [];
+
+function normalizedPayload(event) {
+  const payload = record(event?.payload);
+  if (!payload) return { family: "unsupported", reason: "payload_not_object" };
+  const api = safeString(event?.model?.api) ?? "unknown";
+  if (api === "google-generative-ai" || api === "google-vertex") {
+    const config = record(payload.config) ?? {};
+    const tools = list(config.tools).flatMap((tool) => list(record(tool)?.functionDeclarations).length > 0
+      ? list(record(tool)?.functionDeclarations) : [tool]);
+    return { family: "google", system: config.systemInstruction ?? null, tools, messages: list(payload.contents), payload };
+  }
+  if (api === "pi-messages") {
+    const context = record(payload.context);
+    if (context && ("messages" in context || "systemPrompt" in context || "tools" in context)) {
+      return { family: "pi-messages", system: context.systemPrompt ?? null, tools: list(context.tools), messages: list(context.messages), payload };
+    }
+  }
+  if (api === "bedrock-converse-stream") {
+    return { family: "bedrock", system: payload.system ?? null, tools: list(record(payload.toolConfig)?.tools), messages: list(payload.messages), payload };
+  }
+  if (api === "anthropic-messages") {
+    return { family: "anthropic", system: payload.system ?? null, tools: list(payload.tools), messages: list(payload.messages), payload };
+  }
+  if (["openai-responses", "azure-openai-responses", "openai-codex-responses"].includes(api)) {
+    return { family: api === "openai-codex-responses" ? "openai-codex" : "openai-responses", system: payload.instructions ?? null, tools: list(payload.tools), messages: list(payload.input), payload };
+  }
+  return { family: "unsupported", reason: `unrecognized_api:${api}` };
+}
+
+function cacheMetadata(payload, family) {
+  const disabled = payload.prompt_cache_retention === "none" || record(payload.options)?.cacheRetention === "none";
+  const key = payload.prompt_cache_key ?? payload.cache_key ?? payload.cachedContent
+    ?? (family === "pi-messages" ? record(payload.options)?.sessionId : undefined);
+  let explicit = false;
+  const pending = [{ value: payload, depth: 0 }];
+  let visited = 0;
+  while (pending.length > 0 && visited < 10_000) {
+    const { value, depth } = pending.pop();
+    visited += 1;
+    if (depth > 12 || value === null || typeof value !== "object") continue;
+    for (const [name, child] of Object.entries(value)) {
+      if (["cache_control", "cachePoint", "cache_point", "prompt_cache_retention", "prompt_cache_options"].includes(name) && child != null) explicit = true;
+      if (typeof child === "object" && child !== null) pending.push({ value: child, depth: depth + 1 });
+    }
+  }
+  return {
+    cacheMode: disabled ? "disabled" : [key === undefined ? "" : "keyed", explicit ? "explicit" : ""].filter(Boolean).join("+") || "provider-default",
+    ...(disabled || key === undefined ? {} : { cacheKeyFingerprint: fingerprint(key) }),
+  };
+}
+
+/** Install a metadata-only, request-lifecycle-bounded Pi payload diagnostic. */
+export function installPromptCacheDiagnostics(harness, options) {
+  if (options.promptCacheDiagnostics !== true || typeof options.onEvent !== "function") return () => {};
+  let ordinal = 0;
+  const remove = harness.hooks.on("before_payload", (event) => {
+    const correlation = { phase: "assistant", requestId: randomUUID() };
+    activeRequests.set(harness, correlation);
+    const normalized = normalizedPayload(event);
+    const model = event?.model ?? options.model ?? {};
+    const base = {
+      type: "prompt_cache_diagnostic",
+      ...correlation,
+      requestOrdinal: ++ordinal,
+      model: [safeString(model.provider), safeString(model.id)].filter(Boolean).join(":") || "unknown",
+      api: safeString(model.api) ?? "unknown",
+      payloadFamily: normalized.family,
+    };
+    if (normalized.family === "unsupported") {
+      options.onEvent({ ...base, supported: false, unsupportedReason: normalized.reason });
+      return;
+    }
+    const messages = normalized.messages;
+    const logicalInputInterpretation = normalized.payload.previous_response_id === undefined ? "full" : "delta";
+    const codexWireUnknown = normalized.family === "openai-codex" && logicalInputInterpretation === "full";
+    options.onEvent({
+      ...base,
+      supported: true,
+      systemBytes: bytes(normalized.system), systemFingerprint: fingerprint(normalized.system),
+      toolDefinitionCount: normalized.tools.length, toolDefinitionsFingerprint: fingerprint(normalized.tools),
+      messageCount: messages.length,
+      messageFingerprints: messages.slice(0, MAX_MESSAGE_FINGERPRINTS).map(fingerprint),
+      messageFingerprintsTruncated: messages.length > MAX_MESSAGE_FINGERPRINTS,
+      ...cacheMetadata(normalized.payload, normalized.family),
+      logicalInputInterpretation,
+      inputInterpretation: codexWireUnknown ? "unavailable" : logicalInputInterpretation,
+      inputInterpretationSource: codexWireUnknown ? "pre_transport_payload" : "provider_payload",
+    });
+  }, { id: "mono-agent-prompt-cache-diagnostics" });
+  return () => { activeRequests.delete(harness); remove(); };
+}

package/src/ai/providers/pi-native/provider-attribution.js

@@ -0,0 +1,102 @@
+// @ts-check
+
+const OPENCODE_HOST = "opencode.ai";
+const OPENCODE_PROVIDERS = new Set(["opencode", "opencode-go"]);
+const REQUEST_METHODS = new Set([
+  "stream",
+  "complete",
+  "streamSimple",
+  "completeSimple",
+  "streamDeferred",
+  "fetchDeferred",
+  "cancelDeferred",
+]);
+
+/** @typedef {import("@earendil-works/pi-ai").Models} Models */
+/** @typedef {import("@earendil-works/pi-ai").ProviderHeaders} ProviderHeaders */
+
+/**
+ * Match Pi's OpenCode attribution boundary without accepting deceptive suffixes
+ * or subdomains. Provider ids remain authoritative for callers that deliberately
+ * route OpenCode through a nonstandard endpoint.
+ *
+ * @param {{provider?: string, baseUrl?: string}} model
+ */
+export function isOpenCodeModel(model) {
+  if (OPENCODE_PROVIDERS.has(model?.provider)) return true;
+  if (typeof model?.baseUrl !== "string") return false;
+  try {
+    return new URL(model.baseUrl).hostname === OPENCODE_HOST;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Add one default without replacing an auth/model/request value, including a
+ * caller's case-insensitive null suppression.
+ *
+ * @param {ProviderHeaders} headers
+ * @param {string} name
+ * @param {string} value
+ * @returns {ProviderHeaders}
+ */
+function addDefaultHeader(headers, name, value) {
+  const lowerName = name.toLowerCase();
+  if (Object.keys(headers).some((existingName) => existingName.toLowerCase() === lowerName)) {
+    return headers;
+  }
+  return { ...headers, [name]: value };
+}
+
+/**
+ * @param {Object<string, *>|undefined} options
+ * @param {string} sessionId
+ * @returns {Object<string, *>}
+ */
+function withOpenCodeHeaderTransform(options, sessionId) {
+  const previousTransform = options?.transformHeaders;
+  return {
+    ...(options ?? {}),
+    transformHeaders: async (headers) => {
+      let attributed = addDefaultHeader(headers, "x-opencode-session", sessionId);
+      attributed = addDefaultHeader(attributed, "x-opencode-client", "mono-agent");
+      return typeof previousTransform === "function"
+        ? await previousTransform(attributed)
+        : attributed;
+    },
+  };
+}
+
+/**
+ * Decorate every Pi Models request path for one run. Non-request methods stay
+ * bound to the original Models instance because its state lives in private
+ * fields; matching is performed on the actual model dispatched by Pi, covering
+ * builtin, custom-provider, compaction, deferred, and advanced/test models.
+ *
+ * @param {Models} models
+ * @param {string} sessionId
+ * @returns {Models}
+ */
+export function withOpenCodeSessionHeaders(models, sessionId) {
+  const wrappers = new Map();
+  return /** @type {Models} */ (new Proxy(models, {
+    get(target, property) {
+      const value = Reflect.get(target, property, target);
+      if (typeof property !== "string" || typeof value !== "function") return value;
+      if (!REQUEST_METHODS.has(property)) return value.bind(target);
+
+      let wrapper = wrappers.get(property);
+      if (wrapper === undefined) {
+        wrapper = (model, input, options) => value.call(
+          target,
+          model,
+          input,
+          isOpenCodeModel(model) ? withOpenCodeHeaderTransform(options, sessionId) : options,
+        );
+        wrappers.set(property, wrapper);
+      }
+      return wrapper;
+    },
+  }));
+}