@agentex/agent 0.0.35 → 0.0.37

package/src/providers/codex/execute.ts

@@ -250,6 +250,9 @@ export async function executeCodexProvider(ctx: ExecutionContext): Promise<Execu
           status: "stopped",
           description: task.description,
           summary: null,
+          // Cut short, so there is no result to hand back.
+          toolUseId: null,
+          report: null,
           parentTaskId: task.parentTaskId,
           timestamp: new Date().toISOString(),
           providerType: "codex",

package/src/providers/codex/parse.ts

@@ -1,4 +1,5 @@
 import type {
+  BackgroundTaskReport,
   BaseStreamEventFields,
   GoalSource,
   StreamEvent,
@@ -70,6 +71,26 @@ function parseStringArray(value: unknown): string[] {
     : [];
 }
 
+/**
+ * The delivered-result payload for a background task, or null.
+ *
+ * One rule for every Codex emitter: a child that reached a terminal outcome
+ * handed something back; one that was cut short did not. Defined here rather
+ * than at each construction site because there are five of them and four
+ * previously forgot, so a host keying on `report !== null` — which the README
+ * tells it to do — rendered no row for completions that reached it by the
+ * reconcile path. Mirrors the Claude gate in `claude/parse.ts`.
+ */
+export function codexBackgroundTaskReport(
+  phase: "started" | "progress" | "completed",
+  status: "pending" | "running" | "paused" | "completed" | "failed" | "stopped" | null,
+  summary: string | null,
+): BackgroundTaskReport | null {
+  if (phase !== "completed") return null;
+  if (status !== "completed" && status !== "failed") return null;
+  return { summary, outputFile: null, usage: null };
+}
+
 function codexBackgroundTaskState(
   value: unknown,
 ): { phase: "started" | "completed"; status: "running" | "completed" | "failed" | "stopped"; summary: string | null } {
@@ -454,6 +475,8 @@ function parseV2Notification(event: Record<string, unknown>): StreamEvent | Stre
         description: asNullableString(item["agentPath"]),
         summary: null,
         parentTaskId: null,
+        toolUseId: null,
+        report: null,
         ...base,
       };
     }
@@ -491,6 +514,8 @@ function parseV2Notification(event: Record<string, unknown>): StreamEvent | Stre
           description,
           summary: state.summary,
           parentTaskId: null,
+          toolUseId: null,
+          report: codexBackgroundTaskReport(state.phase, state.status, state.summary),
           ...base,
         };
       });

package/src/providers/codex/session.ts

