@mono-agent/agent-runtime 0.1.0

package/src/ai/runtime/sessions.js

@@ -0,0 +1,126 @@
+// Provider session registries.
+//
+// Bridges that support continuous provider sessions (codex-app keeps the
+// app-server subprocess + thread alive, pi-sdk keeps a pi Session transcript)
+// register their live sessions here, keyed by provider session id. The host
+// owns session lifetime policy (which conversation maps to which session,
+// when to resume, when to retire); these registries only make sure nothing
+// leaks if the host forgets: every entry carries an idle TTL backstop with an
+// unref'd timer plus a lazy wall-clock check, so a stalled timer (laptop
+// sleep) still cannot resurrect an expired session.
+//
+// `createSessionRegistry` instances self-register in a module-level set so
+// the runtime surface can expose `disposeSession(id)` / `disposeAllSessions()`
+// without knowing which bridge owns the id. Provider session ids are unique
+// across bridges (codex thread ids, pi uuids), so fan-out dispose is safe.
+
+const DEFAULT_IDLE_TIMEOUT_MS = 30 * 60 * 1000;
+
+const allRegistries = new Set();
+
+function normalizeTtl(value, fallback) {
+  const n = Number(value);
+  if (!Number.isFinite(n) || n < 1_000) return fallback;
+  return n;
+}
+
+export function createSessionRegistry({ idleTimeoutMs = DEFAULT_IDLE_TIMEOUT_MS, onEvict, now = Date.now, isBusy } = {}) {
+  const entries = new Map();
+  const defaultTtlMs = normalizeTtl(idleTimeoutMs, DEFAULT_IDLE_TIMEOUT_MS);
+
+  async function evict(id, reason) {
+    const entry = entries.get(id);
+    if (!entry) return false;
+    if (reason === "idle_timeout" && isBusy?.(entry.value)) {
+      // A session executing a turn must not be torn down by the idle timer;
+      // give it a fresh TTL window. Explicit dispose still wins.
+      entry.lastActivityAt = now();
+      armTimer(id, entry);
+      return false;
+    }
+    entries.delete(id);
+    clearTimeout(entry.timer);
+    if (onEvict) {
+      try {
+        await onEvict(entry.value, reason);
+      } catch {
+        // Eviction cleanup is best-effort; a failed close must not block
+        // the registry from forgetting the session.
+      }
+    }
+    return true;
+  }
+
+  function armTimer(id, entry) {
+    clearTimeout(entry.timer);
+    entry.timer = setTimeout(() => {
+      void evict(id, "idle_timeout");
+    }, entry.ttlMs);
+    entry.timer.unref?.();
+  }
+
+  const registry = {
+    get(id) {
+      const entry = entries.get(id);
+      if (!entry) return undefined;
+      if (now() - entry.lastActivityAt > entry.ttlMs && !isBusy?.(entry.value)) {
+        void evict(id, "idle_timeout");
+        return undefined;
+      }
+      return entry.value;
+    },
+    set(id, value, { idleTimeoutMs: entryTtl } = {}) {
+      const previous = entries.get(id);
+      if (previous) clearTimeout(previous.timer);
+      const entry = { value, lastActivityAt: now(), timer: null, ttlMs: normalizeTtl(entryTtl, defaultTtlMs) };
+      entries.set(id, entry);
+      armTimer(id, entry);
+    },
+    touch(id, { idleTimeoutMs: entryTtl } = {}) {
+      const entry = entries.get(id);
+      if (!entry) return;
+      if (entryTtl !== undefined) entry.ttlMs = normalizeTtl(entryTtl, entry.ttlMs);
+      entry.lastActivityAt = now();
+      armTimer(id, entry);
+    },
+    has(id) {
+      return registry.get(id) !== undefined;
+    },
+    /** Remove without running onEvict — for callers that already cleaned up. */
+    delete(id) {
+      const entry = entries.get(id);
+      if (!entry) return false;
+      entries.delete(id);
+      clearTimeout(entry.timer);
+      return true;
+    },
+    async dispose(id) {
+      return evict(id, "disposed");
+    },
+    async disposeAll() {
+      const ids = [...entries.keys()];
+      for (const id of ids) await evict(id, "disposed");
+    },
+    size() {
+      return entries.size;
+    },
+  };
+
+  allRegistries.add(registry);
+  return registry;
+}
+
+export async function disposeProviderSession(providerSessionId) {
+  if (typeof providerSessionId !== "string" || !providerSessionId.trim()) return false;
+  let disposed = false;
+  for (const registry of allRegistries) {
+    if (await registry.dispose(providerSessionId)) disposed = true;
+  }
+  return disposed;
+}
+
+export async function disposeAllProviderSessions() {
+  for (const registry of allRegistries) {
+    await registry.disposeAll();
+  }
+}

