@cortexkit/aft-opencode 0.27.1 → 0.28.1

package/src/shared/live-server-client.ts

@@ -0,0 +1,132 @@
+/**
+ * Workaround helper for the OpenCode plugin promptAsync runner-split bug
+ * (https://github.com/anomalyco/opencode/issues/28202).
+ *
+ * OpenCode's plugin-provided `input.client` is constructed with
+ * `fetch: async (...args) => Server.Default().app.fetch(...args)`, which
+ * routes requests through `HttpApiApp.webHandler()` and a SEPARATE Effect
+ * `memoMap` from the one used by the live HTTP listener. Since
+ * `SessionRunState` is a per-memo-map in-memory layer, plugin-origin
+ * `promptAsync` calls observe an "idle" runner while the live UI turn is
+ * still running. The result is that `ensureRunning` fails to coalesce and
+ * OpenCode persists multiple assistant children under a single synthetic
+ * user parent — what users see as duplicate "stop" messages after every
+ * background-bash completion reminder.
+ *
+ * The workaround is to bypass `input.client` for the wake path and build
+ * a separate `createOpencodeClient` configured to hit `input.serverUrl`
+ * via `globalThis.fetch`. That client enters the same live listener the
+ * UI uses, so the active session's `SessionRunState` is the one that
+ * resolves `ensureRunning` and overlapping turns coalesce correctly.
+ *
+ * Tracked upstream as anomalyco/opencode#28202. When OpenCode fixes the
+ * runtime split, this helper and its single consumer in `bg-notifications.ts`
+ * can be deleted and the wake path can go back to `input.client`.
+ */
+
+import { createOpencodeClient } from "@opencode-ai/sdk";
+
+export type LiveServerClient = ReturnType<typeof createOpencodeClient>;
+
+/**
+ * Cache key is `${serverUrl}|${directory}`. Both are stable per OpenCode
+ * session/project pair, so one client is reused across many wakes. We don't
+ * key on `serverUrl + auth header` because the auth env vars are server-wide
+ * — if they change we'd want a fresh client anyway; in practice they're set
+ * once at process start.
+ */
+const clientCache = new Map<string, LiveServerClient>();
+
+function cacheKey(serverUrl: string, directory: string): string {
+  return `${serverUrl}|${directory}`;
+}
+
+/**
+ * Build the Basic-auth header OpenCode's server expects when
+ * `OPENCODE_SERVER_PASSWORD` is set. Read at call time (not at module load)
+ * so test setup can mutate `process.env` between cases.
+ */
+function serverAuthHeaders(): Record<string, string> | undefined {
+  const password = process.env.OPENCODE_SERVER_PASSWORD;
+  if (!password) return undefined;
+  const username = process.env.OPENCODE_SERVER_USERNAME ?? "opencode";
+  return {
+    Authorization: `Basic ${Buffer.from(`${username}:${password}`).toString("base64")}`,
+  };
+}
+
+/**
+ * Return a cached `createOpencodeClient` pointed at the live HTTP listener
+ * for the given `(serverUrl, directory)` pair. One client object is reused
+ * across many wakes for a given session.
+ *
+ * The `fetch` is bound to `globalThis.fetch` explicitly. Without this, the
+ * SDK would fall back to `globalThis.fetch` anyway in normal Node runtimes,
+ * but we set it on purpose so anyone reading this code (or grepping for the
+ * bug fix) can see that we intentionally chose the live HTTP transport.
+ */
+export function getLiveServerClient(serverUrl: string, directory: string): LiveServerClient {
+  const key = cacheKey(serverUrl, directory);
+  const cached = clientCache.get(key);
+  if (cached) return cached;
+  const client = createOpencodeClient({
+    baseUrl: serverUrl,
+    directory,
+    headers: serverAuthHeaders(),
+    fetch: globalThis.fetch,
+  });
+  clientCache.set(key, client);
+  return client;
+}
+
+/** Test helper — drop the cache between cases so each test starts clean. */
+export function __resetLiveServerClientCacheForTests(): void {
+  clientCache.clear();
+}
+
+/**
+ * True when the current runtime is Bun. OpenCode's TUI ships with Bun;
+ * the Electron Desktop app ships with Node. We use this to gate the
+ * `--port 0` nudge: Desktop is unaffected by anomalyco/opencode#28202
+ * because Node's webidl polyfill is complete, so undici v8 (and the live
+ * HTTP server) work without additional flags.
+ */
+export function isBunRuntime(): boolean {
+  return typeof (globalThis as { Bun?: unknown }).Bun !== "undefined";
+}
+
+/**
+ * Probe whether `serverUrl` accepts a connection within `timeoutMs`.
+ * Returns `true` for any HTTP response (including 4xx / 5xx) since the
+ * goal is to confirm the listener exists. Returns `false` on connection
+ * refused, DNS failure, timeout, or undefined URL.
+ *
+ * Used at plugin init under Bun to detect TUI sessions started without
+ * `opencode --port 0` — those bind an internal-only listener that 404s
+ * for `/session/...` endpoints and breaks AFT's wake path.
+ */
+export async function probeServerReachable(
+  serverUrl: string | undefined,
+  timeoutMs = 1500,
+): Promise<boolean> {
+  if (!serverUrl) return false;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    // Hit a path that actually exists on the OpenCode HTTP API so a
+    // 200 confirms the API server is up, not just any random listener
+    // (e.g. an internal IPC port that happens to accept TCP but rejects
+    // all paths with 404 — which is exactly what TUI binds without
+    // `--port 0`).
+    const probeUrl = new URL("/session", serverUrl).toString();
+    const res = await globalThis.fetch(probeUrl, {
+      method: "GET",
+      signal: controller.signal,
+    });
+    return res.status >= 200 && res.status < 500;
+  } catch {
+    return false;
+  } finally {
+    clearTimeout(timer);
+  }
+}

