@agent-native/core 0.83.0 → 0.84.0

package/corpus/core/src/agent/tool-call-journal.ts

@@ -8,16 +8,18 @@
  * told about any tool call that started but whose outcome was never recorded.
  *
  * IMPORTANT — this is a pure read-over-the-ledger view. There is no new
- * recording hook anywhere in the hot path. The classification reuses the exact
- * positional `tool_start` → `tool_done` matching that `thread-data-builder.ts`
- * already relies on to rebuild durable turns:
+ * recording hook anywhere in the hot path. Classification uses input-aware
+ * `tool_start` → `tool_done` matching when a `tool_done` event carries its
+ * input, while preserving the legacy positional fallback that older ledger
+ * events and `thread-data-builder.ts` rely on:
  *
  *   - `tool_start` events carry `{ tool, input }` (no tool-call id at this
  *     layer; the ledger event stream omits it).
- *   - `tool_done` events carry `{ tool, result }`.
- *   - A `tool_done` is matched to the OLDEST still-open `tool_start` for the
- *     same tool name (FIFO per tool), mirroring how the dispatch loop emits a
- *     start immediately before its matching done.
+ *   - `tool_done` events carry `{ tool, input?, result }`.
+ *   - A `tool_done` with input is matched to the open start with the same tool
+ *     name and deep-canonicalized input.
+ *   - A legacy `tool_done` without input is matched to the OLDEST still-open
+ *     `tool_start` for the same tool name (FIFO per tool).
  *
  * A `tool_start` with no matching `tool_done` is the dangerous case: the call
  * began, its side effect may or may not have landed, and the interruption ate
@@ -32,7 +34,7 @@
  * effect again. Layer 2 is the stronger guarantee.
  */
 