package/src/ai/streaming/codex-events.js

@@ -0,0 +1,139 @@
+const CODEX_ITEM_EVENTS = new Set(["item.started", "item.completed"]);
+
+export function normalizeCodexItemType(type) {
+  if (type === "commandExecution") return "command_execution";
+  if (type === "mcpToolCall") return "mcp_tool_call";
+  if (type === "fileChange") return "file_change";
+  if (type === "agentMessage") return "agent_message";
+  return type || "";
+}
+
+function isCompleted(raw) {
+  return raw?.type === "item.completed";
+}
+
+function itemId(item, fallback) {
+  return item?.id || fallback;
+}
+
+function itemStatus(item, raw) {
+  return item?.status || (isCompleted(raw) ? "completed" : "in_progress");
+}
+
+function itemFailed(item) {
+  const status = String(item?.status || "").toLowerCase();
+  const exitCode = item?.exit_code ?? item?.exitCode;
+  return Boolean(
+    item?.error ||
+    status === "failed" ||
+    status === "errored" ||
+    status === "error" ||
+    (typeof exitCode === "number" && exitCode !== 0),
+  );
+}
+
+function commandOutput(item) {
+  return item?.aggregated_output ?? item?.aggregatedOutput ?? item?.output ?? "";
+}
+
+function mcpToolName(item) {
+  return item?.server && item?.tool
+    ? `mcp__${item.server}__${item.tool}`
+    : item?.tool || "mcp_tool_call";
+}
+
+function mcpResultContent(item) {
+  if (item?.error) return item.error;
+  if (item?.result?.structuredContent != null) return item.result.structuredContent;
+  if (item?.result?.structured_content != null) return item.result.structured_content;
+  if (item?.result?.content != null) return item.result.content;
+  return item?.result || "";
+}
+
+function fileChangePayload(raw, item, context = {}) {
+  if (typeof context.fileChangePayload === "function") {
+    const payload = context.fileChangePayload(raw, item);
+    if (payload) return payload;
+  }
+  return {
+    changes: Array.isArray(item.changes) ? item.changes : [],
+    status: itemStatus(item, raw),
+    ...(item.summary ? { summary: item.summary } : {}),
+  };
+}
+
+export function normalizeCodexItemEvent(raw, context = {}) {
+  if (!raw || !CODEX_ITEM_EVENTS.has(raw.type) || !raw.item) return null;
+  const item = raw.item;
+  const type = normalizeCodexItemType(item.type);
+
+  if (type === "file_change") {
+    const id = itemId(item, "file_change");
+    const payload = fileChangePayload(raw, item, context);
+    if (!isCompleted(raw)) {
+      return {
+        type: "assistant",
+        message: { content: [{ type: "tool_use", id, name: "file_edit", input: payload }] },
+      };
+    }
+    return {
+      type: "user",
+      message: {
+        content: [{
+          type: "tool_result",
+          tool_use_id: id,
+          content: item.error || payload,
+          is_error: itemFailed(item),
+        }],
+      },
+    };
+  }
+
+  if (type === "mcp_tool_call") {
+    const id = itemId(item, `${item.server || "mcp"}:${item.tool || "tool"}`);
+    if (!isCompleted(raw)) {
+      return {
+        type: "assistant",
+        message: { content: [{ type: "tool_use", id, name: mcpToolName(item), input: item.arguments || {} }] },
+      };
+    }
+    return {
+      type: "user",
+      message: {
+        content: [{
+          type: "tool_result",
+          tool_use_id: id,
+          content: mcpResultContent(item),
+          is_error: itemFailed(item),
+        }],
+      },
+    };
+  }
+
+  if (type === "command_execution") {
+    const id = itemId(item, item.command || "command_execution");
+    if (!isCompleted(raw)) {
+      return {
+        type: "assistant",
+        message: { content: [{ type: "tool_use", id, name: "command_execution", input: { command: item.command || "" } }] },
+      };
+    }
+    return {
+      type: "user",
+      message: {
+        content: [{
+          type: "tool_result",
+          tool_use_id: id,
+          content: commandOutput(item),
+          is_error: itemFailed(item),
+        }],
+      },
+    };
+  }
+
+  if (type === "agent_message" && isCompleted(raw) && typeof item.text === "string") {
+    return { type: "assistant", message: { content: [{ type: "text", text: item.text }] } };
+  }
+
+  return null;
+}