package/src/shared/rpc-client.ts

@@ -1,19 +1,23 @@
-import { readFileSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
 import { warn } from "../logger";
-import { rpcPortFilePath } from "./rpc-utils";
+import { rpcPortFileDir, rpcPortFilePath } from "./rpc-utils";
 
 const MAX_RETRIES = 10;
 const RETRY_DELAY_MS = 500;
 const REQUEST_TIMEOUT_MS = 5000;
 
+type PortInfo = { port: number; token: string | null };
+
 export class AftRpcClient {
   private port: number | null = null;
   private token: string | null = null;
-  private portFilePath: string;
-  private healthChecked = false;
+  private portsDir: string;
+  private legacyPortFile: string;
 
   constructor(storageDir: string, directory: string) {
-    this.portFilePath = rpcPortFilePath(storageDir, directory);
+    this.portsDir = rpcPortFileDir(storageDir, directory);
+    this.legacyPortFile = rpcPortFilePath(storageDir, directory);
   }
 
   /** Call an RPC method. Retries port resolution if the server isn't ready yet. */
@@ -21,111 +25,129 @@ export class AftRpcClient {
     method: string,
     params: Record<string, unknown> = {},
   ): Promise<T> {
-    const info = await this.resolvePortInfo();
-    if (!info) {
+    // Try ALL discovered ports for this project (OpenCode TUI under --port 0
+    // loads our plugin twice in the same process, so two RPC servers listen
+    // and we have to try both — only one's bridge is actually warm).
+    const infos = await this.resolvePortInfos();
+    if (infos.length === 0) {
       throw new Error("AFT RPC server not available");
     }
 
-    return this.callResolved<T>(method, params, info, true);
+    // First pass: try every port. Prefer responses that look like "warm
+    // bridge" output (i.e. not the synthetic `status: "not_initialized"`
+    // placeholder served when this instance's bridge hasn't been spawned).
+    let placeholder: T | null = null;
+    let lastError: unknown = null;
+    for (const info of infos) {
+      try {
+        const result = await this.callOne<T>(method, params, info);
+        if (this.looksLikePlaceholder(result)) {
+          placeholder = result; // remember but keep trying
+          continue;
+        }
+        // Warm response — cache this port for subsequent calls.
+        this.port = info.port;
+        this.token = info.token;
+        return result;
+      } catch (err) {
+        lastError = err;
+      }
+    }
+
+    // All ports returned placeholder OR failed. Use placeholder if we have
+    // one (sidebar then shows the lazy-spawn UI); otherwise rethrow last error.
+    if (placeholder !== null) return placeholder;
+    throw lastError instanceof Error ? lastError : new Error(String(lastError));
   }
 
-  private async callResolved<T>(
+  private async callOne<T>(
     method: string,
     params: Record<string, unknown>,
-    info: { port: number; token: string | null },
-    retryOnConnectionFailure: boolean,
+    info: PortInfo,
   ): Promise<T> {
-    let response: Response;
-    try {
-      response = await this.fetchWithTimeout(`http://127.0.0.1:${info.port}/rpc/${method}`, {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ ...params, token: info.token }),
-      });
-    } catch (err) {
-      if (!retryOnConnectionFailure) throw err;
-      return this.retryAfterReset<T>(method, params, err);
-    }
-
+    const response = await this.fetchWithTimeout(`http://127.0.0.1:${info.port}/rpc/${method}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ ...params, token: info.token }),
+    });
     if (!response.ok) {
       const text = await response.text();
-      if (response.status >= 500 && retryOnConnectionFailure) {
-        return this.retryAfterReset<T>(method, params, `HTTP ${response.status}: ${text}`);
-      }
       throw new Error(`RPC ${method} failed (${response.status}): ${text}`);
     }
-
     return (await response.json()) as T;
   }
 
-  private async retryAfterReset<T>(
-    method: string,
-    params: Record<string, unknown>,
-    reason: unknown,
-  ): Promise<T> {
-    const message = reason instanceof Error ? reason.message : String(reason);
-    warn(`RPC ${method} failed on cached port; retrying after port refresh (${message})`);
-    this.reset();
-    const refreshed = await this.resolvePortInfo();
-    if (!refreshed) {
-      throw new Error("AFT RPC server not available after port refresh");
-    }
-    return this.callResolved<T>(method, params, refreshed, false);
+  /**
+   * Heuristic for "this response is the lazy-spawn placeholder, not the real
+   * data." We treat any `not_initialized` status as a placeholder so the
+   * client knows to try the next port (the warm one).
+   */
+  private looksLikePlaceholder<T>(result: T): boolean {
+    if (!result || typeof result !== "object") return false;
+    const status = (result as Record<string, unknown>).status;
+    return status === "not_initialized";
   }
 
-  /** Check if the RPC server is reachable. */
+  /** Check if any RPC server is reachable. */
   async isAvailable(): Promise<boolean> {
     try {
-      const port = await this.resolvePort();
-      return port !== null;
+      const infos = await this.resolvePortInfos();
+      return infos.length > 0;
     } catch {
       return false;
     }
   }
 
-  private async resolvePort(): Promise<number | null> {
-    return (await this.resolvePortInfo())?.port ?? null;
-  }
-
-  private async resolvePortInfo(): Promise<{ port: number; token: string | null } | null> {
-    if (this.port && this.healthChecked) {
-      return { port: this.port, token: this.token };
-    }
-
-    if (this.port) {
-      const alive = await this.healthCheck(this.port);
-      if (alive) {
-        this.healthChecked = true;
-        return { port: this.port, token: this.token };
-      }
-      this.port = null;
-      this.token = null;
-      this.healthChecked = false;
-    }
-
+  /**
+   * Discover all live RPC port files for this project. Tries the per-instance
+   * directory first (v0.28.2+), then falls back to the single legacy `port`
+   * file (older plugin versions in mixed deployments).
+   */
+  private async resolvePortInfos(): Promise<PortInfo[]> {
     for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
-      const info = this.readPortFile();
-      if (info) {
-        const alive = await this.healthCheck(info.port);
-        if (alive) {
-          this.port = info.port;
-          this.token = info.token;
-          this.healthChecked = true;
-          return info;
+      const infos = this.readAllPortFiles();
+      if (infos.length > 0) {
+        const alive: PortInfo[] = [];
+        for (const info of infos) {
+          if (await this.healthCheck(info.port)) {
+            alive.push(info);
+          }
         }
+        if (alive.length > 0) return alive;
       }
-
       if (attempt < MAX_RETRIES - 1) {
         await new Promise((r) => setTimeout(r, RETRY_DELAY_MS));
       }
     }
+    return [];
+  }
 
-    return null;
+  private readAllPortFiles(): PortInfo[] {
+    const collected: PortInfo[] = [];
+    // Per-instance directory (v0.28.2+): one file per plugin load.
+    if (existsSync(this.portsDir)) {
+      try {
+        const entries = readdirSync(this.portsDir);
+        for (const entry of entries) {
+          if (!entry.endsWith(".json")) continue;
+          const info = this.parsePortFile(join(this.portsDir, entry));
+          if (info) collected.push(info);
+        }
+      } catch {
+        // ignore read errors
+      }
+    }
+    // Legacy single file (pre-v0.28.2 plugin versions in mixed deployments).
+    if (collected.length === 0) {
+      const info = this.parsePortFile(this.legacyPortFile);
+      if (info) collected.push(info);
+    }
+    return collected;
   }
 
-  private readPortFile(): { port: number; token: string | null } | null {
+  private parsePortFile(path: string): PortInfo | null {
     try {
-      const content = readFileSync(this.portFilePath, "utf-8").trim();
+      const content = readFileSync(path, "utf-8").trim();
       let port: number;
       let token: string | null;
       if (content.startsWith("{")) {
@@ -170,6 +192,5 @@ export class AftRpcClient {
   reset(): void {
     this.port = null;
     this.token = null;
-    this.healthChecked = false;
   }
 }

package/src/shared/rpc-server.ts

@@ -1,9 +1,9 @@
 import { randomBytes } from "node:crypto";
 import { mkdirSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { createServer, type IncomingMessage, type Server, type ServerResponse } from "node:http";
-import { dirname } from "node:path";
+import { dirname, join } from "node:path";
 import { log, warn } from "../logger";
-import { rpcPortFilePath } from "./rpc-utils";
+import { rpcPortFileDir } from "./rpc-utils";
 
 type RpcHandler = (params: Record<string, unknown>) => Promise<Record<string, unknown>>;
 
@@ -13,9 +13,14 @@ export class AftRpcServer {
   private token: string | null = null;
   private handlers = new Map<string, RpcHandler>();
   private portFilePath: string;
+  private portsDir: string;
+  /** Unique per-instance ID — distinguishes our entry from duplicate plugin loads. */
+  private instanceId: string;
 
   constructor(storageDir: string, directory: string) {
-    this.portFilePath = rpcPortFilePath(storageDir, directory);
+    this.portsDir = rpcPortFileDir(storageDir, directory);
+    this.instanceId = randomBytes(8).toString("hex");
+    this.portFilePath = join(this.portsDir, `${this.instanceId}.json`);
   }
 
   /** Register an RPC method handler. */

package/src/shared/rpc-utils.ts

@@ -13,9 +13,31 @@ export function projectHash(directory: string): string {
 }
 
 /**
- * Get the per-project RPC port file path.
+ * Legacy per-project RPC port file path (single file).
+ *
+ * Kept exported for backward-compatibility readers — when an older plugin
+ * instance is running alongside a newer one, the older one still writes
+ * to this path. New code prefers `rpcPortFileDir` (one file per instance)
+ * so that two plugin instances under `opencode --port 0` don't overwrite
+ * each other's port info. The client falls back to the legacy file if
+ * the new directory has no entries.
  */
 export function rpcPortFilePath(storageDir: string, directory: string): string {
   const hash = projectHash(directory);
   return join(storageDir, "rpc", hash, "port");
 }
+
+/**
+ * Per-project RPC port directory. Each plugin instance writes a file
+ * `<instance-id>.json` into this directory so the client can discover
+ * ALL active plugin instances (e.g. the two created by OpenCode TUI when
+ * launched with `--port 0`). The client tries each port and uses the
+ * first one whose bridge is warm.
+ *
+ * Replaces the single `port` file used pre-v0.28.2 (which suffered from
+ * last-write-wins racing under `--port 0`).
+ */
+export function rpcPortFileDir(storageDir: string, directory: string): string {
+  const hash = projectHash(directory);
+  return join(storageDir, "rpc", hash, "ports");
+}

package/src/tui/index.tsx

@@ -174,12 +174,16 @@ const StatusDialog = (props: StatusDialogProps) => {
       paddingTop={1}
       paddingBottom={1}
     >
-      {/* Title */}
+      {/* Title. Hide version while the lazy-spawn placeholder is showing — users
+          read `vunknown` next to "AFT Status" as broken state instead of "AFT
+          has not been used yet for this project". */}
       <box justifyContent="center" width="100%" marginBottom={1} flexDirection="row" gap={2}>
         <text fg={t().accent}>
           <b>⚡ AFT Status</b>
         </text>
-        <text fg={t().textMuted}>v{status()?.version ?? packageJson.version}</text>
+        {status()?.cache_role !== "not_initialized" && (
+          <text fg={t().textMuted}>v{status()?.version ?? packageJson.version}</text>
+        )}
       </box>
 
       {/* Error / not-yet-ready state */}
@@ -197,7 +201,8 @@ const StatusDialog = (props: StatusDialogProps) => {
       {status()?.cache_role === "not_initialized" ? (
         <box width="100%" marginTop={1} justifyContent="center">
           <text fg={t().textMuted}>
-            {status()!.message || "Waiting for first tool call to populate"}
+            {status()!.message ||
+              "AFT bridge is now spawned lazily, information here will be populated after first tool call."}
           </text>
         </box>
       ) : null}
@@ -224,8 +229,10 @@ const StatusDialog = (props: StatusDialogProps) => {
         </box>
       ) : null}
 
-      {/* 2-column body */}
-      {status() ? (
+      {/* 2-column body. Gate on cache_role too so a synthetic not_initialized
+          snapshot doesn't render an empty grid of "unknown" / "—" rows
+          alongside the lazy-spawn placeholder message above. */}
+      {status() && status()!.cache_role !== "not_initialized" ? (
         <box flexDirection="row" width="100%" gap={4}>
           {/* Left column */}
           <box flexDirection="column" flexGrow={1} flexBasis={0}>
@@ -540,16 +547,24 @@ async function showStartupNotifications(api: TuiPluginApi): Promise<void> {
       show?: boolean;
       version?: string;
       features?: string[];
+      footer?: string;
     };
 
     if (announcement.show && announcement.version && announcement.features?.length) {
       const featureText = announcement.features.map((f: string) => `  • ${f}`).join("\n");
+      // Blank-line separator distinguishes the persistent footer (Discord
+      // invite, etc.) from the version-specific bullets.
+      const hasFooter =
+        typeof announcement.footer === "string" && announcement.footer.trim().length > 0;
+      const message = hasFooter
+        ? `What's new:\n\n${featureText}\n\n${announcement.footer}`
+        : `What's new:\n\n${featureText}`;
 
       api.ui.dialog.replace(
         () => (
           <api.ui.DialogAlert
             title={`AFT v${announcement.version}`}
-            message={`What's new:\n\n${featureText}`}
+            message={message}
             onConfirm={() => {
               // Mark as announced so it doesn't show again
               void client.call("mark-announced", {});