march-cli 0.1.0

package/src/agent/model-payload-dumper.mjs

@@ -0,0 +1,201 @@
+import { stripAnsi } from "../text/ansi.mjs";
+
+export { appendProviderUserMessage, replaceProviderContextMessages, replaceProviderSystemPrompt } from "./provider/payload-messages.mjs";
+
+const MODEL_PAYLOAD_DUMPER_INSTALLED = Symbol("march.modelPayloadDumperInstalled");
+
+export function installModelPayloadDumper(session, modelContextDumper, getKind = () => "model", onModelPayload = null, transformPayload = null) {
+  if ((!modelContextDumper?.enabled && typeof onModelPayload !== "function" && typeof transformPayload !== "function") || !session?.agent) return;
+  const agent = session.agent;
+  if (agent[MODEL_PAYLOAD_DUMPER_INSTALLED]) return;
+  const originalOnPayload = agent.onPayload;
+  agent.onPayload = async (payload, model) => {
+    const replacement = originalOnPayload ? await originalOnPayload(payload, model) : undefined;
+    const originalEffectivePayload = replacement === undefined ? payload : replacement;
+    const kind = getKind();
+    const effectivePayload = typeof transformPayload === "function"
+      ? transformPayload(originalEffectivePayload, { kind, model })
+      : originalEffectivePayload;
+    onModelPayload?.({
+      payload: effectivePayload,
+      model,
+      kind,
+      estimatedTokens: estimateProviderPayloadTokens(effectivePayload),
+    });
+    if (!modelContextDumper?.enabled) {
+      return effectivePayload !== originalEffectivePayload ? effectivePayload : replacement;
+    }
+    const metadata = {
+      provider: model?.provider,
+      model: model?.id,
+      payload: "provider_request",
+    };
+    const requestPath = modelContextDumper.dump({
+      kind,
+      prompt: formatHumanPayload(effectivePayload),
+      metadata,
+    });
+    modelContextDumper.dumpSidecar?.({
+      sourcePath: requestPath,
+      suffix: "payload",
+      value: effectivePayload,
+    });
+    const tools = extractPayloadTools(effectivePayload);
+    if (tools) {
+      modelContextDumper.dumpSidecar?.({
+        sourcePath: requestPath,
+        suffix: "tools",
+        value: {
+          metadata: { ...metadata, payload: "provider_tools" },
+          tools,
+        },
+      });
+    }
+    if (effectivePayload !== originalEffectivePayload) return effectivePayload;
+    return replacement;
+  };
+  agent[MODEL_PAYLOAD_DUMPER_INSTALLED] = true;
+}
+
+export function estimateProviderPayloadTokens(payload) {
+  const request = normalizePayload(payload);
+  let chars = 0;
+  for (const key of ["system", "systemPrompt", "instructions"]) {
+    chars += textChars(request[key]);
+  }
+  for (const key of ["messages", "input"]) {
+    if (Array.isArray(request[key])) chars += textChars(request[key]);
+  }
+  const tools = extractPayloadTools(payload);
+  if (tools?.length) chars += JSON.stringify(tools).length;
+  if (chars === 0) chars = JSON.stringify(request).length;
+  return Math.ceil(chars / 4);
+}
+
+function formatHumanPayload(payload) {
+  const request = normalizePayload(payload);
+  const lines = ["# Messages", ""];
+  const messages = getHumanMessages(request);
+  const toolCalls = collectToolCalls(messages);
+  if (messages.length === 0) {
+    lines.push("(no messages found)", "");
+  } else {
+    for (const message of messages) {
+      lines.push(formatMessageHeading(message, toolCalls), "", formatMessageContent(message.content));
+      if (Array.isArray(message.tool_calls) && message.tool_calls.length > 0) {
+        lines.push("", ...message.tool_calls.map(formatToolCallLine));
+      }
+      lines.push("");
+    }
+  }
+
+  const tools = extractPayloadTools(payload);
+  if (tools?.length) {
+    lines.push("# Tools", "");
+    for (const tool of tools) lines.push(`- ${formatToolSummary(tool)}`);
+    lines.push("");
+  }
+
+  lines.push("# Raw Payload", "", "See the sibling `*-payload.json` file for the exact provider request.");
+  if (tools?.length) lines.push("See the sibling `*-tools.json` file for the complete tool schema.");
+  return lines.join("\n");
+}
+
+function getHumanMessages(request) {
+  if (Array.isArray(request.messages)) return request.messages;
+  if (!Array.isArray(request.input)) return [];
+  const messages = [];
+  if (typeof request.instructions === "string" && request.instructions) {
+    messages.push({ role: "system", content: request.instructions });
+  }
+  for (const item of request.input) {
+    if (!item || typeof item !== "object") continue;
+    if (item.role) {
+      messages.push(item);
+      continue;
+    }
+    messages.push({ role: item.type ?? "input", content: item });
+  }
+  return messages;
+}
+
+function collectToolCalls(messages) {
+  const calls = new Map();
+  for (const message of messages) {
+    if (!Array.isArray(message?.tool_calls)) continue;
+    for (const call of message.tool_calls) {
+      if (call?.id) calls.set(call.id, call);
+    }
+  }
+  return calls;
+}
+
+function formatMessageHeading(message, toolCalls) {
+  if (message?.role !== "tool") return `## ${message?.role ?? "message"}`;
+  const call = toolCalls.get(message.tool_call_id);
+  const name = call?.function?.name ?? message.name;
+  return name ? `## tool ${name}` : "## tool";
+}
+
+function formatToolCallLine(call) {
+  const name = call?.function?.name ?? call?.name ?? "unnamed_tool";
+  const args = call?.function?.arguments ?? call?.arguments ?? "";
+  return `tool_call ${name}(${stripAnsi(String(args ?? ""))})`;
+}
+
+function normalizePayload(payload) {
+  if (!payload || typeof payload !== "object") return { messages: [{ role: "payload", content: String(payload ?? "") }] };
+  if (Array.isArray(payload.messages)) return payload;
+  if (payload.body && typeof payload.body === "object") return payload.body;
+  if (typeof payload.body === "string") {
+    try {
+      return JSON.parse(payload.body);
+    } catch {}
+  }
+  return payload;
+}
+
+function formatMessageContent(content) {
+  if (typeof content === "string") return stripAnsi(content);
+  if (Array.isArray(content)) return content.map(formatContentPart).join("\n");
+  return stripAnsi(JSON.stringify(content, null, 2));
+}
+
+function formatContentPart(part) {
+  if (typeof part === "string") return stripAnsi(part);
+  if (!part || typeof part !== "object") return String(part ?? "");
+  if (typeof part.text === "string") return stripAnsi(part.text);
+  if (part.type) return stripAnsi(`[${part.type}] ${JSON.stringify(part)}`);
+  return stripAnsi(JSON.stringify(part));
+}
+
+function formatToolSummary(tool) {
+  const name = tool?.function?.name ?? tool?.name ?? "unnamed_tool";
+  const description = tool?.function?.description ?? tool?.description ?? "";
+  return description ? `${name}: ${description}` : name;
+}
+
+function extractPayloadTools(payload) {
+  if (!payload || typeof payload !== "object") return null;
+  if (Array.isArray(payload.tools)) return payload.tools;
+  if (payload.body && typeof payload.body === "object" && Array.isArray(payload.body.tools)) return payload.body.tools;
+  if (typeof payload.body === "string") {
+    try {
+      const body = JSON.parse(payload.body);
+      if (Array.isArray(body.tools)) return body.tools;
+    } catch {}
+  }
+  return null;
+}
+
+function textChars(value) {
+  if (value == null) return 0;
+  if (typeof value === "string") return value.length;
+  if (Array.isArray(value)) return value.reduce((sum, item) => sum + textChars(item), 0);
+  if (typeof value !== "object") return String(value).length;
+  if (typeof value.text === "string") return value.text.length;
+  if (typeof value.content === "string") return value.content.length;
+  if (Array.isArray(value.content)) return textChars(value.content);
+  if (value.type === "image" || value.type === "image_url") return 0;
+  return JSON.stringify(value).length;
+}