package/src/ai/streaming/opencode-events.js

@@ -0,0 +1,54 @@
+// Normalizes OpenCode message parts (from `message.part.updated` events and the
+// final `session.prompt` response) into the Anthropic-shaped RuntimeEvents the
+// rest of the runtime/transcript layer consumes. Sibling of codex-events.js.
+//
+// OpenCode part shapes (from @opencode-ai/sdk types.gen):
+//   ToolPart      { type:"tool", callID, tool, state:{ status, input, output?, error? } }
+//   ReasoningPart { type:"reasoning", text }
+//   TextPart      { type:"text", text }
+
+export function toolUseEvent(part) {
+  return {
+    type: "assistant",
+    message: {
+      content: [{ type: "tool_use", id: part.callID, name: part.tool, input: part.state?.input || {} }],
+    },
+  };
+}
+
+export function toolResultEvent(part) {
+  const state = part.state || {};
+  const isError = state.status === "error";
+  return {
+    type: "user",
+    message: {
+      content: [{
+        type: "tool_result",
+        tool_use_id: part.callID,
+        content: isError ? (state.error || "") : (state.output || ""),
+        is_error: isError,
+      }],
+    },
+  };
+}
+
+export function thinkingEvent(part) {
+  return {
+    type: "assistant",
+    message: { content: [{ type: "thinking", text: part.text || "" }] },
+  };
+}
+
+export function assistantTextEvent(text) {
+  return {
+    type: "assistant",
+    message: { content: [{ type: "text", text: text || "" }] },
+  };
+}
+
+// A tool part is "settled" once it has produced output or errored — that's when
+// we emit the tool_result half of the pair.
+export function toolPartSettled(part) {
+  const status = part?.state?.status;
+  return status === "completed" || status === "error";
+}

package/src/ai/types.js

