@agentex/agent 0.0.34 → 0.0.36

package/src/providers/opencode/discovery.ts

@@ -1,5 +1,6 @@
 import type { ListModelsOptions, ProviderModel } from "../../types.js";
 import { acquireOpenCodeRuntime } from "./runtime.js";
+import { withModelCache } from "../../utils/model-cache.js";
 
 function record(value: unknown): Record<string, unknown> {
   return value && typeof value === "object" && !Array.isArray(value)
@@ -59,11 +60,13 @@ export function openCodeModelsFromPayload(payload: Record<string, unknown>): Pro
 }
 
 export async function listOpenCodeModels(options: ListModelsOptions = {}): Promise<ProviderModel[]> {
-  const runtime = await acquireOpenCodeRuntime(options);
-  try {
-    const payload = await runtime.server.client.json<Record<string, unknown>>("/provider");
-    return openCodeModelsFromPayload(payload);
-  } finally {
-    runtime.server.release();
-  }
+  return withModelCache("opencode", options, options.cacheTtlMs, async () => {
+    const runtime = await acquireOpenCodeRuntime(options);
+    try {
+      const payload = await runtime.server.client.json<Record<string, unknown>>("/provider");
+      return openCodeModelsFromPayload(payload);
+    } finally {
+      runtime.server.release();
+    }
+  });
 }

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

@@ -54,6 +54,83 @@ export function turnStatusFromMessage(info: unknown): "completed" | "failed" {
   return m && m["error"] ? "failed" : "completed";
 }
 