package/src/agent/pi-session/pi-session-sidecar-failure.mjs

@@ -0,0 +1,10 @@
+export async function createSidecarWriteFailure({ runtimeHost, sourceSessionFile, action, cause }) {
+  const causeMessage = cause?.message ?? String(cause);
+  const baseMessage = `failed to write pi session sidecar after ${action}: ${causeMessage}`;
+  try {
+    await runtimeHost.switchSession(sourceSessionFile);
+    return new Error(`${baseMessage}; rolled back to source session`);
+  } catch (rollbackErr) {
+    return new Error(`${baseMessage}; rollback failed: ${rollbackErr.message}`);
+  }
+}

package/src/agent/provider/payload-messages.mjs

@@ -0,0 +1,138 @@
+export function replaceProviderSystemPrompt(payload, systemPrompt) {
+  if (!payload || typeof payload !== "object" || !systemPrompt) return payload;
+  if (payload.body && typeof payload.body === "object") {
+    const body = replaceProviderSystemPrompt(payload.body, systemPrompt);
+    return body === payload.body ? payload : { ...payload, body };
+  }
+  if (typeof payload.body === "string") {
+    try {
+      const body = JSON.parse(payload.body);
+      const replaced = replaceProviderSystemPrompt(body, systemPrompt);
+      return replaced === body ? payload : { ...payload, body: JSON.stringify(replaced) };
+    } catch {
+      return payload;
+    }
+  }
+  if (!Array.isArray(payload.messages)) return payload;
+  return {
+    ...payload,
+    messages: [
+      { role: "system", content: systemPrompt },
+      ...payload.messages.filter((message) => message?.role !== "system"),
+    ],
+  };
+}
+
+export function replaceProviderContextMessages(payload, providerContext) {
+  if (!payload || typeof payload !== "object" || !providerContext?.system) return payload;
+  if (payload.body && typeof payload.body === "object") {
+    const body = replaceProviderContextMessages(payload.body, providerContext);
+    return body === payload.body ? payload : { ...payload, body };
+  }
+  if (typeof payload.body === "string") {
+    try {
+      const body = JSON.parse(payload.body);
+      const replaced = replaceProviderContextMessages(body, providerContext);
+      return replaced === body ? payload : { ...payload, body: JSON.stringify(replaced) };
+    } catch {
+      return payload;
+    }
+  }
+  if (Array.isArray(payload.messages)) return replaceChatMessagesPayload(payload, providerContext);
+  if (Array.isArray(payload.input) && typeof payload.instructions === "string") return replaceResponsesPayload(payload, providerContext);
+  return payload;
+}
+
+export function appendProviderUserMessage(payload, content) {
+  if (!payload || typeof payload !== "object" || !content) return payload;
+  if (payload.body && typeof payload.body === "object") {
+    const body = appendProviderUserMessage(payload.body, content);
+    return body === payload.body ? payload : { ...payload, body };
+  }
+  if (typeof payload.body === "string") {
+    try {
+      const body = JSON.parse(payload.body);
+      const appended = appendProviderUserMessage(body, content);
+      return appended === body ? payload : { ...payload, body: JSON.stringify(appended) };
+    } catch {
+      return payload;
+    }
+  }
+  if (Array.isArray(payload.messages)) {
+    return {
+      ...payload,
+      messages: [...payload.messages, { role: "user", content }],
+    };
+  }
+  if (Array.isArray(payload.input) && typeof payload.instructions === "string") {
+    return {
+      ...payload,
+      input: [...payload.input, { role: "user", content: [{ type: "input_text", text: content }] }],
+    };
+  }
+  return payload;
+}
+
+function replaceChatMessagesPayload(payload, providerContext) {
+  const originalUser = payload.messages.findLast?.((message) => message?.role === "user")
+    ?? [...payload.messages].reverse().find((message) => message?.role === "user");
+  const userMessages = (providerContext.userMessages ?? []).filter((message) => message?.content);
+  const contextMessages = userMessages.map((message, index) => ({
+    role: "user",
+    content: index === userMessages.length - 1 ? contentWithOriginalNonTextParts(message.content, originalUser) : message.content,
+  }));
+  return {
+    ...payload,
+    messages: [
+      { role: "system", content: providerContext.system },
+      ...contextMessages,
+      ...payload.messages.filter((message) => message?.role !== "system" && message?.role !== "user"),
+    ],
+  };
+}
+
+function replaceResponsesPayload(payload, providerContext) {
+  const userMessages = (providerContext.userMessages ?? []).filter((message) => message?.content);
+  const originalUser = payload.input.findLast?.((item) => item?.role === "user")
+    ?? [...payload.input].reverse().find((item) => item?.role === "user");
+  return {
+    ...payload,
+    instructions: providerContext.system,
+    input: [
+      ...userMessages.map((message, index) => ({
+        role: "user",
+        content: index === userMessages.length - 1
+          ? responsesContentWithOriginalNonTextParts(message.content, originalUser)
+          : [{ type: "input_text", text: message.content }],
+      })),
+      ...payload.input.filter((item) => item?.role !== "user"),
+    ],
+  };
+}
+
+function responsesContentWithOriginalNonTextParts(text, originalUser) {
+  return [{ type: "input_text", text }, ...responsesNonTextContentParts(originalUser?.content)];
+}
+
+function responsesNonTextContentParts(content) {
+  if (!Array.isArray(content)) return [];
+  return content.filter((part) => {
+    if (!part || typeof part !== "object") return false;
+    if (part.type === "input_text" || part.type === "text" || typeof part.text === "string") return false;
+    return true;
+  });
+}
+
+function contentWithOriginalNonTextParts(text, originalUser) {
+  const extraParts = nonTextContentParts(originalUser?.content);
+  return extraParts.length ? [{ type: "text", text }, ...extraParts] : text;
+}
+
+function nonTextContentParts(content) {
+  if (!Array.isArray(content)) return [];
+  return content.filter((part) => {
+    if (!part || typeof part !== "object") return false;
+    if (part.type === "text" || typeof part.text === "string") return false;
+    return true;
+  });
+}

