@agentex/agent 0.0.39 → 0.0.42

package/src/providers/antigravity/session.ts

@@ -38,7 +38,8 @@ import { AGY_SIGN_IN_MESSAGE, buildAgyArgs, findAgyBinary, readAgyResumeId } fro
 interface ActiveTurn {
   turnId: string;
   abort: AbortController;
-  done: Promise<TurnResult>;
+  /** Set once the turn starts; a turn_start handler can interrupt before that. */
+  done: Promise<TurnResult> | null;
 }
 
 /**
@@ -74,8 +75,20 @@ class AntigravitySession implements AgentSession {
   /** Events received from agy processes, to tell whether one saw a message. */
   private connectionEvents = 0;
   private draining = false;
-  /** Instructions go into the first message of a conversation this session starts. */
-  private pendingInstructions: string | null;
+  /**
+   * agy has no system-prompt flag, so instructions ride on the first message
+   * each process accepts, like a per-process system prompt. They stay pending
+   * until agy acknowledges a message that carried them, so a failed start or
+   * sign-in never drops them, and a resume agy could not honor (a new
+   * conversation) still gets them.
+   */
+  private readonly instructions: string | null;
+  /** Conversations this session saw agy accept the instructions into. */
+  private readonly instructedConversations = new Set<string>();
+  /** The current process accepted a message that carried the instructions. */
+  private connectionInstructed = false;
+  /** The conversation the current process was started to resume, if any. */
+  private connectionResumeId: string | null = null;
   private readonly cwd: string;
   private readonly goals: GoalController;
 
