@mono-agent/agent-runtime 0.20.14 → 0.21.0

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

@@ -9,6 +9,7 @@ import {
   createCompactionSummaryMessage,
   getOrThrow,
 } from "@earendil-works/pi-agent-core";
+import { installPromptCacheDiagnostics, promptCacheRequest } from "./prompt-cache-diagnostics.js";
 
 export const PI_CONTEXT = BACKGROUND_CONTEXT;
 
@@ -201,6 +202,7 @@ export async function createPiHarnessAdapter(session, options) {
   let rawHarness;
   /** @type {any} */
   let lane;
+  let removePromptCacheDiagnostics = () => {};
   try {
     created = await AgentHarness.create({
       ...options,
@@ -231,6 +233,7 @@ export async function createPiHarnessAdapter(session, options) {
     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;
@@ -243,6 +246,7 @@ export async function createPiHarnessAdapter(session, options) {
   const manuallyAppendedEntryIds = new Set();
 
   const adapter = {
+    getPromptCacheRequest: () => promptCacheRequest(rawHarness),
     models: options.models,
     getModel: () => currentModel,
     getThinkingLevel: () => currentThinkingLevel,
@@ -259,11 +263,44 @@ export async function createPiHarnessAdapter(session, options) {
       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) {
-      return getOrThrow(await lane.prompt(text, promptOptions?.images, PI_CONTEXT));
+      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) {
-      return getOrThrow(await lane.steer(message, undefined, PI_CONTEXT));
+      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);
@@ -330,6 +367,7 @@ export async function createPiHarnessAdapter(session, options) {
     async close() {
       if (closed) return;
       closed = true;
+      removePromptCacheDiagnostics();
       await session.close();
     },
   };

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;
+    },
+  }));
+}

package/src/ai/providers/pi-native/result-builder.js

@@ -32,6 +32,24 @@ export function usageFromMessages(messages = []) {
   return usage;
 }
 
+/**
+ * Pi initializes failed assistant messages with an all-zero usage object before
+ * any provider telemetry arrives. A successful response makes those zeros
+ * measured; a failed response is measured only when real usage is non-zero.
+ * @param {Array<any>} [messages]
+ */
+export function hasMeasuredUsage(messages = []) {
+  return messages.some((message) => {
+    if (message?.role !== "assistant" || !message.usage) return false;
+    if (message.stopReason !== "error" && message.stopReason !== "aborted") return true;
+    const usage = message.usage;
+    return [usage.input, usage.output, usage.cacheRead, usage.cacheWrite, usage.totalTokens,
+      usage.cost?.input, usage.cost?.output, usage.cost?.cacheRead,
+      usage.cost?.cacheWrite, usage.cost?.total]
+      .some((value) => Number.isFinite(Number(value)) && Number(value) > 0);
+  });
+}
+
 /**
  * Add what this run's subagents spent to the run's own usage.
  *
@@ -70,7 +88,7 @@ export function withSubagentUsage(usage, delegated, estimatedCost) {
  * requests in the run: the last assistant usage is the same provider-counted
  * value Pi's compaction logic trusts, so it can decrease after compaction.
  * @param {any} assistantMessage
- * @returns {{input: number, output: number, cacheRead: number, cacheCreation: number, total: number}|null}
+ * @returns {{input: number, output: number, cacheRead: number, cacheCreation: number, total: number, costUsd: number}|null}
  */
 export function contextUsageFromAssistantMessage(assistantMessage) {
   if (assistantMessage?.role !== "assistant" || !assistantMessage.usage) return null;
@@ -83,6 +101,7 @@ export function contextUsageFromAssistantMessage(assistantMessage) {
     cacheRead: Number(assistantMessage.usage.cacheRead) || 0,
     cacheCreation: Number(assistantMessage.usage.cacheWrite) || 0,
     total,
+    costUsd: Number(assistantMessage.usage.cost?.total) || 0,
   };
 }
 
@@ -211,6 +230,8 @@ export function buildSuccessResult(params) {
     runtimeWarnings,
     capabilitiesUsed,
     structuredResult,
+    usageMeasured = true,
+    effectiveEffort,
   } = params;
   return {
     text: finalText,
@@ -219,15 +240,16 @@ export function buildSuccessResult(params) {
     usage: {
       input_tokens: usage.input || null,
       output_tokens: usage.output || null,
-      cache_read_tokens: usage.cacheRead || null,
-      cache_creation_tokens: usage.cacheWrite || null,
-      cache_write_tokens: usage.cacheWrite || null,
+      cache_read_tokens: usageMeasured ? usage.cacheRead : null,
+      cache_creation_tokens: usageMeasured ? usage.cacheWrite : null,
+      cache_write_tokens: usageMeasured ? usage.cacheWrite : null,
       cost_usd: usage.cost || estimatedCost,
     },
     durationMs: Date.now() - start,
     numTurns: turnCount || runAssistantCount,
     model: resolved.reference || `${resolved.provider}:${resolved.model}`,
     effort: options.effort || null,
+    effectiveEffort: effectiveEffort || null,
     sdk: "pi",
     cancelled: externalAbort,
     error: errorMessage,
@@ -266,6 +288,7 @@ export function buildErrorResult(params) {
     runtimeWarnings,
     isRetryable,
     piTransport,
+    effectiveEffort,
   } = params;
   return {
     text: assistantTexts.join("") || null,
@@ -275,6 +298,7 @@ export function buildErrorResult(params) {
     numTurns: turnCount,
     model: resolved?.reference || (resolved?.provider && resolved?.model ? `${resolved.provider}:${resolved.model}` : null),
     effort: options.effort || null,
+    effectiveEffort: effectiveEffort || null,
     sdk: "pi",
     cancelled: externalAbort,
     error: externalAbort ? null : errorMessage,