@@ -0,0 +1,70 @@
+// Runtime contracts. These are JSDoc-only; the codebase is JS
+// (no TypeScript), so the types document the bridge surface that active
+// runtimes implement through src/ai/runtime/registry.js.
+
+/**
+ * @typedef {Object} RuntimeModelRef
+ * @property {"claude" | "pi" | "codex"} sdk Canonical active runtime id.
+ * @property {string} model              Provider model id.
+ * @property {string} reference          Original canonical model reference.
+ * @property {string} [provider]         Pi provider id when sdk === "pi".
+ */
+
+/**
+ * @typedef {Object} RuntimeRequest
+ * @property {string} systemPrompt
+ * @property {Array<Object>} messages
+ * @property {RuntimeModelRef} model
+ * @property {string} [effort]
+ * @property {boolean} [fastMode]
+ * @property {string} [cwd]
+ * @property {Object<string, Object>} [mcpServers]
+ * @property {Array<string>} [allowedTools]
+ * @property {Array<string>} [disallowedTools]
+ * @property {string} [permissionMode]
+ * @property {number} [maxTurns]
+ * @property {Object} [outputSchema]
+ * @property {string} [runArtifactDir]
+ * @property {AbortSignal} [abortSignal]
+ * @property {Object} [liveInput]
+ * @property {"auto"|"concise"|"detailed"|"off"|"on"|null} [piReasoningSummary]
+ * @property {Object} [settings]
+ * @property {Object} [nativeSubagents] Same-runtime teammate helpers exposed through native provider subagent surfaces.
+ * @property {(event: RuntimeEvent) => void} [onEvent]
+ */
+
+/**
+ * @typedef {Object} RuntimeEvent
+ * @property {string} type
+ */
+
+/**
+ * @typedef {Object} RuntimeResult
+ * @property {string|null} [text]
+ * @property {*} [structuredResult]
+ * @property {string|null} [structuredResultSource]
+ * @property {Array<RuntimeEvent>} [events]
+ * @property {Object} [usage]
+ * @property {number} [durationMs]
+ * @property {number} [numTurns]
+ * @property {string} [model]
+ * @property {string} [effort]
+ * @property {"claude" | "pi" | "codex"} [sdk]
+ * @property {boolean} [cancelled]
+ * @property {string|null} [error]
+ * @property {Object|null} [errorDetails]
+ * @property {string|null} [failureKind]
+ * @property {string|null} [providerSessionId]
+ * @property {Array<Object>} [runtimeWarnings]
+ * @property {Object} [diagnostics]
+ */
+
+/**
+ * @typedef {Object} RuntimeBridge
+ * @property {"claude" | "pi" | "codex"} id
+ * @property {(ref: RuntimeModelRef) => boolean} supports
+ * @property {(ref?: RuntimeModelRef) => Object} capabilities
+ * @property {(systemPrompt: string, req: RuntimeRequest) => Promise<RuntimeResult>} execute
+ */
+
+export const PROVIDER_KIND_VALUES = ["claude", "pi", "codex"];

package/src/index.js

@@ -0,0 +1,23 @@
+// Public entry for @mono-agent/agent-runtime.
+//
+// Most consumers should reach for `createRuntime` (see runtime.js) — it
+// binds the host integration callbacks once and returns a `.run()` method.
+// The named exports below remain available for advanced use cases (custom
+// bridge registration, direct provider invocation, tool-runtime introspection).
+
+export { createRuntime } from "./runtime.js";
+export { createPiOAuthApiKeyResolver } from "./pi-auth.js";
+export { createRouterRuntime } from "./ai/runtime/router.js";
+export {
+  configureToolRuntime,
+  readToolRuntime,
+  readRuntimeBrand,
+  resetToolRuntime,
+} from "./agent/tools/shared/runtime-context.js";
+export {
+  DEFAULT_RUNTIME_BRAND,
+  resolveRuntimeBrand,
+} from "./runtime-brand.js";
+
+export * from "./ai/index.js";
+export * from "./agent/index.js";

package/src/pi-auth.js