-import type { AgentChatEvent } from "./types.js";
+import type { AgentChatEvent, AgentToolInput } from "./types.js";
 
 /** A single recorded tool-call ledger entry, classified by outcome. */
 export interface ToolCallJournalEntry {
@@ -46,7 +48,7 @@ export interface ToolCallJournalEntry {
   /** Tool / action name (from the `tool_start` event). */
   tool: string;
   /** Tool input captured at `tool_start`, if any. */
-  input?: Record<string, string>;
+  input?: AgentToolInput;
   /** 0-based position of the `tool_start` among all tool calls in the turn. */
   order: number;
   /** Result text from the matched `tool_done`, when the call completed. */
@@ -70,22 +72,53 @@ const INPUT_SIGNATURE_MAX_CHARS = 120;
 /** Max length of a per-tool-call result summary surfaced in the resume note. */
 const RESULT_SUMMARY_MAX_CHARS = 400;
 
-function inputSignature(input: Record<string, string> | undefined): string {
-  if (!input) return "";
-  let sig: string;
+function inputSignature(input: unknown): string {
+  if (input == null) return "";
   try {
-    // Stable key order so the same logical input produces the same signature
-    // regardless of how the engine serialized the object.
-    const sorted = Object.keys(input)
-      .sort()
-      .reduce<Record<string, string>>((acc, k) => {
-        acc[k] = input[k];
-        return acc;
-      }, {});
-    sig = JSON.stringify(sorted);
+    return JSON.stringify(canonicalizeForSignature(input));
   } catch {
-    sig = String(input);
+    return String(input);
+  }
+}
+
+function canonicalizeForSignature(
+  input: unknown,
+  seen = new WeakSet(),
+): unknown {
+  if (input == null) return input;
+  if (typeof input === "bigint") return input.toString();
+  if (typeof input === "function" || typeof input === "symbol") {
+    return String(input);
+  }
+  if (typeof input !== "object") return input;
+
+  if (seen.has(input)) return "[Circular]";
+  seen.add(input);
+  if (Array.isArray(input)) {
+    const output = input.map((value) =>
+      value === undefined
+        ? "[Undefined]"
+        : canonicalizeForSignature(value, seen),
+    );
+    seen.delete(input);
+    return output;
   }
+
+  const object = input as Record<string, unknown>;
+  const output: Record<string, unknown> = {};
+  for (const key of Object.keys(object).sort()) {
+    const value = object[key];
+    output[key] =
+      value === undefined
+        ? "[Undefined]"
+        : canonicalizeForSignature(value, seen);
+  }
+  seen.delete(input);
+  return output;
+}
+
+function displayInputSignature(input: unknown): string {
+  const sig = inputSignature(input);
   return sig.length > INPUT_SIGNATURE_MAX_CHARS
     ? sig.slice(0, INPUT_SIGNATURE_MAX_CHARS)
     : sig;
@@ -101,10 +134,9 @@ function inputSignature(input: Record<string, string> | undefined): string {
 export function classifyToolCallJournal(
   events: readonly AgentChatEvent[],
 ): ToolCallJournal {
-  // Open tool_start entries awaiting a matching tool_done, in FIFO order. We
-  // index by tool name so a tool_done matches the OLDEST open start for that
-  // same tool — the dispatch loop always emits start-then-done per call, so the
-  // first unmatched start of a given name is the one this done belongs to.
+  // Open tool_start entries awaiting a matching tool_done. We index by tool
+  // name first, then prefer matching input signatures when the done event
+  // carries input. Older ledger entries without done input fall back to FIFO.
   const openByTool = new Map<string, ToolCallJournalEntry[]>();
   const completed: ToolCallJournalEntry[] = [];
   let order = 0;
@@ -119,11 +151,9 @@ export function classifyToolCallJournal(
 
     if (event.type === "tool_start") {
       const tool = event.tool ?? "unknown";
-      const input = (event.input ?? undefined) as
-        | Record<string, string>
-        | undefined;
+      const input = event.input ?? undefined;
       const entry: ToolCallJournalEntry = {
-        key: `${tool}#${order}:${inputSignature(input)}`,
+        key: `${tool}#${order}:${displayInputSignature(input)}`,
         tool,
         ...(input ? { input } : {}),
         order,
@@ -138,8 +168,14 @@ export function classifyToolCallJournal(
     if (event.type === "tool_done") {
       const tool = event.tool ?? "unknown";
       const queue = openByTool.get(tool);
-      const entry = queue?.shift();
+      const entry = takeMatchingOpenEntry(queue, event);
       if (entry) {
+        if (isNonCompletedToolDone(event)) {
+          // Failed/blocked calls reached a terminal tool_done, but their side
+          // effect did not complete. Drop the matching start instead of
+          // classifying it as completed or interrupted.
+          continue;
+        }
         entry.result = event.result ?? "";
         completed.push(entry);
       }
@@ -159,6 +195,45 @@ export function classifyToolCallJournal(
   return { completed, interrupted };
 }
 
+function takeMatchingOpenEntry(
+  queue: ToolCallJournalEntry[] | undefined,
+  event: Extract<AgentChatEvent, { type: "tool_done" }>,
+): ToolCallJournalEntry | undefined {
+  if (!queue || queue.length === 0) return undefined;
+  if (event.input !== undefined) {
+    const doneSig = inputSignature(event.input);
+    const index = queue.findIndex(
+      (entry) => inputSignature(entry.input) === doneSig,
+    );
+    if (index >= 0) return queue.splice(index, 1)[0];
+  }
+  return queue.shift();
+}
+
+function isNonCompletedToolDone(
+  event: Extract<AgentChatEvent, { type: "tool_done" }>,
+): boolean {
+  if (event.completedSideEffect === false) return true;
+  if (event.isError === true) return true;
+
+  const result = (event.result ?? "").trim();
+  if (!result) return false;
+
+  // Legacy run events did not persist isError. Keep known non-execution results
+  // from becoming durable "completed" write calls after deploy.
+  return (
+    result.startsWith("Error: Unknown tool") ||
+    result.startsWith("Error running ") ||
+    result.startsWith("Invalid action parameters for ") ||
+    result.startsWith("Plan mode blocked ") ||
+    result.startsWith("Skipped ") ||
+    result.startsWith("Stopped after ") ||
+    result.startsWith("The tool was not executed") ||
+    result.startsWith("Awaiting human approval") ||
+    result.includes(" did NOT execute")
+  );
+}
+
 /** True when the journal has nothing worth telling a resuming model about. */
 export function isJournalEmpty(journal: ToolCallJournal): boolean {
   return journal.completed.length === 0 && journal.interrupted.length === 0;
@@ -184,7 +259,7 @@ export function findCompletedJournalEntry(
   input: unknown,
   consumedKeys?: Set<string>,
 ): ToolCallJournalEntry | undefined {
-  const wantSig = inputSignature(normalizeInputForSignature(input));
+  const wantSig = inputSignature(input);
   for (const entry of journal.completed) {
     if (entry.tool !== toolName) continue;
     if (inputSignature(entry.input) !== wantSig) continue;
@@ -195,20 +270,6 @@ export function findCompletedJournalEntry(
   return undefined;
 }
 
-/**
- * Coerce an arbitrary tool input into the `Record<string, string>` shape the
- * journal recorded at `tool_start` so signatures compare apples-to-apples. The
- * ledger stores `tool_start.input` as a string map; the live call's `input` is
- * the parsed object — both pass through `inputSignature`, which sorts keys and
- * JSON-stringifies, so a plain object compares correctly.
- */
-function normalizeInputForSignature(
-  input: unknown,
-): Record<string, string> | undefined {
-  if (input == null || typeof input !== "object") return undefined;
-  return input as Record<string, string>;
-}
-
 function summarizeResult(result: string | undefined): string {
   if (!result) return "(no result recorded)";
   const oneLine = result.replace(/\s+/g, " ").trim();
@@ -218,9 +279,9 @@ function summarizeResult(result: string | undefined): string {
     : oneLine;
 }
 
-function describeInput(input: Record<string, string> | undefined): string {
+function describeInput(input: unknown): string {
   if (!input) return "";
-  const sig = inputSignature(input);
+  const sig = displayInputSignature(input);
   return sig && sig !== "{}" ? ` input: ${sig}` : "";
 }
 

package/corpus/core/src/agent/types.ts

@@ -207,16 +207,21 @@ export interface AgentChatRequest {
   approvedToolCalls?: string[];
 }
 
+export type AgentToolInput = Record<string, unknown>;
+
 export type AgentChatEvent =
   | { type: "text"; text: string }
   | { type: "thinking"; text: string }
   | { type: "activity"; label: string; tool?: string }
   | { type: "stream_keepalive" }
-  | { type: "tool_start"; tool: string; input: Record<string, string> }
+  | { type: "tool_start"; tool: string; input: AgentToolInput }
   | {
       type: "tool_done";
       tool: string;
+      input?: AgentToolInput;
       result: string;
+      isError?: boolean;
+      completedSideEffect?: boolean;
       mcpApp?: AgentMcpAppPayload;
       chatUI?: ActionChatUIConfig;
     }

package/corpus/core/src/cli/design-connect.ts

@@ -402,6 +402,78 @@ function sendJson(
   res.end(`${JSON.stringify(body, null, 2)}\n`);
 }
 
+function sameOrigin(a: string, b: string): boolean {
+  try {
+    return new URL(a).origin === new URL(b).origin;
+  } catch {
+    return false;
+  }
+}
+
+function resolvePreviewSnapshotUrl(
+  devServerUrl: string,
+  rawUrl: string | null,
+): string {
+  const base = normalizeHttpUrl(devServerUrl);
+  const parsed = new URL(rawUrl?.trim() || "/", `${base}/`);
+  parsed.hash = "";
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new Error("Snapshot URL must use http(s).");
+  }
+  if (!sameOrigin(parsed.toString(), base)) {
+    throw new Error("Snapshot URL must stay on the connected dev server.");
+  }
+  return parsed.toString();
+}
+
+async function fetchPreviewSnapshot(
+  devServerUrl: string,
+  targetUrl: string,
+  redirects = 0,
+): Promise<{
+  url: string;
+  status: number;
+  contentType: string;
+  html: string;
+}> {
+  if (redirects > 5) {
+    throw new Error("Too many redirects while fetching preview snapshot.");
+  }
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 10_000);
+  try {
+    const response = await fetch(targetUrl, {
+      method: "GET",
+      redirect: "manual",
+      signal: controller.signal,
+      headers: {
+        accept: "text/html,application/xhtml+xml;q=0.9,*/*;q=0.8",
+      },
+    });
+    const location = response.headers.get("location");
+    if (location && response.status >= 300 && response.status < 400) {
+      const redirected = new URL(location, targetUrl);
+      redirected.hash = "";
+      if (!sameOrigin(redirected.toString(), devServerUrl)) {
+        throw new Error("Snapshot redirect left the connected dev server.");
+      }
+      return fetchPreviewSnapshot(
+        devServerUrl,
+        redirected.toString(),
+        redirects + 1,
+      );
+    }
+    return {
+      url: response.url || targetUrl,
+      status: response.status,
+      contentType: response.headers.get("content-type") ?? "",
+      html: await response.text(),
+    };
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
 /** Read the full request body as a UTF-8 string. */
 async function readRequestBody(req: IncomingMessage): Promise<string> {
   return new Promise<string>((resolve, reject) => {
@@ -514,6 +586,40 @@ export async function startDesignConnectBridge(
         sendJson(res, 200, { ok: true, source: manifest.source });
         return;
       }
+      if (pathname === "/snapshot") {
+        if (req.method !== "GET") {
+          sendJson(res, 405, { ok: false, error: "method not allowed" });
+          return;
+        }
+        void (async () => {
+          try {
+            const requestUrl = new URL(req.url ?? "/", manifest.bridgeUrl);
+            const targetUrl = resolvePreviewSnapshotUrl(
+              manifest.devServerUrl,
+              requestUrl.searchParams.get("url") ??
+                requestUrl.searchParams.get("path"),
+            );
+            const snapshot = await fetchPreviewSnapshot(
+              manifest.devServerUrl,
+              targetUrl,
+            );
+            sendJson(res, snapshot.status >= 400 ? snapshot.status : 200, {
+              ok: snapshot.status < 400,
+              source: manifest.source,
+              url: snapshot.url,
+              status: snapshot.status,
+              contentType: snapshot.contentType,
+              html: snapshot.html,
+            });
+          } catch (err: unknown) {
+            sendJson(res, 400, {
+              ok: false,
+              error: err instanceof Error ? err.message : String(err),
+            });
+          }
+        })();
+        return;
+      }
 
       // ── Token-gated write endpoints (POST only) ───────────────────────────
 

package/corpus/core/src/cli/gateway-helpers.ts

@@ -1,3 +1,20 @@
+import type { EventEmitter } from "node:events";
+
+type ErrorEventEmitter = Pick<EventEmitter, "on"> & object;
+
+const gatewaySocketsWithErrorSink = new WeakSet<object>();
+
+export function attachGatewaySocketErrorSink(
+  socket: ErrorEventEmitter | null | undefined,
+  onError?: (error: unknown) => void,
+): void {
+  if (!socket || gatewaySocketsWithErrorSink.has(socket)) return;
+  gatewaySocketsWithErrorSink.add(socket);
+  socket.on("error", (error) => {
+    onError?.(error);
+  });
+}
+
 /**
  * When an app returns a redirect to a root-relative path that doesn't already
  * include the app prefix, prepend it. This handles the common case where a

package/corpus/core/src/cli/recap.ts

@@ -1995,7 +1995,6 @@ export function buildCommentBody(env: NodeJS.ProcessEnv = process.env): string {
 
   lines.push(`Here's a [visual recap](${safeUrl}) of what changed:`);
   lines.push("");
-  lines.push(`<a href="${safeUrl}">`);
   lines.push(`<picture>`);
   if (lightImageUrl && darkImageUrl) {
     lines.push(
@@ -2004,7 +2003,6 @@ export function buildCommentBody(env: NodeJS.ProcessEnv = process.env): string {
   }
   lines.push(`  <img alt="Visual recap" src="${fallbackImageUrl}">`);
   lines.push(`</picture>`);
-  lines.push(`</a>`);
   lines.push("");
   lines.push(`**Open the [full interactive recap](${safeUrl})**`);
   if (env.DIFF_HUGE === "true") {

package/corpus/core/src/cli/skills.ts

@@ -449,6 +449,10 @@ iframe-backed screens on the infinite canvas.
 - The \`/visual-edit\` entry route can open before the viewer signs in. Public
   \`/design/:id\` editor links can also render read-only public designs without a
   session.
+- Prefer links returned by Design actions or \`/_agent-native/open\` deep links.
+  Do not surface URLs with \`_session=\` tokens. Query sessions are only a
+  fallback after normal cookie resolution, so an existing browser session can
+  still open the design as a different user and show "Design not found".
 - Do not attempt anonymous write actions. Bridge registration, design creation,
   screen placement, generation, saving, and sharing are account-backed. If a
   signed-out visitor wants to save or share, send them through the framework
@@ -471,30 +475,44 @@ For one-shot agent setup, ask for JSON and keep the long-running bridge open in
 a second terminal if the user needs live updates:
 
 \`\`\`bash
-npx @agent-native/core@latest design connect --url http://localhost:5173 --root . --json
+npx @agent-native/core@latest design connect --url http://localhost:5173 --root .
+curl http://127.0.0.1:7331/manifest.json
 \`\`\`
 
+Do not use \`--json\` for an editable session. \`--json\`, \`--once\`, and
+\`--dry-run\` print the manifest and exit, so Design will fall back to a
+non-editable live iframe as soon as it tries to refresh the snapshot.
+
 ## Action Flow
 
-1. Register or refresh the bridge with \`connect-localhost\`, passing the
-   \`/manifest.json\` result as \`routeManifest\` and \`capabilities\`.
-2. Create or reuse a Design project with \`create-design\`.
-3. Place URL-backed screens with \`add-localhost-screens\`:
+Prefer the single authenticated \`open-visual-edit\` action. It registers or
+refreshes the localhost bridge, creates or reuses a Design project, places
+URL-backed screens, stores the active visual-edit context, and navigates to
+overview mode in one call. This avoids creating a private design under a
+synthetic CLI user and then handing the browser a tokenized URL that may be
+shadowed by an existing session.
 
 \`\`\`bash
-pnpm action add-localhost-screens '{
-  "designId": "<design-id>",
-  "connectionId": "<connection-id>",
+pnpm action open-visual-edit '{
+  "title": "Docs homepage visual edit",
+  "devServerUrl": "http://localhost:5173",
+  "bridgeUrl": "http://127.0.0.1:7331",
+  "rootPath": "/absolute/path/to/app",
+  "routeManifest": { "...": "from /manifest.json" },
   "paths": ["/", "/pricing", "/checkout?step=payment"]
 }'
 \`\`\`
 
+The action returns \`designId\`, \`connectionId\`, \`screens\`, \`urlPath\`, and
+\`openUrl\`. Keep those IDs in the chat context for follow-ups.
+
 For a numbered flow the user describes in chat, keep the labels and order:
 
 \`\`\`bash
-pnpm action add-localhost-screens '{
-  "designId": "<design-id>",
-  "connectionId": "<connection-id>",
+pnpm action open-visual-edit '{
+  "designId": "<existing-design-id>",
+  "connectionId": "<existing-connection-id>",
+  "devServerUrl": "http://localhost:1234",
   "routes": [
     { "url": "localhost:1234/onboarding/1", "title": "Screen 1" },
     { "url": "localhost:1234/onboarding/2", "title": "Screen 2" },
@@ -503,21 +521,41 @@ pnpm action add-localhost-screens '{
 }'
 \`\`\`
 
-If no \`routes\` or \`paths\` are supplied, \`add-localhost-screens\` uses every
-route from the latest localhost manifest.
-
-4. Navigate to overview mode:
+For responsive follow-ups, call \`open-visual-edit\` again with the same
+\`designId\` and \`connectionId\`, plus explicit viewport dimensions:
 
 \`\`\`bash
-pnpm action navigate --view editor --designId "<design-id>" --editorView overview
+pnpm action open-visual-edit '{
+  "designId": "<existing-design-id>",
+  "connectionId": "<existing-connection-id>",
+  "devServerUrl": "http://localhost:5173",
+  "paths": ["/"],
+  "defaultWidth": 390,
+  "defaultHeight": 844,
+  "startX": 1600,
+  "startY": 0
+}'
 \`\`\`
 
+If no \`routes\` or \`paths\` are supplied, \`open-visual-edit\` uses every route
+from the localhost manifest.
+
+Fallback, only when \`open-visual-edit\` is unavailable:
+
+1. Register or refresh the bridge with \`connect-localhost\`, passing the
+   \`/manifest.json\` result as \`routeManifest\` and \`capabilities\`.
+2. Create or reuse a Design project with \`create-design\`.
+3. Place URL-backed screens with \`add-localhost-screens\`.
+4. Navigate to overview mode with \`navigate\`.
+
 ## Open The Design Surface
 
 - Use the \`link\`, \`deepLink\`, or MCP App embed returned by Design actions so
   the user sees the canvas. In Codex Desktop or VS Code, prefer opening that
   Design URL in the available preview/webview panel; otherwise surface the
   "Open design" link.
+- Return or open the \`openUrl\` / action link, not a hand-built
+  \`/design/:id?_session=...\` URL.
 - If the user is working in VS Code, the Agent Native extension can open the
   same URL via
   \`vscode://builder.agent-native/open?url=<encoded-design-url>\`. Its

package/corpus/core/src/cli/workspace-dev.ts

@@ -17,6 +17,7 @@ import {
   type WorkspaceAppAudience,
 } from "../shared/workspace-app-audience.js";
 import {
+  attachGatewaySocketErrorSink,
   normalizeOrigin,
   rewriteRedirectLocation,
   escapeHtml,
@@ -1048,9 +1049,18 @@ export async function runWorkspaceDev(
             if (rewritten) responseHeaders.location = rewritten;
           }
           res.writeHead(statusCode, responseHeaders);
+          proxyRes.once("error", () => {
+            if (!res.destroyed) res.destroy();
+          });
           proxyRes.pipe(res);
         },
       );
+      proxyReq.once("socket", (socket) => {
+        attachGatewaySocketErrorSink(socket);
+      });
+      res.once("error", () => {
+        proxyReq.destroy();
+      });
       responseTimer = setTimeout(() => {
         if (settled) return;
         settled = true;
@@ -1123,6 +1133,13 @@ export async function runWorkspaceDev(
     head: Buffer,
   ): void {
     startApp(app);
+    let target: net.Socket | undefined;
+    attachGatewaySocketErrorSink(socket, () => {
+      target?.destroy();
+    });
+    socket.once("close", () => {
+      target?.destroy();
+    });
     void waitForPort(app.port, Date.now() + proxyReadyTimeoutMs).then(
       (ready) => {
         if (!ready) {
@@ -1130,8 +1147,9 @@ export async function runWorkspaceDev(
           socket.destroy();
           return;
         }
+        if (socket.destroyed) return;
         app.ready = true;
-        const target = net.connect(app.port, "127.0.0.1", () => {
+        const upstream = net.connect(app.port, "127.0.0.1", () => {
           const headers = Object.entries(
             proxyHeaders(req, `127.0.0.1:${app.port}`),
           )
@@ -1141,14 +1159,20 @@ export async function runWorkspaceDev(
                 : [`${key}: ${value ?? ""}`],
             )
             .join("\r\n");
-          target.write(
+          upstream.write(
             `${req.method} ${req.url} HTTP/${req.httpVersion}\r\n${headers}\r\n\r\n`,
           );
-          if (head.length) target.write(head);
-          socket.pipe(target).pipe(socket);
+          if (head.length) upstream.write(head);
+          socket.pipe(upstream).pipe(socket);
         });
+        target = upstream;
 
-        target.on("error", () => socket.destroy());
+        attachGatewaySocketErrorSink(upstream, () => {
+          if (!socket.destroyed) socket.destroy();
+        });
+        upstream.once("close", () => {
+          if (!socket.destroyed) socket.destroy();
+        });
       },
     );
   }