@@ -86,7 +99,7 @@ class AntigravitySession implements AgentSession {
   ) {
     this.cwd = ctx.cwd ?? process.cwd();
     this.conversationId = readAgyResumeId(ctx.sessionParams, this.cwd);
-    this.pendingInstructions = this.conversationId ? null : instructions;
+    this.instructions = instructions;
     this.goals = new GoalController({
       providerType: ANTIGRAVITY_PROVIDER_TYPE,
       capability: EMULATED_GOAL_CAPABILITY,
@@ -118,12 +131,14 @@ class AntigravitySession implements AgentSession {
     const uuid = uuidv7();
     const turnId = uuidv7();
     const abort = new AbortController();
-    const text = this.pendingInstructions ? `${this.pendingInstructions}\n\n${message}` : message;
-    this.pendingInstructions = null;
 
     this._state = "thinking";
-    const done = this.runTurn(text, turnId, abort, options);
-    this.active = { turnId, abort, done };
+    // Registered before the turn runs, so interrupt() can reach it from inside
+    // a turn_start handler.
+    const active: ActiveTurn = { turnId, abort, done: null };
+    this.active = active;
+    const done = this.runTurn(message, turnId, abort, options);
+    active.done = done;
     void done.then((result) => this.goals.onTurnSettled(result)).catch(() => undefined);
     return { uuid, result: done };
   }
@@ -133,6 +148,8 @@ class AntigravitySession implements AgentSession {
     const config = this.ctx.config ?? {};
     // A replacement process picks the conversation back up where it stopped.
     this.conversationId = this.sessionId;
+    this.connectionResumeId = this.conversationId;
+    this.connectionInstructed = false;
     const parser = new AgyStreamParser({
       includePartialMessages: config.includePartialMessages,
       conversationId: this.conversationId,
@@ -162,18 +179,21 @@ class AntigravitySession implements AgentSession {
   }
 
   private async runTurn(
-    text: string,
+    message: string,
     turnId: string,
     abort: AbortController,
     options?: SendOptions,
   ): Promise<TurnResult> {
-    await this.emitTurnEdge({ type: "turn_start", turnId, trigger: "send" });
-
+    // Arm every stop before the first await: an interrupt that lands while
+    // turn_start handlers run must still stop the turn.
     const timeoutSec = options?.timeoutSec ?? this.ctx.config?.timeoutSec;
     const graceSec = this.ctx.config?.graceSec;
     let timer: ReturnType<typeof setTimeout> | null = null;
     const guards: Promise<"timeout" | "aborted">[] = [
-      new Promise((resolve) => abort.signal.addEventListener("abort", () => resolve("aborted"), { once: true })),
+      new Promise((resolve) => {
+        if (abort.signal.aborted) resolve("aborted");
+        else abort.signal.addEventListener("abort", () => resolve("aborted"), { once: true });
+      }),
     ];
     if (timeoutSec && timeoutSec > 0) {
       guards.push(new Promise((resolve) => { timer = setTimeout(() => resolve("timeout"), timeoutSec * 1000); }));
@@ -184,15 +204,30 @@ class AntigravitySession implements AgentSession {
       else options.signal.addEventListener("abort", onSendAbort, { once: true });
     }
 
-    let connection = this.ensureConnection();
+    let connection: AgyConnection | null = null;
     try {
+      await this.emitTurnEdge({ type: "turn_start", turnId, trigger: "send" });
+      if (abort.signal.aborted) {
+        // Stopped before agy saw anything: nothing to interrupt, nothing spawned.
+        await this.emitTurnEdge({ type: "turn_end", turnId, trigger: "send", reason: "cancelled" });
+        return { summary: null, costUsd: null, status: "aborted", errorCode: "aborted", errorMessage: "Turn aborted" };
+      }
+
+      connection = this.ensureConnection();
       let result: TurnResult | null = null;
       let reason: "result" | "cancelled" | "session_closed" = "result";
       for (let attempt = 0; result === null; attempt++) {
         const eventsBefore = this.connectionEvents;
+        const carriesInstructions = this.needsInstructions();
         const pending = connection.nextTurn();
-        connection.write(text);
+        connection.write(carriesInstructions ? `${this.instructions}\n\n${message}` : message);
         const first = await Promise.race([pending, ...guards]);
+        // Any event from agy means it accepted the message, instructions included.
+        if (carriesInstructions && this.connectionEvents > eventsBefore) {
+          this.connectionInstructed = true;
+          const conversation = this.parser?.conversationId;
+          if (conversation) this.instructedConversations.add(conversation);
+        }
         if (first === "timeout" || first === "aborted") {
           const outcome = await interruptAgyTurn(connection, pending, graceSec);
           // agy may report INTERRUPTED and then exit. Learn which before the
@@ -230,11 +265,17 @@ class AntigravitySession implements AgentSession {
       if (timer) clearTimeout(timer);
       options?.signal?.removeEventListener("abort", onSendAbort);
       this.active = null;
-      if (!connection.alive && this.connection === connection) this.connection = null;
+      if (connection && !connection.alive && this.connection === connection) this.connection = null;
       if (this._state !== "closed") this._state = "idle";
     }
   }
 
+  /** The next message must carry the instructions (see `instructions`). */
+  private needsInstructions(): boolean {
+    if (!this.instructions || this.connectionInstructed) return false;
+    return !(this.connectionResumeId && this.instructedConversations.has(this.connectionResumeId));
+  }
+
   private usageOf(outcome: AgyTurnOutcome | null): { usage?: TurnResult["usage"] } {
     const usage = agyUsageRecord(outcome?.result?.turnUsage ?? null, this.parser?.model ?? this.ctx.config?.model ?? null);
     return usage ? { usage } : {};
@@ -335,12 +376,12 @@ class AntigravitySession implements AgentSession {
     const active = this.active;
     if (!active) return;
     active.abort.abort();
-    await active.done.catch(() => undefined);
+    await active.done?.catch(() => undefined);
   }
 
   async drain(): Promise<void> {
     this.draining = true;
-    if (this.active) await this.active.done.catch(() => undefined);
+    await this.active?.done?.catch(() => undefined);
     await this.close();
   }
 
@@ -350,7 +391,7 @@ class AntigravitySession implements AgentSession {
     const active = this.active;
     if (active) {
       active.abort.abort();
-      await active.done.catch(() => undefined);
+      await active.done?.catch(() => undefined);
     }
     const connection = this.connection;
     this.connection = null;

package/src/providers/claude/attach.ts

@@ -1,6 +1,5 @@
 import { createReadStream } from "node:fs";
 import { stat } from "node:fs/promises";
-import * as readline from "node:readline";
 import type {
   AttachOptions,
   CatchUpOptions,
@@ -16,6 +15,7 @@ import {
   createSessionRecord,
   MalformedSessionRecordError,
 } from "../../sessions/record.js";
+import { readJsonlLines } from "../../utils/jsonl-lines.js";
 import { getRuntimeHomeEnvVar } from "../../utils/runtime-homes.js";
 import { claudeSessionCodec } from "./codec.js";
 import {
@@ -86,16 +86,15 @@ const EMPTY: AsyncIterable<CatchUpYield> = {
  * preceding completed one.
  */
 async function classifyLastTurn(filePath: string): Promise<LastTurnStatus> {
-  const stream = createReadStream(filePath, { encoding: "utf8" });
+  const stream = createReadStream(filePath);
   stream.on("error", () => {});
-  const lines = readline.createInterface({ input: stream, crlfDelay: Infinity });
   let lastTurn: LastTurnStatus = "unknown";
 
   try {
-    for await (const line of lines) {
+    for await (const line of readJsonlLines(stream)) {
       let raw: unknown;
       try {
-        raw = JSON.parse(line);
+        raw = JSON.parse(line.text);
       } catch {
         continue;
       }
@@ -109,7 +108,6 @@ async function classifyLastTurn(filePath: string): Promise<LastTurnStatus> {
     if (fsError?.code !== "ENOENT") throw error;
     return "unknown";
   } finally {
-    lines.close();
     stream.destroy();
   }
 

package/src/providers/claude/transcript.ts

@@ -23,8 +23,8 @@ import { createReadStream } from "node:fs";
 import { readdir, realpath, stat, open as fsOpen } from "node:fs/promises";
 import * as os from "node:os";
 import * as path from "node:path";
-import * as readline from "node:readline";
 
+import { readJsonlLines } from "../../utils/jsonl-lines.js";
 import { getDefaultRuntimeHome, getRuntimeHomeEnvVar } from "../../utils/runtime-homes.js";
 import type { FoundTranscript, StreamEvent, TranscriptOps } from "../../types.js";
 import { parseStreamLine } from "./parse.js";
@@ -273,13 +273,12 @@ async function readCwdFromTranscript(filePath: string): Promise<string | null> {
   if (!fh) return null;
 
   try {
-    const stream = fh.createReadStream({ encoding: "utf8", autoClose: false });
-    const rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
+    const stream = fh.createReadStream({ autoClose: false });
     let count = 0;
     try {
-      for await (const raw of rl) {
+      for await (const line of readJsonlLines(stream)) {
         if (++count > 50) break;
-        const trimmed = raw.trim();
+        const trimmed = line.text.trim();
         if (!trimmed) continue;
         try {
           const obj = JSON.parse(trimmed) as Record<string, unknown>;
@@ -300,7 +299,6 @@ async function readCwdFromTranscript(filePath: string): Promise<string | null> {
         }
       }
     } finally {
-      rl.close();
       stream.destroy();
     }
   } finally {
@@ -377,26 +375,16 @@ export async function* readClaudeTranscript(
 
   const stream = createReadStream(filePath, { start: fromOffset, encoding: undefined });
 
-  // Suppress stray ENOENT (file deleted between stat and open) — readline
+  // Suppress stray ENOENT (file deleted between stat and open) — the stream
   // raises the same condition through its own iterator, which we catch below.
   stream.on("error", () => {});
 
-  const rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
-
-  let pos = fromOffset;
   let stillSkippingPastSince = !!sinceEventId;
 
   try {
-    for await (const line of rl) {
-      // readline strips the trailing `\n` (and the `\r` from `\r\n`). Claude
-      // writes Unix line endings, so we account for `\n` only. A `\r\n` file
-      // would yield offsets 1 byte short per line — accepted as a corner
-      // case; resume from such an offset would skip one stray `\r`.
-      const lineByteLen = Buffer.byteLength(line, "utf8");
-      pos += lineByteLen + 1;
-
-      if (!line) continue;
-      const trimmed = line.trim();
+    for await (const line of readJsonlLines(stream, fromOffset)) {
+      if (!line.text) continue;
+      const trimmed = line.text.trim();
       if (!trimmed) continue;
 
       if (looksLikeSkippedType(trimmed)) continue;
@@ -413,7 +401,7 @@ export async function* readClaudeTranscript(
       }
 
       for (const event of events) {
-        yield { event, offset: pos };
+        yield { event, offset: line.end };
       }
     }
   } catch (err) {
@@ -421,7 +409,6 @@ export async function* readClaudeTranscript(
     const e = err as NodeJS.ErrnoException;
     if (e?.code !== "ENOENT") throw err;
   } finally {
-    rl.close();
     stream.destroy();
   }
 }

package/src/providers/codex/attach.ts

@@ -132,6 +132,10 @@ export async function attachCodexSession(
   if (transcript) {
     const lastEvent = await latestTurnBoundary(transcript.filePath, sessionId);
     if (lastEvent === null) lastTurn = "unknown";
+    // turn_aborted replays as an interrupted result, but the turn never
+    // finished, so it stays "interrupted" for hosts deciding whether to re-send.
+    else if (lastEvent.type === "event_msg" && lastEvent.payload?.["type"] === "turn_aborted")
+      lastTurn = "interrupted";
     else if (codexLineToStreamEvents(lastEvent, { sessionId }).some((event) => event.type === "result"))
       lastTurn = "completed";
     else lastTurn = "interrupted";

package/src/providers/codex/history.ts

@@ -57,6 +57,17 @@ function codexUserText(line: CodexTranscriptLine): string | null {
   if (line.type === "event_msg" && line.payload?.["type"] === "user_message") {
     return meaningfulHumanText(asString(line.payload["message"]));
   }
+  // Paginated rollouts (`session_meta.history_mode: "paginated"`, written by
+  // Codex 0.142 and later) never write `user_message`. What the person typed
+  // is a completed `UserMessage` item instead, and legacy rollouts never
+  // persist that item, so each message is read once. The `response_item` user
+  // message beside it also carries injected context, so it is not the one read.
+  if (line.type === "event_msg" && line.payload?.["type"] === "item_completed") {
+    const item = asRecord(line.payload["item"]);
+    if (item?.["type"] === "UserMessage") {
+      return meaningfulHumanText(textFromContent(item["content"], new Set(["text", "input_text"])));
+    }
+  }
   // Older unwrapped rollouts have no event_msg mirror.
   if (line.type === "message" && line.raw["role"] === "user") {
     return meaningfulHumanText(textFromContent(

package/src/providers/codex/parse.ts

@@ -81,6 +81,61 @@ function parseStringArray(value: unknown): string[] {
  * tells it to do — rendered no row for completions that reached it by the
  * reconcile path. Mirrors the Claude gate in `claude/parse.ts`.
  */
+/**
+ * The name an MCP tool call goes by: `mcp__<server>__<tool>`, the name the
+ * model calls it by and the shape Claude reports, so hosts render both alike.
+ * Codex's `tool` can be dotted (`github.create_branch` on the `codex_apps`
+ * server); the model sees `mcp__codex_apps__github_create_branch`.
+ */
+export function codexMcpToolName(server: string, tool: string | null): string {
+  const clean = (part: string) => part.replace(/[^A-Za-z0-9_-]/g, "_");
+  return tool ? `mcp__${clean(server)}__${clean(tool)}` : `mcp__${clean(server)}`;
+}
+
+function isMcpToolCallItem(itemType: string): boolean {
+  return itemType === "mcpToolCall" || itemType === "mcp_tool_call";
+}
+
+/** What an MCP tool call returned: its error, else its text content, else its structured content. */
+function mcpToolCallOutput(item: Record<string, unknown>): string {
+  const error = parseObject(item["error"]);
+  const message = asString(error["message"], "");
+  if (message) return message;
+  const result = parseObject(item["result"]);
+  const content = Array.isArray(result["content"]) ? result["content"] : [];
+  const text = content
+    .map((part) => {
+      const block = parseObject(part);
+      return block["type"] === "text" ? asString(block["text"], "") : JSON.stringify(part);
+    })
+    .filter(Boolean)
+    .join("\n");
+  if (text) return text;
+  const structured = result["structuredContent"] ?? result["structured_content"];
+  return structured === undefined || structured === null ? "" : JSON.stringify(structured);
+}
+
+function mcpToolCallEvent(
+  phase: "started" | "completed",
+  item: Record<string, unknown>,
+  itemId: string | null,
+  base: BaseStreamEventFields,
+): StreamEvent {
+  const name = codexMcpToolName(asString(item["server"], ""), asNullableString(item["tool"]));
+  if (phase === "started") {
+    return { type: "tool_call", toolCallId: itemId, name, input: item["arguments"] ?? {}, ...base };
+  }
+  return {
+    type: "tool_result",
+    toolCallId: itemId,
+    toolName: name,
+    content: mcpToolCallOutput(item),
+    isError: item["status"] === "failed" || Object.keys(parseObject(item["error"])).length > 0,
+    exitCode: null,
+    ...base,
+  };
+}
+
 export function codexBackgroundTaskReport(
   phase: "started" | "progress" | "completed",
   status: "pending" | "running" | "paused" | "completed" | "failed" | "stopped" | null,
@@ -402,6 +457,7 @@ function parseV2Notification(event: Record<string, unknown>): StreamEvent | Stre
           ...base,
         };
       }
+      if (isMcpToolCallItem(itemType)) return mcpToolCallEvent("started", item, itemId, base);
       // reasoning, agentMessage, userMessage — wait for item/completed.
       return null;
     }
@@ -432,6 +488,7 @@ function parseV2Notification(event: Record<string, unknown>): StreamEvent | Stre
         ...base,
       };
     }
+    if (isMcpToolCallItem(itemType)) return mcpToolCallEvent("completed", item, itemId, base);
     if (itemType === "agentMessage") {
       const directText = asString(item["text"], "");
       if (directText || directText === "") {
@@ -690,6 +747,7 @@ function parseNdjsonEvent(
         ...base,
       };
     }
+    if (isMcpToolCallItem(itemType)) return mcpToolCallEvent("started", item, itemId, base);
   }
 
   if (type === "item.completed") {
@@ -721,6 +779,7 @@ function parseNdjsonEvent(
         ...base,
       };
     }
+    if (isMcpToolCallItem(itemType)) return mcpToolCallEvent("completed", item, itemId, base);
     if (itemType === "agent_message") {
       const phase = asMessagePhase(item["phase"]);
       const directText = asString(item["text"], "");

package/src/providers/codex/permissions.ts

@@ -0,0 +1,61 @@
+/**
+ * The approval policy and sandbox a Codex app-server thread runs with.
+ *
+ * `codex app-server` reads root `-c key=value` overrides but drops the
+ * interactive flags (`--sandbox`, `--dangerously-bypass-approvals-and-sandbox`):
+ * they belong to the TUI, and the `app-server` subcommand never receives them
+ * (codex-rs `cli/src/main.rs`, verified on 0.160). Sessions spawned with those
+ * flags ran on Codex's own defaults instead: approvals `on-request` and a
+ * `workspace-write` or `read-only` sandbox, whatever the host asked for.
+ *
+ * So the policy is set twice, through the two channels app-server does read:
+ * the `-c` overrides at spawn (every thread the process runs, child agents and
+ * resumed threads included) and the `thread/start` / `thread/resume` params
+ * (the root thread, explicitly, so a resumed thread created under different
+ * settings takes the current ones).
+ *
+ * It matters beyond the sandbox. Under `never` with full disk access, Codex
+ * approves MCP and app tool calls itself (`mcp_permission_prompt_is_auto_approved`
+ * in codex-rs `codex-mcp`). Under `on-request` it asks the client first, through
+ * `mcpServer/elicitation/request`.
+ */
+
+import type { ProviderConfig } from "../../types.js";
+
+export type CodexSandboxMode = "read-only" | "workspace-write" | "danger-full-access";
+
+export interface CodexThreadPermissions {
+  /** Unset leaves Codex's configured default (`on-request` unless the user changed it). */
+  approvalPolicy?: "never";
+  /** Unset leaves Codex's configured default, which depends on the folder's trust. */
+  sandbox?: CodexSandboxMode;
+}
+
+/**
+ * Plan mode wins over `skipPermissions`, as it does for the spawn flags:
+ * read-only, with approvals left on so an escalation still reaches the host.
+ * Anything else leaves Codex's defaults, which is what no flag ever meant.
+ */
+export function codexThreadPermissions(
+  config: Pick<ProviderConfig, "planMode" | "skipPermissions"> | undefined,
+): CodexThreadPermissions {
+  if (config?.planMode) return { sandbox: "read-only" };
+  if (config?.skipPermissions) return { approvalPolicy: "never", sandbox: "danger-full-access" };
+  return {};
+}
+
+/** The same settings as root `-c` overrides, placed before the `app-server` subcommand. */
+export function codexPermissionConfigArgs(permissions: CodexThreadPermissions): string[] {
+  const args: string[] = [];
+  if (permissions.approvalPolicy) args.push("-c", `approval_policy="${permissions.approvalPolicy}"`);
+  if (permissions.sandbox) args.push("-c", `sandbox_mode="${permissions.sandbox}"`);
+  return args;
+}
+
+/** The same settings as `thread/start` / `thread/resume` params. */
+export function codexPermissionThreadParams(permissions: CodexThreadPermissions): Record<string, unknown> {
+  return {
+    ...(permissions.approvalPolicy ? { approvalPolicy: permissions.approvalPolicy } : {}),
+    ...(permissions.sandbox ? { sandbox: permissions.sandbox } : {}),
+  };
+}