@@ -2,6 +2,7 @@ import type { ChildProcess } from "node:child_process";
 import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import type {
+  BackgroundTaskReport,
   AgentSession,
   CancelResult,
   ClearGoalResult,
@@ -27,7 +28,7 @@ import { translateEndpoint } from "../../utils/endpoint.js";
 import { injectWorkspaceSkills } from "../../utils/skills.js";
 import { resolveInstructions } from "../../utils/instructions.js";
 import { createToolNameTracker } from "../../utils/tool-names.js";
-import { parseCodexStreamLines } from "./parse.js";
+import { parseCodexStreamLines, codexBackgroundTaskReport } from "./parse.js";
 import { withPlanModePreamble } from "./plan-mode.js";
 import { scanCodexSessionUsage } from "./usage-scanner.js";
 import { codexSessionCodec } from "./codec.js";
@@ -1448,6 +1449,8 @@ export class CodexSessionImpl implements AgentSession {
       parentTaskId?: string | null;
       turnId?: string | null;
       eventId?: string | null;
+      /** Set on the edge that actually hands the child's result back. */
+      report?: BackgroundTaskReport | null;
       raw: Record<string, unknown>;
     },
   ): Extract<StreamEvent, { type: "background_task" }> {
@@ -1461,6 +1464,16 @@ export class CodexSessionImpl implements AgentSession {
       description: options.description ?? null,
       summary: options.summary ?? null,
       parentTaskId: options.parentTaskId ?? null,
+      // Codex identifies children by thread id, not by the id of the
+      // `spawn_agent` call that created them, so there is no tool-call link to
+      // report here.
+      toolUseId: null,
+      // Derived, not passed. Four of the five emitters that reach this helper
+      // never set it, and the omission was invisible until a host asked why
+      // reconciled completions produced no row.
+      report: options.report !== undefined
+        ? options.report
+        : codexBackgroundTaskReport(phase, status, options.summary ?? null),
       timestamp: new Date().toISOString(),
       providerType: "codex",
       sessionId: rootThreadId,
@@ -1833,6 +1846,8 @@ export class CodexSessionImpl implements AgentSession {
         status: "running",
         description,
         summary: null,
+        toolUseId: null,
+        report: null,
         parentTaskId: parentThreadId === rootThreadId ? null : parentThreadId,
         timestamp: new Date().toISOString(),
         providerType: "codex",
@@ -1867,6 +1882,8 @@ export class CodexSessionImpl implements AgentSession {
         status: "running",
         description: task.description,
         summary: null,
+        toolUseId: null,
+        report: null,
         parentTaskId: task.parentTaskId,
         timestamp: new Date().toISOString(),
         providerType: "codex",
@@ -1920,6 +1937,12 @@ export class CodexSessionImpl implements AgentSession {
       description: task.description,
       summary: task.summary ?? (errorMessage || null),
       parentTaskId: task.parentTaskId,
+      toolUseId: null,
+      // The child's turn ended and its result is being handed back — the same
+      // edge Claude expresses as `task_notification`. Same rule as every other
+      // emitter, so a host can render "one row per delivered result" across
+      // providers instead of special-casing each one.
+      report: codexBackgroundTaskReport("completed", status, task.summary ?? (errorMessage || null)),
       timestamp: new Date().toISOString(),
       providerType: "codex",
       sessionId: rootThreadId,

package/src/providers/opencode/event-parse.ts

@@ -73,7 +73,7 @@ export function incompleteTurnMessage(finish: string | null): string {
 }
 
 export interface TerminalOutcome {
-  status: "completed" | "failed";
+  status: "completed" | "failed" | "aborted";
   errorCode: string | null;
   errorMessage: string | null;
   /**
@@ -81,7 +81,7 @@ export interface TerminalOutcome {
    * "silent empty turn" opencode records as a normal completion (typically after
    * an upstream stream error, surfaced as `finish: "unknown"`). Distinct from a
    * user interrupt, which opencode marks with a `MessageAbortedError` in
-   * `info.error` and so lands in the error branch below.
+   * `info.error` and so reports as `aborted` below.
    */
   incomplete: boolean;
 }
@@ -92,20 +92,34 @@ export interface TerminalOutcome {
  * visible note) instead of rendering as a stall. Keyed on the message having no
  * visible text and a non-clean finish reason; never fires when the model
  * produced an answer or stopped cleanly, and never fires on an interrupt.
+ *
+ * Both the live and reconcile paths call this, so the "finished" guard lives
+ * here: a message with neither a finish reason nor an error is still running (or
+ * a malformed response) and stays `completed`. Without it, an empty `/message`
+ * body would flip to `failed` with no note — the exact silent stall this exists
+ * to remove, reached from the other direction.
  */
 export function terminalOutcome(info: unknown, hasVisibleText: boolean): TerminalOutcome {
-  const status = turnStatusFromMessage(info);
-  if (status === "failed") {
-    const m = rec(info);
-    return {
-      status,
-      errorCode: "agent_error",
-      errorMessage: JSON.stringify(m?.["error"] ?? null),
-      incomplete: false,
-    };
+  const m = rec(info);
+  const rawError = m?.["error"] ?? null;
+  const finish = m ? str(m["finish"] ?? null) : null;
+
+  // Not a finished turn (no finish reason, no error): don't reclassify.
+  if (rawError == null && finish === null) {
+    return { status: "completed", errorCode: null, errorMessage: null, incomplete: false };
   }
-  const finish = str(rec(info)?.["finish"] ?? null);
-  const cleanStop = finish !== null && CLEAN_FINISH_REASONS.has(finish);
+
+  if (rawError != null) {
+    // A user interrupt (through opencode's own UI, on a session this process is
+    // attached to) is recorded as a MessageAbortedError. Report it as `aborted`
+    // to match self-aborts and Codex, not a generic error with a JSON blob.
+    if (rec(rawError)?.["name"] === "MessageAbortedError") {
+      return { status: "aborted", errorCode: "aborted", errorMessage: "The turn was interrupted.", incomplete: false };
+    }
+    return { status: "failed", errorCode: "agent_error", errorMessage: JSON.stringify(rawError), incomplete: false };
+  }
+
+  const cleanStop = CLEAN_FINISH_REASONS.has(finish!);
   if (!hasVisibleText && !cleanStop) {
     return {
       status: "failed",

package/src/providers/opencode/http-session.ts

@@ -491,6 +491,12 @@ class OpenCodeSession implements AgentSession {
   private finishTurn(): void {
     this._turnActive = false;
     this._inFlight = null;
+    // Cleared at turn end, not with the sibling dedup maps at turn start: the
+    // user message's role has to survive from its `message.updated` frame into
+    // the part stream that follows within the same turn, so clearing at the
+    // start would reintroduce the prompt echo. Bounding it here keeps the map
+    // from growing for the whole life of a long-running session.
+    this._messageRoles.clear();
     if (this._state !== "closed") this._state = "idle";
   }
 
@@ -615,6 +621,13 @@ class OpenCodeSession implements AgentSession {
    * stable `:incomplete` event id is shared with the reconcile path
    * (`historicalEvents`) so a later catch-up dedups against this live note
    * instead of duplicating it.
+   *
+   * This is library-authored prose, not model output. It is emitted as
+   * `type: "assistant"` because that is the only surface a host renders, and is
+   * tagged `raw.synthetic: "incomplete_turn"`. A host that replays transcript
+   * history back into a model (context rebuilding, summarization) should filter
+   * events carrying `raw.synthetic` so this note is never fed back as assistant
+   * turn content.
    */
   private async emitIncompleteNote(info: Record<string, unknown>): Promise<void> {
     const messageId = str(info["id"]);

package/src/types.ts

@@ -998,6 +998,48 @@ export type BackgroundTaskType = "subagent" | "process" | "unknown";
 /** Lifecycle edge represented by one `background_task` StreamEvent. */
 export type BackgroundTaskPhase = "started" | "progress" | "completed";
 
+/**
+ * A background task's delivered output.
+ *
+ * Present only on the event where the provider actually *hands the result
+ * back* — distinct from a state patch that merely says the task reached a
+ * terminal status. Claude emits both for one completion (`task_updated` then
+ * `task_notification`), and they are different records, not duplicates: only
+ * the delivery carries the summary, the output file, and the `toolUseId`
+ * linking the task to the call that launched it.
+ *
+ * Collapsing the two into one indistinguishable "completed" event is what
+ * made hosts render every finished task twice: once with its report and once
+ * with nothing. Only the delivery carries the summary and the output file
+ * (`toolUseId` is also on the task's `started` record).
+ *
+ * Absent on a task that was cut short — a stop or a kill delivers no result.
+ */
+export interface BackgroundTaskReport {
+  /** The task's final output as the provider summarized it. */
+  summary: string | null;
+  /** Path to the task's full transcript/output on disk, when the provider writes one. */
+  outputFile: string | null;
+  /** What the task consumed, when reported. */
+  usage: {
+    totalTokens: number | null;
+    toolUses: number | null;
+    durationMs: number | null;
+  } | null;
+}
+
+/**
+ * Why a turn began.
+ *
+ * - `send` — dispatched through `send()`. Usually the host; agentex's own
+ *   emulated goal loop also continues a session this way, so this means
+ *   "someone called send()", not strictly "the user".
+ * - `resume` — the provider started it on its own. Claude does this when a
+ *   background task finishes: it enqueues a task-notification as user input,
+ *   which opens a fresh turn with no host involvement.
+ */
+export type TurnTrigger = "send" | "resume";
+
 /** Current normalized state carried by a `background_task` event. */
 export type BackgroundTaskStatus =
   | "pending"
@@ -1229,6 +1271,61 @@ export type StreamEvent =
       description: string | null;
       summary: string | null;
       parentTaskId: string | null;
+      /**
+       * The `tool_call` id that launched this task, when the provider reports
+       * it. This is the structured link between a task and the tool call it
+       * came from — the same id Claude writes into a subagent's `meta.json`.
+       */
+      toolUseId: string | null;
+      /**
+       * The task's delivered output, on the event that delivers it, else null.
+       * A terminal `status` says the task finished; a non-null `report` says
+       * its result is being handed back. See `BackgroundTaskReport`.
+       */
+      report: BackgroundTaskReport | null;
+    } & BaseStreamEventFields)
+  /**
+   * A turn opened. Pairs with `result`, which closes one.
+   *
+   * Hosts that track "is the agent working" cannot derive it from their own
+   * dispatch alone, because not every turn is theirs: when a background task
+   * finishes, Claude enqueues a notification as user input and starts a turn
+   * by itself. A host keying off its own `send()` sees that turn as idle and
+   * reports the session as finished while it is visibly working.
+   *
+   * Emitted for host-initiated turns too, so `turn_start` → `result` describes
+   * turn liveness straight off the stream.
+   *
+   * Deliberately does not name the background task behind a `resume`. Claude
+   * delivers a task's result and opens the turn as two unlinked records, and
+   * with several tasks in flight the pairing is not recoverable from the wire
+   * — every attempt to infer it produced a plausible id that was sometimes
+   * simply wrong. Correlate through `background_task.report` and `toolUseId`,
+   * which the provider does state.
+   */
+  | ({
+      type: "turn_start";
+      turnId: string;
+      trigger: TurnTrigger;
+    } & BaseStreamEventFields)
+  /**
+   * A turn closed. Every `turn_start` is followed by exactly one of these.
+   *
+   * `result` cannot serve as the close signal on its own: a message the CLI
+   * cancels, discards, or refuses opens a turn and produces no result at all,
+   * so a host tracking `turn_start` → `result` would stay busy forever. This
+   * is the guaranteed counterpart; `result` remains the outcome payload.
+   */
+  | ({
+      type: "turn_end";
+      turnId: string;
+      trigger: TurnTrigger;
+      /**
+       * Why the turn ended. `result` means a normal completion whose payload
+       * arrives as the accompanying `result` event; the rest are CLI verdicts
+       * on the message that produced no result.
+       */
+      reason: "result" | "cancelled" | "discarded" | "refused" | "session_closed";
     } & BaseStreamEventFields)
   | ({
       type: "result";