+/**
+ * Finish reasons that represent the model deliberately ending its turn. Anything
+ * outside this set that also produced no text is treated as an incomplete turn
+ * (see `terminalOutcome`). `tool-calls` is included because it's an intermediate
+ * step in the agent loop, not an empty terminal turn.
+ */
+const CLEAN_FINISH_REASONS = new Set(["stop", "length", "end_turn", "stop_sequence", "tool-calls"]);
+
+/** User-facing note for a turn that ended with no reply (provider dropped the stream). */
+export function incompleteTurnMessage(finish: string | null): string {
+  const reason = finish ? ` (finish reason "${finish}")` : "";
+  return (
+    `The model ended the turn without sending a reply${reason}. ` +
+    "The upstream provider returned no content, which usually means the stream was dropped. " +
+    "Send your message again to retry."
+  );
+}
+
+export interface TerminalOutcome {
+  status: "completed" | "failed" | "aborted";
+  errorCode: string | null;
+  errorMessage: string | null;
+  /**
+   * True when the turn ended with no reply, no tool output, and no error — the
+   * "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 reports as `aborted` below.
+   */
+  incomplete: boolean;
+}
+
+/**
+ * Classify a terminal assistant message. Extends `turnStatusFromMessage` by
+ * catching the empty-turn case so a dropped stream surfaces as `failed` (with a
+ * 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 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 };
+  }
+
+  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",
+      errorCode: "incomplete_turn",
+      errorMessage: incompleteTurnMessage(finish),
+      incomplete: true,
+    };
+  }
+  return { status: "completed", errorCode: null, errorMessage: null, incomplete: false };
+}
+
 /** Map opencode's `tokens` (+ model identity) to agentex usage. */
 export function usageFromMessage(info: unknown): Record<string, TokenUsage> | undefined {
   const m = rec(info);

package/src/providers/opencode/history.ts

@@ -15,7 +15,14 @@ import { assertSessionRecord, createSessionRecord, MalformedSessionRecordError }
 import { acquireOpenCodeRuntime } from "./runtime.js";
 import { opencodeSessionCodec } from "./codec.js";
 import { createOpenCodeSession } from "./http-session.js";
-import { mapOpenCodePart, mapOpenCodeToolCall, type OcBaseInfo } from "./event-parse.js";
+import {
+  assistantTextFromParts,
+  incompleteTurnMessage,
+  mapOpenCodePart,
+  mapOpenCodeToolCall,
+  terminalOutcome,
+  type OcBaseInfo,
+} from "./event-parse.js";
 
 const PAGE_SIZE = 100;
 const MAX_PAGES = 100;
@@ -209,16 +216,37 @@ export function historicalEvents(
   const lastPartId = events.at(-1)?.partId;
   const finished = string(info["finish"]) !== null || info["error"] != null;
   if (messageId && lastPartId && finished) {
-    const error = info["error"] != null;
+    const hasVisibleText = assistantTextFromParts(message.parts).trim().length > 0;
+    const term = terminalOutcome(info, hasVisibleText);
+    // A turn that ended with no reply (upstream dropped the stream) gets a
+    // visible note, deduped against the live session's note by the shared
+    // `:incomplete` event id.
+    if (term.incomplete) {
+      events.push({
+        partId: lastPartId,
+        event: {
+          type: "assistant",
+          text: incompleteTurnMessage(string(info["finish"])),
+          timestamp,
+          providerType: "opencode",
+          sessionId,
+          messageId,
+          eventId: `${messageId}:incomplete`,
+          turnId: null,
+          parentToolCallId: null,
+          raw: { synthetic: "incomplete_turn", info },
+        },
+      });
+    }
     events.push({
       partId: lastPartId,
       event: {
         type: "result",
         text: "",
         costUsd: typeof info["cost"] === "number" ? info["cost"] : null,
-        isError: error,
+        isError: term.status !== "completed",
         stopReason: null,
-        terminalReason: error ? "failed" : "completed",
+        terminalReason: term.status,
         numTurns: 1,
         durationMs: null,
         timestamp,

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

@@ -25,9 +25,10 @@ import { opencodeSessionCodec } from "./codec.js";
 import { prepareOpenCodeSkillConfig } from "./skill-config.js";
 import {
   assistantTextFromParts,
+  incompleteTurnMessage,
   mapOpenCodePart,
   mapOpenCodeToolCall,
-  turnStatusFromMessage,
+  terminalOutcome,
   usageFromMessage,
   type OcBaseInfo,
 } from "./event-parse.js";
@@ -83,6 +84,12 @@ class OpenCodeSession implements AgentSession {
   private readonly _seenTextLen = new Map<string, number>();
   private readonly _emittedToolCall = new Set<string>();
   private readonly _emittedToolResult = new Set<string>();
+  /**
+   * messageID → role, learned from `message.updated` SSE frames. Lets `emitPart`
+   * drop a user message's own text part, which opencode streams once a turn is
+   * active and would otherwise surface as an assistant bubble echoing the prompt.
+   */
+  private readonly _messageRoles = new Map<string, string>();
   private _sse: AbortController | null = null;
   private readonly _handledInput = new Set<string>();
   private readonly _inputInFlight = new Set<string>();
@@ -245,6 +252,17 @@ class OpenCodeSession implements AgentSession {
       if (request) await this.handleQuestion(request);
       return;
     }
+    if (payload["type"] === "message.updated") {
+      // Track message roles so emitPart can distinguish a user message's own
+      // text part (echoed onto the SSE feed) from real assistant output.
+      const info = rec(rec(payload["properties"])?.["info"]) ?? rec(payload["properties"]);
+      const mid = info ? str(info["id"]) : null;
+      const role = info ? str(info["role"]) : null;
+      if (mid && role && str(info!["sessionID"]) === this._sessionId) {
+        this._messageRoles.set(mid, role);
+      }
+      return;
+    }
     if (payload["type"] !== "message.part.updated") return;
     const props = rec(payload["properties"]);
     const part = rec(props?.["part"]);
@@ -403,6 +421,12 @@ class OpenCodeSession implements AgentSession {
     // The SSE feed is global and async: drop stragglers that arrive while no turn
     // is active so a finished turn's late parts don't surface against the next one.
     if (!this._turnActive) return;
+    // Drop parts belonging to a user message — opencode re-streams the prompt's
+    // own text part once the turn is active, which would echo as an assistant
+    // bubble. Unknown role (message.updated not seen yet) falls through and
+    // emits, so a race can never suppress genuine assistant output.
+    const messageId = str(part["messageID"]);
+    if (messageId && this._messageRoles.get(messageId) === "user") return;
     const info: OcBaseInfo = {
       provider: "opencode",
       sessionId: this._sessionId,
@@ -467,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";
   }
 
@@ -537,18 +567,20 @@ class OpenCodeSession implements AgentSession {
           const data = (await res.json()) as Record<string, unknown>;
           terminalRaw = data;
           const info = rec(data["info"]);
-          const status = turnStatusFromMessage(info);
           const usage = usageFromMessage(info);
           const summary = assistantTextFromParts(data["parts"]) || null;
           const costUsd = info ? num(info["cost"]) : null;
-          const errorMessage = status === "failed" ? JSON.stringify(info?.["error"] ?? null) : null;
+          const term = terminalOutcome(info, summary != null && summary.trim().length > 0);
+          // A silent empty turn (upstream dropped the stream) would otherwise
+          // render as a stall. Surface a visible note before the terminal result.
+          if (term.incomplete && info) await this.emitIncompleteNote(info);
           outcome = {
             summary,
             ...(usage ? { usage } : {}),
             costUsd,
-            status,
-            errorCode: status === "failed" ? "agent_error" : null,
-            errorMessage,
+            status: term.status,
+            errorCode: term.errorCode,
+            errorMessage: term.errorMessage,
           };
         }
       }
@@ -584,12 +616,42 @@ class OpenCodeSession implements AgentSession {
     return outcome;
   }
 
+  /**
+   * Surface a turn that ended with no reply as a visible assistant note. The
+   * 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"]);
+    await this.emit({
+      type: "assistant",
+      text: incompleteTurnMessage(str(info["finish"])),
+      timestamp: new Date().toISOString(),
+      providerType: "opencode",
+      sessionId: this._sessionId,
+      messageId,
+      eventId: messageId ? `${messageId}:incomplete` : null,
+      turnId: null,
+      parentToolCallId: null,
+      raw: { synthetic: "incomplete_turn", info },
+    });
+  }
+
   private async emitTerminal(
     outcome: TurnResult,
     raw: Record<string, unknown>,
     startedAt: number,
   ): Promise<void> {
     const info = rec(raw["info"]);
+    const messageId = info ? str(info["id"]) : null;
     await this.emit({
       type: "result",
       text: outcome.summary ?? outcome.errorMessage ?? "",
@@ -602,8 +664,10 @@ class OpenCodeSession implements AgentSession {
       timestamp: new Date().toISOString(),
       providerType: "opencode",
       sessionId: this._sessionId,
-      messageId: info ? str(info["id"]) : null,
-      eventId: info ? str(info["id"]) : null,
+      messageId,
+      // Match the reconcile path's `${messageId}:result` id so the live and
+      // catch-up terminal markers dedup instead of both landing as rows.
+      eventId: messageId ? `${messageId}:result` : null,
       turnId: null,
       parentToolCallId: null,
       raw,

package/src/types.ts

@@ -1203,17 +1203,29 @@ export type StreamEvent =
    * `phase: "completed"` settles only this task. It is never a root turn
    * result and must not be used to resolve `SendHandle.result`.
    *
-   * Events are reducer-friendly snapshots. `status` is always populated,
-   * while description/summary may be null when the provider did not report
-   * them. `parentTaskId` identifies a nested background task when that lineage
-   * is available.
+   * Events are reducer-friendly snapshots, and every optional field follows one
+   * rule: null means the provider did not report it, so keep what you already
+   * have. That includes `status` — a sparse patch can rename a task without
+   * saying anything about whether it is still running. `parentTaskId`
+   * identifies a nested background task when that lineage is available.
    */
   | ({
       type: "background_task";
       taskId: string;
       taskType: BackgroundTaskType;
       phase: BackgroundTaskPhase;
-      status: BackgroundTaskStatus;
+      /**
+       * The task's state as the provider reported it, or `null` for "no change
+       * reported" — read it as "keep whatever you have".
+       *
+       * Null rather than a default because the alternative is asserting a state
+       * the provider never sent. A sparse patch that only renames a task would
+       * otherwise claim `running` and silently resurrect a `paused` one. This
+       * matches `description` and `summary`, where null already means "the
+       * provider did not report this"; status was the one field that invented a
+       * value instead of admitting absence.
+       */
+      status: BackgroundTaskStatus | null;
       description: string | null;
       summary: string | null;
       parentTaskId: string | null;
@@ -1373,6 +1385,8 @@ export interface AuthResolveContext {
 export interface ProviderModel {
   id: string;
   name: string;
+  /** One-line blurb from the provider's own catalog, when it ships one. */
+  description?: string;
   provider?: string;
   providerName?: string;
   variants?: Array<{

package/src/utils/model-cache.ts

@@ -0,0 +1,67 @@
+/**
+ * TTL cache behind `listModels()`.
+ *
+ * `ListModelsOptions.cacheTtlMs` was part of the public shape long before
+ * anything honored it, so callers could pass a TTL and silently get an
+ * uncached spawn every time. Model discovery costs a CLI round trip (or
+ * several, when a provider has to probe), which is why the option existed.
+ *
+ * Entries are keyed on the runtime identity that can change the answer —
+ * binary override, cwd, and any env the caller passed. Env is folded in
+ * because a different credential can yield a different catalog; only the key
+ * names and a hash-free ordering of values are used, and the key never leaves
+ * this process.
+ */
+
+const store = new Map<string, { expiresAt: number; value: unknown }>();
+
+export interface ModelCacheIdentity {
+  cwd?: string | undefined;
+  env?: Record<string, string | undefined> | undefined;
+  config?: { command?: string | undefined } | undefined;
+}
+
+function identityKey(provider: string, identity: ModelCacheIdentity): string {
+  const env = Object.entries(identity.env ?? {})
+    .filter(([, value]) => value !== undefined)
+    .sort(([left], [right]) => left.localeCompare(right));
+  return JSON.stringify([provider, identity.cwd ?? "", identity.config?.command ?? "", env]);
+}
+
+/**
+ * Run `load` at most once per TTL window for the given identity.
+ *
+ * `cacheTtlMs` of 0 (or undefined) forces a fresh load and refreshes the entry,
+ * which is how callers implement an explicit "refresh catalog" action.
+ * Rejections are never cached: a discovery failure is usually a transient
+ * "CLI is mid-upgrade" and should not pin an error for the whole window.
+ */
+export async function withModelCache<T>(
+  provider: string,
+  identity: ModelCacheIdentity,
+  cacheTtlMs: number | undefined,
+  load: () => Promise<T>,
+): Promise<T> {
+  const key = identityKey(provider, identity);
+  const ttl = cacheTtlMs ?? 0;
+  if (ttl > 0) {
+    const hit = store.get(key);
+    if (hit && hit.expiresAt > Date.now()) return hit.value as T;
+  }
+  const value = await load();
+  if (ttl > 0) store.set(key, { expiresAt: Date.now() + ttl, value });
+  else store.delete(key);
+  return value;
+}
+
+/** Drop cached catalogs. Scoped to one provider when named, otherwise all. */
+export function clearModelCache(provider?: string): void {
+  if (!provider) {
+    store.clear();
+    return;
+  }
+  const prefix = `["${provider}"`;
+  for (const key of [...store.keys()]) {
+    if (key.startsWith(prefix)) store.delete(key);
+  }
+}