package/src/agent/read-file-tool.mjs

@@ -0,0 +1,112 @@
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { toolText } from "./tool-result.mjs";
+
+const DEFAULT_LIMIT = 30;
+const DEFAULT_DIRECTORY_LIMIT = 200;
+const MAX_LIMIT = 2000;
+
+export function createReadFileTool({ engine }) {
+  return defineTool({
+    name: "read",
+    label: "Read File",
+    description: "Read a file slice with 1-based line numbers. Use offset and limit to read specific line ranges.",
+    parameters: Type.Object({
+      path: Type.String({ description: "Absolute or relative path to read" }),
+      offset: Type.Optional(Type.Number({ description: "1-based line number to start reading from; default 1" })),
+      limit: Type.Optional(Type.Number({ description: "Maximum number of lines to read; default 30, max 2000" })),
+    }),
+    execute: async (_toolCallId, params) => readFileSlice({ engine, ...params }),
+  });
+}
+
+export function readFileSlice({ engine, path, offset = 1, limit = DEFAULT_LIMIT }) {
+  const absPath = engine.resolvePath(path);
+  let stat;
+  try {
+    stat = statSync(absPath);
+  } catch (err) {
+    return toolText(`Error reading ${absPath}: ${err.message}`, { error: true, path: absPath });
+  }
+  if (stat.isDirectory()) return readDirectoryListing({ path: absPath, offset, limit });
+
+  let content;
+  try {
+    content = readFileSync(absPath, "utf8");
+  } catch (err) {
+    if (err?.code === "EISDIR") {
+      return toolText(`Error reading ${absPath}: this is a directory. Use ls(path) or find(pattern, path) to inspect it.`, { error: true, path: absPath, isDirectory: true });
+    }
+    return toolText(`Error reading ${absPath}: ${err.message}`, { error: true, path: absPath });
+  }
+
+  const lines = content.split("\n");
+  const start = clampLine(offset, lines.length);
+  const count = clampLimit(limit);
+  const selected = lines.slice(start - 1, start - 1 + count);
+  const end = start + selected.length - 1;
+  const body = selected.map((line, index) => `${start + index} | ${line}`).join("\n");
+  const header = `--- ${absPath} (lines ${start}-${end} of ${lines.length}) ---`;
+  const remaining = lines.length - end;
+  const footer = remaining > 0 ? `\n\n[${remaining} more lines in file. Use offset=${end + 1} to continue.]` : "";
+  return toolText(`${header}\n${body || "(empty)"}${footer}`, {
+    path: absPath,
+    offset: start,
+    limit: count,
+    totalLines: lines.length,
+    endLine: end,
+    truncated: remaining > 0,
+  });
+}
+
+function readDirectoryListing({ path, offset = 1, limit }) {
+  let entries;
+  try {
+    entries = readdirSync(path, { withFileTypes: true })
+      .map((entry) => ({
+        name: entry.name,
+        label: entry.isDirectory() ? `${entry.name}/` : entry.name,
+        isDirectory: entry.isDirectory(),
+      }))
+      .sort((a, b) => Number(b.isDirectory) - Number(a.isDirectory) || a.name.localeCompare(b.name));
+  } catch (err) {
+    return toolText(`Error reading ${path}: ${err.message}`, { error: true, path });
+  }
+
+  const start = entries.length === 0 ? 0 : clampLine(offset, entries.length);
+  const count = clampLimit(limit ?? DEFAULT_DIRECTORY_LIMIT);
+  const selected = start === 0 ? [] : entries.slice(start - 1, start - 1 + count);
+  const end = start + selected.length - 1;
+  const remaining = start === 0 ? 0 : entries.length - end;
+  const range = entries.length === 0 ? "0 entries" : `entries ${start}-${end} of ${entries.length}`;
+  const header = `--- ${path} (directory, ${range}) ---`;
+  const footer = remaining > 0 ? `\n\n[${remaining} more entries in directory. Use offset=${end + 1} to continue, or find(pattern, path) to search recursively.]` : "";
+  return toolText(`${header}\n${selected.map((entry) => entry.label).join("\n") || "(empty directory)"}${footer}`, {
+    path,
+    isDirectory: true,
+    entryCount: entries.length,
+    offset: start,
+    limit: count,
+    endEntry: end,
+    truncated: remaining > 0,
+    entries: selected.map((entry) => ({
+      name: entry.name,
+      path: resolve(path, entry.name),
+      isDirectory: entry.isDirectory,
+    })),
+  });
+}
+
+function clampLine(value, lineCount) {
+  const parsed = Math.trunc(Number(value));
+  if (!Number.isFinite(parsed) || parsed < 1) return 1;
+  return Math.min(parsed, Math.max(1, lineCount));
+}
+
+function clampLimit(value) {
+  const parsed = Math.trunc(Number(value));
+  if (!Number.isFinite(parsed) || parsed < 1) return DEFAULT_LIMIT;
+  return Math.min(parsed, MAX_LIMIT);
+}

