@agent-native/core 0.84.0 → 0.84.2

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

@@ -1,3 +1,4 @@
+import { spawn } from "node:child_process";
 import crypto from "node:crypto";
 import fsSync from "node:fs";
 import fs from "node:fs/promises";
@@ -44,6 +45,7 @@ export interface DesignConnectArgs {
   json: boolean;
   once: boolean;
   dryRun: boolean;
+  daemon: boolean;
   help: boolean;
 }
 
@@ -115,6 +117,7 @@ export function parseDesignConnectArgs(argv: string[]): DesignConnectArgs {
     json: false,
     once: false,
     dryRun: false,
+    daemon: false,
     help: false,
   };
 
@@ -155,6 +158,8 @@ export function parseDesignConnectArgs(argv: string[]): DesignConnectArgs {
     } else if (arg === "--dry-run") {
       parsed.dryRun = true;
       parsed.once = true;
+    } else if (arg === "--daemon") {
+      parsed.daemon = true;
     } else if (arg.startsWith("-")) {
       throw new Error(`Unknown option: ${arg}`);
     } else {
@@ -165,6 +170,11 @@ export function parseDesignConnectArgs(argv: string[]): DesignConnectArgs {
   if (!Number.isInteger(parsed.port) || parsed.port <= 0) {
     throw new Error("--port must be a positive integer");
   }
+  if (parsed.daemon && (parsed.json || parsed.once || parsed.dryRun)) {
+    throw new Error(
+      "--daemon cannot be combined with --json, --once, or --dry-run",
+    );
+  }
   parsed.root = path.resolve(parsed.root);
   parsed.url = parsed.url ? normalizeHttpUrl(parsed.url) : undefined;
   return parsed;
@@ -298,6 +308,86 @@ async function probeDevServer(url: string): Promise<boolean> {
   }
 }
 
+async function waitForBridgeHealth(
+  bridgeUrl: string,
+  timeoutMs = 5_000,
+): Promise<boolean> {
+  const healthUrl = new URL("/health", bridgeUrl).toString();
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 400);
+    try {
+      const response = await fetch(healthUrl, {
+        method: "GET",
+        signal: controller.signal,
+      });
+      if (response.ok) return true;
+    } catch {
+      // Keep polling until the detached process finishes binding the port.
+    } finally {
+      clearTimeout(timeout);
+    }
+    await new Promise((resolve) => setTimeout(resolve, 150));
+  }
+  return false;
+}
+
+function isDesignConnectManifest(
+  value: unknown,
+): value is DesignConnectManifest {
+  if (!value || typeof value !== "object") return false;
+  const manifest = value as Partial<DesignConnectManifest>;
+  return (
+    manifest.version === 1 &&
+    manifest.source === "agent-native-design-connect" &&
+    manifest.sourceType === "localhost" &&
+    manifest.localOnly === true &&
+    typeof manifest.devServerUrl === "string" &&
+    typeof manifest.bridgeUrl === "string" &&
+    typeof manifest.rootPath === "string"
+  );
+}
+
+async function fetchRunningBridgeManifest(
+  bridgeUrl: string,
+): Promise<DesignConnectManifest | null> {
+  const manifestUrl = new URL("/manifest.json", bridgeUrl).toString();
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 800);
+  try {
+    const response = await fetch(manifestUrl, {
+      method: "GET",
+      signal: controller.signal,
+    });
+    if (!response.ok) return null;
+    const body = (await response.json()) as unknown;
+    return isDesignConnectManifest(body) ? body : null;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+export function designConnectManifestsTargetSameApp(
+  running: Pick<DesignConnectManifest, "devServerUrl" | "rootPath">,
+  requested: Pick<DesignConnectManifest, "devServerUrl" | "rootPath">,
+): boolean {
+  let runningUrl = running.devServerUrl;
+  let requestedUrl = requested.devServerUrl;
+  try {
+    runningUrl = normalizeHttpUrl(runningUrl);
+    requestedUrl = normalizeHttpUrl(requestedUrl);
+  } catch {
+    // Fall through to direct string comparison for malformed legacy manifests.
+  }
+  return (
+    runningUrl === requestedUrl &&
+    path.resolve(running.rootPath) === path.resolve(requested.rootPath)
+  );
+}
+
 async function resolveDevServerUrl(url?: string): Promise<string> {
   if (url) return normalizeHttpUrl(url);
   for (const candidate of DEFAULT_DEV_SERVER_CANDIDATES) {
@@ -942,6 +1032,7 @@ Options:
   --route-manifest <path> Non-destructive route manifest output path
   --app-url <url>         Deployed design app URL for self-registration
                           (also reads AGENT_NATIVE_URL / DESIGN_APP_URL env)
+  --daemon                Start the bridge detached, wait for /health, then exit
   --json                  Print the manifest JSON and exit
   --once                  Prepare/scaffold the manifest and exit
   --dry-run               Print what would be exposed without writing files
@@ -966,6 +1057,87 @@ Element provenance (resolveNodeToFile):
   Cross-origin localhost iframes cannot be read regardless of attributes (CSP).`);
 }
 
+function removeDaemonFlag(argv: string[]): string[] {
+  return argv.filter((arg) => arg !== "--daemon");
+}
+
+function resolveCurrentCliInvocation(argv: string[]): {
+  command: string;
+  args: string[];
+} {
+  const suffixLength = argv.length + 1; // leading "design" command + runDesign argv
+  const prefixEnd = Math.max(1, process.argv.length - suffixLength);
+  const cliPrefix = process.argv.slice(1, prefixEnd);
+  const entry = cliPrefix[0] ?? process.argv[1];
+  if (!entry) {
+    throw new Error("Could not resolve current CLI entrypoint for --daemon");
+  }
+  if (entry.endsWith(".ts") || entry.endsWith(".tsx")) {
+    return {
+      command: "tsx",
+      args: [...cliPrefix, "design", ...removeDaemonFlag(argv)],
+    };
+  }
+  return {
+    command: process.execPath,
+    args: [...cliPrefix, "design", ...removeDaemonFlag(argv)],
+  };
+}
+
+async function startDetachedDesignBridge(
+  argv: string[],
+  manifest: DesignConnectManifest,
+): Promise<number> {
+  if (await waitForBridgeHealth(manifest.bridgeUrl, 800)) {
+    const runningManifest = await fetchRunningBridgeManifest(
+      manifest.bridgeUrl,
+    );
+    if (
+      runningManifest &&
+      designConnectManifestsTargetSameApp(runningManifest, manifest)
+    ) {
+      console.error(
+        `Design localhost bridge already running at ${manifest.bridgeUrl}`,
+      );
+      console.log(JSON.stringify(runningManifest, null, 2));
+      return 0;
+    }
+
+    console.error(
+      [
+        `Design localhost bridge already running at ${manifest.bridgeUrl} for a different app.`,
+        runningManifest
+          ? `Running app: ${runningManifest.devServerUrl} (${runningManifest.rootPath})`
+          : "Running bridge did not expose a compatible manifest.",
+        `Requested app: ${manifest.devServerUrl} (${manifest.rootPath})`,
+        "Stop the existing bridge or choose a different --port.",
+      ].join("\n"),
+    );
+    return 1;
+  }
+
+  const invocation = resolveCurrentCliInvocation(argv);
+  const child = spawn(invocation.command, invocation.args, {
+    cwd: process.cwd(),
+    detached: true,
+    env: process.env,
+    stdio: "ignore",
+    shell: process.platform === "win32",
+  });
+  child.unref();
+
+  if (await waitForBridgeHealth(manifest.bridgeUrl)) {
+    console.error(`Design localhost bridge running at ${manifest.bridgeUrl}`);
+    console.log(JSON.stringify(manifest, null, 2));
+    return 0;
+  }
+
+  console.error(
+    `Timed out waiting for detached Design bridge at ${manifest.bridgeUrl}`,
+  );
+  return 1;
+}
+
 export async function runDesign(argv: string[]) {
   const subcommand = argv[0];
   if (subcommand !== "connect") {
@@ -988,6 +1160,9 @@ export async function runDesign(argv: string[]) {
   }
 
   const manifest = await prepareDesignConnectManifest(parsed);
+  if (parsed.daemon) {
+    return startDetachedDesignBridge(argv, manifest);
+  }
   if (parsed.json || parsed.once || parsed.dryRun) {
     console.log(JSON.stringify(manifest, null, 2));
     return 0;

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

@@ -464,18 +464,16 @@ iframe-backed screens on the infinite canvas.
 From the target app repo, make sure its dev server is running, then run:
 
 \`\`\`bash
-npx @agent-native/core@latest design connect --url http://localhost:5173 --root .
+npx @agent-native/core@latest design connect --url http://localhost:5173 --root . --daemon
 \`\`\`
 
-Use the app's real port. The command starts a local bridge on
-\`http://127.0.0.1:7331\` by default and exposes \`/manifest.json\`,
-\`/routes.json\`, and \`/health\`.
+Use the app's real port. The command starts a detached local bridge on
+\`http://127.0.0.1:7331\` by default, waits for \`/health\`, prints the
+manifest JSON, and keeps the bridge alive after the agent command exits.
 
-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:
+For a manual health/manifest check:
 
 \`\`\`bash
-npx @agent-native/core@latest design connect --url http://localhost:5173 --root .
 curl http://127.0.0.1:7331/manifest.json
 \`\`\`
 

package/corpus/core/src/client/AgentPanel.tsx

@@ -548,6 +548,8 @@ export interface AgentPanelProps extends Omit<
    * see the `Layout` files for each template.
    */
   scope?: import("./use-chat-threads.js").ChatThreadScope | null;
+  /** Show the compact scope chip above the composer. Default: true. */
+  showScopeBadge?: MultiTabAssistantChatProps["showScopeBadge"];
   /** Stable browser tab id used for tab-scoped app-state context. */
   browserTabId?: string;
   /** Keep chat thread selection in URL state. */
@@ -673,6 +675,7 @@ function AgentPanelInner({
   storageKey,
   restoreActiveThread = true,
   scope,
+  showScopeBadge,
   browserTabId,
   threadUrlSync,
   chatNotice,
@@ -1710,6 +1713,7 @@ function AgentPanelInner({
               storageKey={storageKey}
               restoreActiveThread={restoreActiveThread}
               scope={scope}
+              showScopeBadge={showScopeBadge}
               browserTabId={browserTabId}
               threadUrlSync={threadUrlSync}
             />
@@ -2393,6 +2397,8 @@ export interface AgentSidebarProps {
    * Templates compute this from the active route (see template layouts).
    */
   scope?: import("./use-chat-threads.js").ChatThreadScope | null;
+  /** Show the compact scope chip above the composer. Default: true. */
+  showScopeBadge?: MultiTabAssistantChatProps["showScopeBadge"];
   /** Stable browser tab id used for tab-scoped app-state context. */
   browserTabId?: string;
   /** Keep chat thread selection in URL state. */
@@ -2422,6 +2428,7 @@ export function AgentSidebar({
   openOnChatRunning = false,
   onFullscreenRequest,
   scope,
+  showScopeBadge,
   browserTabId,
   threadUrlSync,
 }: AgentSidebarProps) {
@@ -2955,6 +2962,7 @@ export function AgentSidebar({
             }
             storageKey={storageKey}
             scope={scope}
+            showScopeBadge={showScopeBadge}
             browserTabId={browserTabId}
             threadUrlSync={threadUrlSync}
           />

package/corpus/core/src/client/MultiTabAssistantChat.tsx

@@ -929,6 +929,8 @@ export type MultiTabAssistantChatProps = Omit<
    * the composer.
    */
   scope?: ChatThreadScope | null;
+  /** Show the compact scope chip above the composer. Default: true. */
+  showScopeBadge?: boolean;
 };
 
 export function MultiTabAssistantChat({
@@ -942,6 +944,7 @@ export function MultiTabAssistantChat({
   browserTabId,
   threadUrlSync = false,
   scope = null,
+  showScopeBadge = true,
   ...props
 }: MultiTabAssistantChatProps) {
   const {
@@ -2625,7 +2628,7 @@ export function MultiTabAssistantChat({
                 ? props.dynamicSuggestions
                 : false;
             const scopeComposerSlot =
-              tabId === activeThreadId && !contentHidden ? (
+              showScopeBadge && tabId === activeThreadId && !contentHidden ? (
                 tabScope && activeThreadId ? (
                   <ScopeBadge
                     scope={tabScope}

package/corpus/core/src/client/agent-chat-adapter.ts

@@ -17,6 +17,7 @@ import { formatChatErrorText, normalizeChatError } from "./error-format.js";
 import {
   AgentAutoContinueSignal,
   type AgentActivityTrailEntry,
+  type AgentAutoContinueErrorInfo,
   type ContentPart,
   readSSEStream,
   settleInterruptedToolCalls,
@@ -1353,6 +1354,7 @@ export function createAgentChatAdapter(
       const structuredContinuationFragments: AgentChatStructuredMessage[] = [];
       let visibleContinuationPrefix: ContentPart[] = [];
       let lastAutoContinueReason: string | null = null;
+      let lastRecoverableRunError: AgentAutoContinueErrorInfo | null = null;
       const attemptedRunIds: string[] = [];
       let authRecoveryAttempted = false;
       let continuationToolCallCounter = 0;
@@ -1364,6 +1366,12 @@ export function createAgentChatAdapter(
           lastAutoContinueReason
             ? `last_auto_continue_reason: ${lastAutoContinueReason}`
             : "",
+          lastRecoverableRunError?.errorCode
+            ? `last_recoverable_error_code: ${lastRecoverableRunError.errorCode}`
+            : "",
+          lastRecoverableRunError?.message
+            ? `last_recoverable_error: ${lastRecoverableRunError.message}`
+            : "",
           `stale_run_continuations: ${staleRunContinuationAttempts}`,
           `stalled_transient_continuations: ${stalledTransientContinuationAttempts}`,
           `empty_transient_continuations: ${emptyTransientContinuationAttempts}`,
@@ -1677,6 +1685,9 @@ export function createAgentChatAdapter(
           signal: AgentAutoContinueSignal,
         ): { ok: boolean; resetVisibleContent: boolean } => {
           lastAutoContinueReason = signal.reason;
+          if (signal.errorInfo) {
+            lastRecoverableRunError = signal.errorInfo;
+          }
           const isTransient = signal.reason !== "loop_limit";
           const visibleContent = visibleContentForContinuation();
           const currentPartialHistory =
@@ -1686,14 +1697,12 @@ export function createAgentChatAdapter(
           // whitespace-only output cannot keep the run alive indefinitely.
           const madeContentProgress = hasContinuationProgress(visibleContent);
           // An action was streamed but has not returned yet (a tool_start with
-          // no tool_done), or the activity trail shows the server was working
-          // on a tool. A run_timeout that fires in this window means the agent
-          // was actively making progress — the server's foldAssistantTurn
-          // persisted the in-flight call — so it must NOT count against the
-          // stalled/empty continuation budgets.
-          const hasInFlightTool =
-            hasInFlightToolCall(visibleContent) ||
-            Boolean(lastActivityTool(signal.activityTrail));
+          // no tool_done). This is durable enough to survive continuation: the
+          // server already emitted a real tool call. A tool-scoped activity
+          // card ("Preparing generate-design") is useful UI, but it happens
+          // before tool_start; treating it as progress caused silent retry
+          // loops when the LLM timed out while assembling a large tool input.
+          const hasInFlightTool = hasInFlightToolCall(visibleContent);
           // Either real output or an actively-running tool counts as progress
           // for the stalled/empty caps.
           const madeProgress = madeContentProgress || hasInFlightTool;
@@ -2174,15 +2183,28 @@ export function createAgentChatAdapter(
               }
               const continuation = prepareAutoContinuation(err);
               if (!continuation.ok) {
-                const message = exhaustedRecoveryMessage(err.reason);
+                const preservedError =
+                  err.errorInfo ?? lastRecoverableRunError ?? null;
+                const message =
+                  preservedError?.message ??
+                  exhaustedRecoveryMessage(err.reason);
+                const details = [
+                  preservedError?.details,
+                  connectionRecoveryDetails(),
+                ]
+                  .filter(Boolean)
+                  .join("\n\n");
+                const errorCode =
+                  preservedError?.errorCode ?? "connection_error";
                 captureChatClientError(err, "auto-continuation-exhausted", {
                   autoContinueReason: err.reason,
+                  ...(errorCode ? { errorCode } : {}),
                 });
                 const runError = {
                   message,
-                  details: connectionRecoveryDetails(),
-                  errorCode: "connection_error",
-                  recoverable: true,
+                  ...(details ? { details } : {}),
+                  errorCode,
+                  recoverable: preservedError?.recoverable ?? true,
                   ...(runId ? { runId } : {}),
                 };
                 if (typeof window !== "undefined") {
@@ -2192,10 +2214,16 @@ export function createAgentChatAdapter(
                     }),
                   );
                 }
-                settleInterruptedToolCalls(content);
+                settleInterruptedToolCalls(content, undefined, {
+                  includeActivity: true,
+                });
                 content.push({
                   type: "text",
-                  text: `Something went wrong: ${message}`,
+                  text: formatChatErrorText(
+                    message,
+                    preservedError?.upgradeUrl,
+                    errorCode,
+                  ),
                 });
                 yield {
                   content: [...content],
@@ -2343,7 +2371,9 @@ export function createAgentChatAdapter(
                     }),
                   );
                 }
-                settleInterruptedToolCalls(content);
+                settleInterruptedToolCalls(content, undefined, {
+                  includeActivity: true,
+                });
                 content.push({
                   type: "text",
                   text: `Something went wrong: ${message}`,

package/corpus/core/src/client/sse-event-processor.ts

@@ -80,21 +80,34 @@ export type AgentAutoContinueReason =
 
 export type AgentActivityTrailEntry = { label: string; tool?: string };
 
+export interface AgentAutoContinueErrorInfo {
+  message: string;
+  details?: string;
+  errorCode?: string;
+  recoverable?: boolean;
+  upgradeUrl?: string;
+}
+
 const INTERRUPTED_TOOL_RESULT =
   "Interrupted before this tool returned a result.";
+const INTERRUPTED_ACTIVITY_RESULT = "Stopped before this action started.";
 
 export function settleInterruptedToolCalls(
   content: ContentPart[],
   result = INTERRUPTED_TOOL_RESULT,
+  options?: { includeActivity?: boolean; activityResult?: string },
 ): boolean {
   let changed = false;
   for (const part of content) {
     if (
       part.type === "tool-call" &&
       part.result === undefined &&
-      part.activity !== true
+      (part.activity !== true || options?.includeActivity === true)
     ) {
-      part.result = result;
+      part.result =
+        part.activity === true
+          ? (options?.activityResult ?? INTERRUPTED_ACTIVITY_RESULT)
+          : result;
       changed = true;
     }
   }
@@ -105,17 +118,20 @@ export class AgentAutoContinueSignal extends Error {
   readonly reason: AgentAutoContinueReason;
   readonly maxIterations?: number;
   readonly activityTrail: AgentActivityTrailEntry[];
+  readonly errorInfo?: AgentAutoContinueErrorInfo;
 
   constructor(options: {
     reason: AgentAutoContinueReason;
     maxIterations?: number;
     activityTrail?: AgentActivityTrailEntry[];
+    errorInfo?: AgentAutoContinueErrorInfo;
   }) {
     super(`Agent run needs automatic continuation: ${options.reason}`);
     this.name = "AgentAutoContinueSignal";
     this.reason = options.reason;
     this.maxIterations = options.maxIterations;
     this.activityTrail = options.activityTrail ?? [];
+    this.errorInfo = options.errorInfo;
   }
 }
 
@@ -342,6 +358,7 @@ export function processEvent(
   autoContinue?: {
     reason: AgentAutoContinueReason;
     maxIterations?: number;
+    errorInfo?: AgentAutoContinueErrorInfo;
   };
 } {
   if (ev.type === "clear") {
@@ -598,7 +615,7 @@ export function processEvent(
         }),
       );
     }
-    settleInterruptedToolCalls(content);
+    settleInterruptedToolCalls(content, undefined, { includeActivity: true });
     content.push({
       type: "text",
       text: formatChatErrorText(errMsg, undefined, errorCode),
@@ -665,6 +682,7 @@ export function processEvent(
       (ev.errorCode === "run_timeout" && ev.recoverable) ||
       isAutoRecoverableError(ev, errMsg)
     ) {
+      const normalized = normalizeChatError(errMsg, ev.errorCode);
       return {
         action: "auto_continue",
         autoContinue: {
@@ -676,6 +694,15 @@ export function processEvent(
                   errMsg.toLowerCase().includes("timeout")
                 ? "run_timeout"
                 : "stream_ended",
+          errorInfo: {
+            message: normalized.message,
+            ...(ev.details || normalized.details
+              ? { details: ev.details ?? normalized.details }
+              : {}),
+            ...(ev.errorCode ? { errorCode: ev.errorCode } : {}),
+            recoverable: ev.recoverable ?? true,
+            ...(ev.upgradeUrl ? { upgradeUrl: ev.upgradeUrl } : {}),
+          },
         },
       };
     }
@@ -700,7 +727,7 @@ export function processEvent(
         }),
       );
     }
-    settleInterruptedToolCalls(content);
+    settleInterruptedToolCalls(content, undefined, { includeActivity: true });
     content.push({
       type: "text",
       text: formatChatErrorText(errMsg, ev.upgradeUrl, ev.errorCode),

package/corpus/core/src/eval/define-eval.ts

@@ -35,7 +35,10 @@ export function defineEval(spec: Eval): Eval {
   if (!spec.input || typeof spec.input.prompt !== "string") {
     throw new Error(`defineEval("${spec.name}"): \`input.prompt\` is required`);
   }
-  if (!Array.isArray(spec.scorers) || spec.scorers.length === 0) {
+  if (
+    (!Array.isArray(spec.scorers) || spec.scorers.length === 0) &&
+    !spec.skipReason
+  ) {
     throw new Error(
       `defineEval("${spec.name}"): at least one scorer is required`,
     );

package/corpus/core/src/eval/report.ts

@@ -27,13 +27,19 @@ export function formatReport(report: EvalRunReport): string {
   lines.push("  ─────");
 
   for (const row of report.results) {
-    const mark = row.passed ? "✓" : "✗";
+    const mark = row.status === "skipped" ? "-" : row.passed ? "✓" : "✗";
     lines.push("");
-    lines.push(
-      `  ${mark} ${row.eval}  (avg ${pct(row.avgScore)}, threshold ${pct(
-        row.threshold,
-      )})`,
-    );
+    if (row.status === "skipped") {
+      lines.push(`  ${mark} ${row.eval}  (skipped)`);
+      lines.push(`      reason: ${row.skipReason ?? "No reason provided"}`);
+      continue;
+    } else {
+      lines.push(
+        `  ${mark} ${row.eval}  (avg ${pct(row.avgScore)}, threshold ${pct(
+          row.threshold,
+        )})`,
+      );
+    }
     if (row.error) {
       lines.push(`      ⚠ run error: ${row.error}`);
     }
@@ -50,9 +56,18 @@ export function formatReport(report: EvalRunReport): string {
 
   lines.push("");
   lines.push("  ─────");
-  const verdict = report.failed === 0 ? "PASS" : "FAIL";
+  const skipped = report.skipped ?? 0;
+  const executedTotal = report.total - skipped;
+  const executedPassed = report.passed - skipped;
+  const verdict =
+    executedTotal === 0 && skipped > 0
+      ? "SKIPPED"
+      : report.failed === 0
+        ? "PASS"
+        : "FAIL";
   lines.push(
-    `  ${verdict}: ${report.passed}/${report.total} evals passed` +
+    `  ${verdict}: ${executedPassed}/${executedTotal} evals passed` +
+      (skipped > 0 ? `, ${skipped} skipped` : "") +
       (report.failed > 0 ? `, ${report.failed} below threshold` : ""),
   );
   lines.push("");