@@ -0,0 +1,80 @@
+import { chmod, mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+
+import { getOAuthApiKey } from "@earendil-works/pi-ai/oauth";
+
+export function createPiOAuthApiKeyResolver(options = {}) {
+  const authPath = typeof options.path === "string" && options.path.trim().length > 0
+    ? options.path
+    : undefined;
+
+  return async function resolvePiOAuthApiKey(provider) {
+    if (!authPath || typeof provider !== "string" || provider.trim().length === 0) {
+      return undefined;
+    }
+
+    const auth = await readAuthFile(authPath);
+    if (auth === undefined || auth[provider] === undefined) {
+      return undefined;
+    }
+
+    const result = await getOAuthApiKey(provider, cloneAuth(auth));
+    if (result === null || result === undefined || typeof result.apiKey !== "string" || result.apiKey.length === 0) {
+      return undefined;
+    }
+
+    auth[provider] = {
+      type: "oauth",
+      ...result.newCredentials,
+    };
+    await writeAuthFile(authPath, auth);
+    return result.apiKey;
+  };
+}
+
+function cloneAuth(auth) {
+  return Object.fromEntries(
+    Object.entries(auth).map(([provider, credentials]) => [
+      provider,
+      credentials && typeof credentials === "object" && !Array.isArray(credentials)
+        ? { ...credentials }
+        : credentials,
+    ]),
+  );
+}
+
+async function readAuthFile(path) {
+  let raw;
+  try {
+    raw = await readFile(path, "utf8");
+  } catch (error) {
+    if (error && error.code === "ENOENT") {
+      return undefined;
+    }
+    throw error;
+  }
+
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      return parsed;
+    }
+  } catch (error) {
+    throw new Error(`Unable to parse Pi auth file at ${path}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  throw new Error(`Unable to parse Pi auth file at ${path}: expected a JSON object`);
+}
+
+// The temp name carries a per-process sequence (not a timestamp) so concurrent
+// writers in the same millisecond never collide on the temp path.
+let atomicWriteSequence = 0;
+
+async function writeAuthFile(path, auth) {
+  const dir = dirname(path);
+  await mkdir(dir, { recursive: true, mode: 0o700 });
+  atomicWriteSequence += 1;
+  const tmpPath = `${path}.tmp-${process.pid}-${atomicWriteSequence}`;
+  await writeFile(tmpPath, `${JSON.stringify(auth, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+  await rename(tmpPath, path);
+  await chmod(path, 0o600);
+}

package/src/runtime-brand.js

@@ -0,0 +1,32 @@
+// Host-customisable identity strings used by the runtime when it has to
+// stamp a name onto something that leaves the process: MCP client name,
+// transcript-snapshot schema id, temp-directory prefix, the doctor command
+// suggested in tool error messages, etc.
+//
+// The runtime ships with neutral defaults. External hosts pass `runtimeBrand`
+// to `createRuntime` to make the package look like theirs without forking
+// string-by-string.
+
+export const DEFAULT_RUNTIME_BRAND = Object.freeze({
+  schemaPrefix: "agent_runtime",
+  mcpClientName: "agent-runtime",
+  mcpClientVersion: "0.1.0",
+  tempdirPrefix: "agent-runtime-cli-",
+  providerModelPrefix: "agent",
+  doctorCommand: "agent-runtime doctor",
+  // serviceName + clientInfo names propagated to provider SDKs that report
+  // a client identity (Codex app-server, etc.).
+  serviceName: "agent-runtime",
+  clientInfoName: "agent-runtime",
+  clientInfoTitle: "Agent Runtime",
+});
+
+export function resolveRuntimeBrand(input) {
+  if (!input || typeof input !== "object") return { ...DEFAULT_RUNTIME_BRAND };
+  const out = { ...DEFAULT_RUNTIME_BRAND };
+  for (const key of Object.keys(DEFAULT_RUNTIME_BRAND)) {
+    const value = input[key];
+    if (typeof value === "string" && value.trim()) out[key] = value.trim();
+  }
+  return out;
+}

package/src/runtime.js

@@ -0,0 +1,104 @@
+// Top-level runtime factory.
+//
+// `createRuntime(host)` is the ergonomic entry point for hosts. It binds the
+// host integration callbacks (pricing, persistence, credentials), configures
+// the module-level tool runtime, and returns a `.run(systemPrompt, options)`
+// method that resolves the right provider bridge based on `options.model` +
+// `options.executionMode`.
+//
+// All four built-in bridges (claude-sdk, claude-cli, pi-sdk, codex-app)
+// register themselves on import via the runtime registry. Hosts that need
+// finer control can keep using the named exports (resolveRuntimeBridge,
+// generateClaudeResponse, etc.) directly.
+//
+// Return shape from `.run()`:
+//   { text, structuredResult, structuredResultSource, events, usage,
+//     durationMs, numTurns, model, effort, sdk, cancelled, error,
+//     errorDetails, failureKind, providerSessionId, runtimeWarnings,
+//     diagnostics }
+//
+// `text` is the raw assistant text. `structuredResult` is whatever JSON the
+// agent returned via the configured outputSchema (undefined when no schema
+// was supplied). Hosts that want a domain-specific contract (for example,
+// a product-specific result object,
+// task envelopes, etc.) parse it themselves.
+
+import { resolveRuntimeBridge } from "./ai/runtime/registry.js";
+import { createObserverHub } from "./ai/observer.js";
+import { disposeAllProviderSessions, disposeProviderSession } from "./ai/runtime/sessions.js";
+import { configureToolRuntime } from "./agent/tools/shared/runtime-context.js";
+import { resolveRuntimeBrand } from "./runtime-brand.js";
+
+const HOST_KEYS = [
+  "resolveCustomPricing",
+  "resolvePiApiKey",
+  "persistArtifact",
+  "onCompactionRecorded",
+  "onToolApprovalRequest",
+  "toolRiskTiers",
+  "approvalDefaultRiskTier",
+  "approvalTimeoutMs",
+  "approvalAlwaysAllowTools",
+];
+
+const TOOL_RUNTIME_KEYS = [
+  "workspace",
+  "repoRoot",
+  "ripgrepPath",
+  "qaOutputDir",
+  "sandboxPolicy",
+];
+
+function pickDefined(source, keys) {
+  const out = {};
+  for (const key of keys) {
+    if (source && source[key] !== undefined) out[key] = source[key];
+  }
+  return out;
+}
+
+export function createRuntime(host = {}) {
+  const hostDefaults = pickDefined(host, HOST_KEYS);
+  const toolRuntime = pickDefined(host, TOOL_RUNTIME_KEYS);
+  const runtimeBrand = resolveRuntimeBrand(host.runtimeBrand);
+  const hostObservers = Array.isArray(host.observers) ? host.observers.slice() : [];
+  // Always configure: even when no tool keys are supplied, we must publish
+  // the resolved brand so internal modules (transcript, pi-bridge, ripgrep
+  // error message) pick it up.
+  configureToolRuntime({ ...toolRuntime, runtimeBrand });
+
+  return {
+    async run(systemPrompt, options = {}) {
+      if (!options.model) throw new Error("createRuntime.run requires options.model");
+      const executionMode = typeof options.executionMode === "string" ? options.executionMode : "sdk";
+      const bridge = await resolveRuntimeBridge(options.model, {
+        liveInput: !!options.liveInput,
+        executionMode,
+      });
+      const callObservers = Array.isArray(options.observers) ? options.observers : [];
+      const hub = createObserverHub({
+        observers: [...hostObservers, ...callObservers],
+        onEvent: options.onEvent,
+      });
+      const result = await bridge.execute(systemPrompt, {
+        ...hostDefaults,
+        ...options,
+        executionMode,
+        runtimeBrand,
+        observerHub: hub,
+        onEvent: hub.emit,
+      });
+      await hub.flush();
+      return result;
+    },
+    configureTools(next = {}) {
+      configureToolRuntime(pickDefined(next, TOOL_RUNTIME_KEYS));
+    },
+    async disposeSession(providerSessionId) {
+      return disposeProviderSession(providerSessionId);
+    },
+    async disposeAllSessions() {
+      return disposeAllProviderSessions();
+    },
+  };
+}