package/src/agent/runner/fast-model.mjs

@@ -0,0 +1,36 @@
+const FAST_PROVIDERS = new Set(["openai", "openai-codex"]);
+const FAST_ID_SUFFIX = "__fast";
+
+export function isFastProvider(provider) {
+  return FAST_PROVIDERS.has(provider);
+}
+
+export function createFastModelEntry(baseModel) {
+  return {
+    model: {
+      ...baseModel,
+      id: baseModel.id + FAST_ID_SUFFIX,
+      name: baseModel.name + " Fast",
+      __isFast: true,
+      __baseId: baseModel.id,
+    },
+  };
+}
+
+export function appendFastVariants(scopedModels) {
+  const result = [];
+  for (const entry of scopedModels) {
+    result.push(entry);
+    if (isFastProvider(entry.model.provider)) {
+      result.push(createFastModelEntry(entry.model));
+    }
+  }
+  return result;
+}
+
+export function fromFastEntryModel(model) {
+  if (model.__isFast) {
+    return { baseId: model.__baseId, isFast: true };
+  }
+  return { baseId: model.id, isFast: false };
+}

package/src/agent/runner/runner-cleanup.mjs

@@ -0,0 +1,12 @@
+export async function runRunnerCleanup(cleanups) {
+  const errors = [];
+  for (const cleanup of cleanups) {
+    try {
+      await cleanup();
+    } catch (err) {
+      errors.push(err);
+    }
+  }
+  if (errors.length === 1) throw errors[0];
+  if (errors.length > 1) throw new AggregateError(errors, "Runner cleanup failed");
+}

package/src/agent/runner/runner-init.mjs

@@ -0,0 +1,15 @@
+import { SessionManager } from "@earendil-works/pi-coding-agent";
+
+export function createDefaultSessionManager(cwd) {
+  return SessionManager.inMemory(cwd);
+}
+
+export function resolveRunnerSessionManager(cwd, sessionManager = null) {
+  return sessionManager ?? createDefaultSessionManager(cwd);
+}
+
+export function resolveInitialModel({ modelRegistry, provider, modelId }) {
+  const available = modelRegistry.getAvailable?.() ?? [];
+  if (provider && modelId) return available.find((model) => model.provider === provider && model.id === modelId) ?? null;
+  return available[0] ?? null;
+}

package/src/agent/runner/runner-session-state.mjs

@@ -0,0 +1,40 @@
+export function getRunnerSessionStats(activeSession, runtimeHost) {
+  const stats = activeSession.getSessionStats();
+  const manager = activeSession.sessionManager;
+  return {
+    ...stats,
+    runtimeHost: Boolean(runtimeHost),
+    piSessionSwitching: Boolean(runtimeHost),
+    persisted: manager?.isPersisted?.() ?? Boolean(activeSession.sessionFile),
+    sessionFile: manager?.getSessionFile?.() ?? activeSession.sessionFile,
+  };
+}
+
+export function syncEngineSessionState(engine, session) {
+  bindToolDefs(engine, session);
+  engine.setRuntimeState({
+    modelId: session.model?.id,
+    provider: session.model?.provider,
+    thinkingLevel: session.thinkingLevel,
+  });
+}
+
+function bindToolDefs(engine, session) {
+  engine.setToolDefs(session.getActiveToolNames().map((name) => {
+    const tool = session.getToolDefinition(name);
+    return {
+      name,
+      description: tool?.description ?? "",
+      parameters: tool?.parameters ? describeParams(tool.parameters) : null,
+    };
+  }));
+}
+
+function describeParams(schema) {
+  if (!schema || !schema.properties) return {};
+  const out = {};
+  for (const [key, prop] of Object.entries(schema.properties)) {
+    out[key] = prop.description ?? key;
+  }
+  return out;
+}