@agent-native/core 0.128.4 → 0.129.1

package/corpus/README.md

@@ -28,6 +28,6 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
 
 ## Generated Counts
 
-- core files: 1625
+- core files: 1629
 - toolkit files: 160
-- template files: 6853
+- template files: 6870

package/corpus/core/CHANGELOG.md

@@ -1,5 +1,95 @@
 # @agent-native/core
 
+## 0.129.1
+
+### Patch Changes
+
+- 8c4b44e: Keep the create organization and invite member popovers compact instead of allowing long helper text to expand their width.
+
+## 0.129.0
+
+### Minor Changes
+
+- 0aada94: Serve the stateless MCP 2026-07-28 protocol natively while preserving stateless
+  legacy clients, automatically negotiate the newest supported protocol from
+  outbound clients and stdio bridges, and harden MCP OAuth issuer, client type,
+  scope, credential binding, and Client ID Metadata Document behavior. Require
+  durable, single-use MCP 2026 approval elicitation before running actions marked
+  `needsApproval`.
+
+  Update the Pinpoint MCP server example to use the stable split MCP v2 packages.
+
+### Patch Changes
+
+- 0aada94: Stop telling sibling agents that an app has no callable actions when it does.
+  The public agent card could only advertise actions with `requiresAuth !== true`,
+  while `actions/invoke` only ever executes actions with `requiresAuth === true` —
+  two disjoint sets. Every app whose A2A actions were authenticated therefore
+  published an empty skills list, and `describe-workspace-apps` reported
+  "exposes no directly callable actions" about an app the caller could in fact
+  call directly. Callers took that at face value and fell back to open-ended
+  `call-agent` delegation, which hands schema discovery to a second model; in
+  practice that model shelled out through `bash`, failed to find the data, and
+  looped until the repetition guard stopped the run.
+
+  The card now serves the invocable set to a caller with a verified A2A identity,
+  and sibling capability discovery signs its probe so it sees that set. Anonymous
+  card fetches are unchanged and still expose only the publicly-safe list, so no
+  capability is disclosed to an unauthenticated reader that was not disclosed
+  before.
+
+- 0aada94: Let Design MCP App canvases hand pending visual source edits back to the host coding conversation while preserving the local Design-agent and copy-prompt fallbacks for ordinary browser panes.
+
+  Teach visual-edit users to minimize Design chrome with Figma's `Shift+\` shortcut or the command menu without claiming the host-reserved `Cmd+\` chord.
+
+- 0aada94: Keep client status timeouts isolated to their own endpoint and preserve the last known model readiness when a status probe is temporarily unavailable.
+- 0aada94: Visual edit: never render a source snapshot in place of the running app. A localhost screen now always loads a live document — the proxied `/live-edit` frame for viewers holding the connection's `previewToken`, and the plain dev-server URL for everyone else. Previously a viewer without a token (signed-out session, public link, inline browser with no cookies) got the `/snapshot` HTML as `srcdoc`: a frozen copy that looked exactly like the app but had no live DOM behind it, so selection, the layers panel, and edits all silently addressed stale markup.
+- 0aada94: Show relative cost per model in the composer's model picker. Each row now
+  carries a quiet `$`/`$$`/`$$$` suffix so a user can tell an entry model from a
+  flagship one before selecting it, rather than discovering the difference in
+  their bill. The tier reuses the token list the picker already sorts by
+  (`MODEL_COST_ORDER`) and reflects each provider's own entry/mid/flagship ladder
+  — it is not a cross-provider price claim. Models outside that list render with
+  no label at all; a guessed tier would read as fact.
+- 0aada94: Send `reasoning_effort: "none"` instead of omitting it when a custom OpenAI base
+  URL forces Chat Completions with tools present. Omitting the field let OpenAI
+  apply the model's own default effort, so GPT-5.6 runs kept failing with
+  "Function tools with reasoning_effort are not supported for <model> in
+  /v1/chat/completions" even after the field was dropped.
+- 0aada94: Use OpenAI's current `gpt-transcribe` model for direct OpenAI voice dictation uploads.
+- 0aada94: Refuse to replace symlinked project skill folders during built-in skill installs.
+- 0aada94: Queued chat messages now run under the model, engine, and reasoning effort they
+  were composed with instead of whatever the picker happens to be set to when the
+  queue flushes. Queued bubbles also gain a "Send now" control that interrupts the
+  active run, and the pending group is labelled with its count.
+- 0aada94: Restore a reachable path for the legacy chat-thread `message_count` repair. Databases predating the column left rows at 0, and both `listThreads` and `searchThreads` filter `message_count > 0` in SQL, so those threads never appeared in the sidebar and nothing called the repair anymore.
+
+  `repairLegacyChatThreadMessageCounts` now runs as a name-tracked migration (`_chat_threads_migrations`) in long-lived app processes, so the `thread_data` scan happens once per database and is skipped entirely on every later boot. Serverless isolates do not launch the repair during cold start; operators can run a long-lived maintenance process against an older hosted database without making concurrent functions race the same full-data scan. `MigrationEntry` gained an optional `run` hook for backfills SQL cannot express; it executes before the bookkeeping row is written, so a failed repair stays unrecorded and retries instead of being marked applied against work that never happened.
+
+- 0aada94: Tell the model the expected parameter signature when a raw-JSON-schema action
+  rejects its arguments. Previously only Zod-backed actions echoed the expected
+  shape, so a model that guessed a wrong enum or type on a raw-schema action got
+  no new information, re-sent the same arguments, and tripped the identical-error
+  breaker with the write never executed. The repeated-error stop message is now
+  written for the user instead of instructing them to fix the tool arguments.
+- 0aada94: Report failed batched schema introspection as an error instead of silently treating the database as up to date.
+- 0aada94: Reduce agent-chat startup request fan-out by sharing concurrent status, session, model-discovery, and thread-list reads.
+- 0aada94: Stop timed-out Neon database statements on the server instead of only abandoning the client request.
+- 0aada94: Stop the chat from claiming a tool is running when nothing is running, and stop
+  recording interrupted actions as failures. A tool card only spins while a chat is
+  actually running — an activity placeholder alone no longer resurrects a spinner
+  on rehydrated history, which is how an email that WAS delivered showed as
+  perpetually "sending". When a stream ends with a tool still in flight the card is
+  now marked with a distinct unknown outcome ("it may or may not have completed")
+  instead of a red failure, both live and in the persisted transcript, because
+  "absent" and "unreadable" are not the same answer. The alternate runtime path now
+  settles its pending tool calls on `done` and on error like the main SSE path does,
+  and a turn whose tool never resolved keeps its "Worked for Xm Ys" summary instead
+  of rendering a permanent "Thinking" indicator with nothing behind it.
+- Updated dependencies [0aada94]
+- Updated dependencies [0aada94]
+  - @agent-native/toolkit@0.10.11
+
 ## 0.128.4
 
 ### Patch Changes

package/corpus/core/docs/content/template-design-collaboration-and-full-apps.mdx

@@ -15,7 +15,9 @@ Design isn't only for prototypes generated from a prompt — a coding agent can
 
 When your coding app has an inline browser, ask `/visual-edit` to open the returned Design URL there. In Codex Desktop, that means the built-in Browser; in Claude Code Desktop's Code tab, it means the Browser pane. Both can keep the canvas inside the coding app beside the conversation. In VS Code, the Agent Native extension opens the same Design URL in its side-panel webview. Browser panes can be disabled or unavailable in CLI, remote, or restricted sessions, so `/visual-edit` falls back to an **Open design** link instead of claiming the canvas opened.
 
-Once Design is open, choose **Show/Hide UI** from the `Cmd+K` menu or press `Cmd+Shift+\` on Apple devices / `Ctrl+Shift+\` elsewhere to toggle all editing chrome so only the canvas remains. The same action is available by right-clicking empty canvas space.
+Once Design is open, choose **Show/Hide UI** from the `Cmd+K` menu or press Figma's `Shift+\` shortcut to toggle all editing chrome so only the canvas remains. The same action is available by right-clicking empty canvas space.
+
+When Design is rendered as an MCP App by a connected coding host, **Apply design updates** sends the pending source-edit handoff back to that host conversation after its normal confirmation. An ordinary inline Browser pane is still useful for the side-by-side canvas, but webpages cannot post into the active Codex or Claude Code task; there, Apply uses Design's local agent and **Copy prompt to your agent** is the coding-agent fallback.
 
 These are especially useful canvas sets:
 

package/corpus/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.128.4",
+  "version": "0.129.1",
   "description": "Framework for agent-native application development — where AI agents and UI share SQL state, actions, and context",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {
@@ -344,8 +344,11 @@
     "@codemirror/lang-sql": "^6.10.0",
     "@codemirror/theme-one-dark": "^6.1.3",
     "@libsql/client": "^0.15.0",
-    "@modelcontextprotocol/ext-apps": "1.7.2",
-    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@modelcontextprotocol/client": "2.0.0",
+    "@modelcontextprotocol/core": "2.0.0",
+    "@modelcontextprotocol/ext-apps": "1.7.5",
+    "@modelcontextprotocol/sdk": "1.30.0",
+    "@modelcontextprotocol/server": "2.0.0",
     "@mozilla/readability": "0.6.0",
     "@neondatabase/serverless": "^1.1.0",
     "@radix-ui/react-popover": "catalog:",

package/corpus/core/src/a2a/client.ts

@@ -277,12 +277,26 @@ export class A2AClient {
     throw lastError ?? new Error("No A2A endpoint candidates available");
   }
 
-  async getAgentCard(options?: { timeoutMs?: number }): Promise<AgentCard> {
+  async getAgentCard(options?: {
+    timeoutMs?: number;
+    /**
+     * Identity token for the card fetch. The anonymous card can only advertise
+     * publicly-safe actions, which is a disjoint set from what `actions/invoke`
+     * runs — so a sibling that discovers anonymously is told there is nothing
+     * callable. Pass a token to see the invocable set.
+     */
+    token?: string;
+  }): Promise<AgentCard> {
     const res = await ssrfSafeFetch(
       `${this.baseUrl}/.well-known/agent-card.json`,
-      options?.timeoutMs
-        ? { signal: AbortSignal.timeout(options.timeoutMs) }
-        : {},
+      {
+        ...(options?.timeoutMs
+          ? { signal: AbortSignal.timeout(options.timeoutMs) }
+          : {}),
+        ...(options?.token
+          ? { headers: { Authorization: `Bearer ${options.token}` } }
+          : {}),
+      },
       { maxRedirects: 3, allowedPrivateOrigins: workspacePrivateOrigins() },
     );
     if (!res.ok) {

package/corpus/core/src/a2a/server.ts

@@ -222,7 +222,7 @@ export function mountA2A(
   // /tmp/security-audit/12-mcp-a2a-agent.md.
   getH3App(nitroApp).use(
     "/.well-known/agent-card.json",
-    defineEventHandler((event) => {
+    defineEventHandler(async (event) => {
       if (getMethod(event) !== "GET") {
         setResponseStatus(event, 405);
         return { error: "Method not allowed" };
@@ -233,10 +233,26 @@ export function mountA2A(
       const host = getRequestHeader(event, "host") ?? "localhost";
       const baseUrl = `${protocol}://${host}`;
 
-      const filteredSkills = filterPublicAgentCardSkills(config);
+      // The anonymous card may only advertise actions safe to disclose
+      // publicly (`requiresAuth !== true`), but `actions/invoke` only ever
+      // runs the opposite set (`requiresAuth === true`). Those are disjoint,
+      // so an unauthenticated card said "no directly callable actions" about
+      // an app whose actions a verified sibling can call — and callers fell
+      // back to open-ended delegation. Show a verified caller what it can
+      // actually invoke; anonymous fetches keep the public list unchanged.
+      let skills = filterPublicAgentCardSkills(config);
+      if (config.authenticatedSkills?.length) {
+        const bearer = extractBearerToken(
+          getRequestHeader(event, "authorization"),
+        );
+        if (bearer) {
+          const payload = await verifyA2AToken(bearer, event);
+          if (payload.email) skills = config.authenticatedSkills;
+        }
+      }
 
       return generateAgentCard(
-        { ...config, skills: filteredSkills },
+        { ...config, skills },
         baseUrl,
         `${routePrefix}/a2a`,
       );

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

@@ -225,6 +225,13 @@ export interface A2AConfig {
   description: string;
   version?: string;
   skills: AgentSkill[];
+  /**
+   * Skills advertised only to a caller with a verified A2A identity — the set
+   * `actions/invoke` will actually run. Anonymous card fetches never see these.
+   * Without it the card advertises the public set, which is disjoint from the
+   * invocable set, so siblings are told nothing is directly callable.
+   */
+  authenticatedSkills?: AgentSkill[];
   /** If true, public agent-card discovery includes only explicit public-safe skills. */
   publicSkillsOnly?: boolean;
   handler?: A2AHandler;

package/corpus/core/src/action.ts

@@ -1370,6 +1370,45 @@ function coerceGatewayStringifiedArgs(
   return out ?? args;
 }
 
+/**
+ * Compact signature of an action's parameters, e.g.
+ * `{ deckId*: string, operation*: "edit"|"replace", slideId?: string }` where
+ * `*` = required and `?` = optional.
+ *
+ * Enum values are spelled out because a rejected call is usually a wrong enum:
+ * gateways that pre-fill optional fields reach for the first allowed value, and
+ * a model that only learns "must be equal to one of the allowed values" re-sends
+ * the same guess until the identical-error breaker kills the turn.
+ *
+ * Shared so the raw-JSON-schema tool path in the agent loop describes a
+ * rejection the same way `wrapWithValidation` does for Zod actions.
+ */
+export function describeToolParameterSignature(
+  parameters: ActionTool["parameters"] | undefined,
+  only?: readonly string[],
+): string | null {
+  const properties = parameters?.properties;
+  if (!properties) return null;
+  const required = new Set(parameters?.required ?? []);
+  const keys = Object.keys(properties).filter(
+    (key) => !only?.length || only.includes(key),
+  );
+  const sig = (keys.length ? keys : Object.keys(properties))
+    .map((key) => {
+      const spec = properties[key];
+      const mark = required.has(key) ? "*" : "?";
+      const type = Array.isArray(spec.enum)
+        ? spec.enum.map((value) => JSON.stringify(value)).join("|")
+        : Array.isArray(spec.type)
+          ? spec.type.join("|")
+          : (spec.type ?? "any");
+      return `${key}${mark}: ${type}`;
+    })
+    .join(", ");
+  if (!sig) return null;
+  return `{ ${sig.length > 600 ? `${sig.slice(0, 600)}…` : sig} }`;
+}
+
 /**
  * Wrap an action's run function with schema validation.
  * Invalid inputs get a clear error message (including what was actually passed)
@@ -1427,22 +1466,10 @@ function wrapWithValidation(
         received = String(args);
       }
 
-      // Also show the EXPECTED signature so the agent doesn't have to guess.
-      // Format: `{ deckId*: string, content*: string, slideId?: string, ... }`
-      // where `*` = required, `?` = optional.
-      let expected = "";
-      if (toolParameters?.properties) {
-        const required = new Set(toolParameters.required ?? []);
-        const sig = Object.entries(toolParameters.properties)
-          .map(([k, v]) => {
-            const mark = required.has(k) ? "*" : "?";
-            const type = (v as { type?: string }).type ?? "any";
-            return `${k}${mark}: ${type}`;
-          })
-          .join(", ");
-        if (sig)
-          expected = ` Expected: { ${sig} } (where * = required, ? = optional).`;
-      }
+      const signature = describeToolParameterSignature(toolParameters);
+      const expected = signature
+        ? ` Expected: ${signature} (where * = required, ? = optional).`
+        : "";
 
       throw new Error(
         `Invalid action parameters — ${parts.join(". ")}. Received: ${received}.${expected}`,

package/corpus/core/src/agent/engine/ai-sdk-engine.ts

@@ -360,18 +360,22 @@ class AISDKEngine implements AgentEngine {
         // `createProviderModel` forces Chat Completions specifically when
         // `this.baseUrl` is set (many OpenAI-compatible gateways/proxies
         // don't implement Responses — see that comment). In that exact
-        // combination — forced Chat Completions AND tools present — drop
-        // the explicit override and let the model use its default reasoning
-        // behavior instead of hard-failing the whole request; Responses-API
-        // calls (no baseUrl) are unaffected and keep full effort control.
+        // combination — forced Chat Completions AND tools present — send
+        // `"none"` rather than our resolved effort; Responses-API calls (no
+        // baseUrl) are unaffected and keep full effort control.
+        //
+        // Omitting the field does NOT work: OpenAI then applies the model's
+        // own default effort, which is not "none", and rejects the request
+        // exactly the same way. Only the explicit "none" clears it — the
+        // error text spells this out ("or set reasoning_effort to 'none'").
         const forcedChatCompletionsWithTools =
           Boolean(this.baseUrl) && aiSdkTools !== undefined;
-        if (!forcedChatCompletionsWithTools) {
-          providerOpts.openai = {
-            ...((providerOpts.openai as object) ?? {}),
-            reasoningEffort,
-          };
-        }
+        providerOpts.openai = {
+          ...((providerOpts.openai as object) ?? {}),
+          reasoningEffort: forcedChatCompletionsWithTools
+            ? "none"
+            : reasoningEffort,
+        };
       } else if (this.provider === "openrouter") {
         providerOpts.openrouter = {
           ...((providerOpts.openrouter as object) ?? {}),

package/corpus/core/src/agent/production-agent.ts

@@ -13,6 +13,7 @@ import type { EventHandler as H3EventHandler } from "h3";
 import { parseA2AAgentActivityPart } from "../a2a/activity.js";
 import type { Task } from "../a2a/types.js";
 import {
+  describeToolParameterSignature,
   isAgentActionStopError,
   type ActionAutomationContext,
   type ActionCaller,
@@ -3405,14 +3406,46 @@ function dedupeAssistantToolCallsById(
   return deduped;
 }
 
+/**
+ * Property names an Ajv `errorsText` line blames, e.g.
+ * `input/operations must be array; input must have required property 'id'`.
+ */
+function schemaErrorPropertyNames(error: string): string[] {
+  const names = new Set<string>();
+  for (const match of error.matchAll(/\binput\/([A-Za-z0-9_$-]+)/g)) {
+    names.add(match[1]);
+  }
+  for (const match of error.matchAll(
+    /must have required property '([^']+)'/g,
+  )) {
+    names.add(match[1]);
+  }
+  return [...names];
+}
+
+/**
+ * Raw-JSON-schema actions used to be told only that their arguments were wrong,
+ * never what shape was expected — so a model re-sent the same guess until the
+ * identical-error breaker ended the turn with the write never executed. Zod
+ * actions have echoed the expected signature since `wrapWithValidation`; this
+ * gives the raw path the same answer from the same helper.
+ */
 function toolInputSchemaErrorResult(
   toolName: string,
   input: unknown,
   error: string,
+  parameters?: ActionTool["parameters"],
 ): string {
+  const signature = describeToolParameterSignature(
+    parameters,
+    schemaErrorPropertyNames(error),
+  );
   return (
     `Invalid action parameters for ${toolName}: ${sanitizeToolErrorText(error)}. ` +
     `Received: ${stringifyToolInput(input)}. ` +
+    (signature
+      ? `Expected: ${signature} (where * = required, ? = optional). `
+      : "") +
     "The tool was not executed; retry with arguments that match the tool schema."
   );
 }
@@ -4723,11 +4756,14 @@ export async function runAgentLoop(opts: {
         const result =
           `Stopped after ${count} identical errors from ${toolCall.name} with the same arguments. ` +
           `Last error: ${sanitizedResult}`;
+        // This message is streamed to the USER, not back to the model — the
+        // model's copy is `result` above. Describe the failure and what they
+        // can do; never instruct them to "fix the arguments".
         requestedActionStop ??= {
           message:
-            `Stopped because ${toolCall.name} failed ${count} times with the same arguments and error. ` +
-            `Last error: ${sanitizedResult} ` +
-            "Fix the underlying issue or change the arguments before retrying.",
+            `I stopped because the ${toolCall.name} action failed ${count} times in a row the same way, ` +
+            "so retrying it again would not have worked. Anything completed before this is saved. " +
+            `Error: ${sanitizedResult}`,
           errorCode: "repeated_identical_tool_error",
         };
         return result;
@@ -5114,6 +5150,7 @@ export async function runAgentLoop(opts: {
             toolCall.name,
             toolCallSchemaError.input,
             toolCallSchemaError.error,
+            actionEntry?.tool.parameters,
           ),
         );
         send({
@@ -5146,6 +5183,7 @@ export async function runAgentLoop(opts: {
             toolCall.name,
             toolCall.input,
             rawToolInputError,
+            actionEntry.tool.parameters,
           ),
         );
         send({

package/corpus/core/src/agent/thread-data-builder.ts

@@ -21,6 +21,8 @@ interface ContentPart {
   args?: Record<string, string>;
   result?: string;
   isError?: boolean;
+  /** Mirrors the client ContentPart marker in client/sse-event-processor.ts. */
+  outcome?: "unknown";
   completedSideEffect?: boolean;
   mcpApp?: AgentMcpAppPayload;
   chatUI?: ActionChatUIConfig;
@@ -385,6 +387,9 @@ function settleInterruptedToolCalls(content: ContentPart[]): void {
   for (const part of content) {
     if (part.type === "tool-call" && part.result === undefined) {
       part.result = INTERRUPTED_TOOL_RESULT;
+      // Interrupted is not failed — never set `isError` here. The persisted
+      // turn must agree with the live client (client/sse-event-processor.ts).
+      part.outcome = "unknown";
     }
   }
 }

package/corpus/core/src/chat-threads/migrations.ts

@@ -0,0 +1,53 @@
+import { isServerlessRuntime } from "../db/client.js";
+import type { MigrationEntry } from "../db/migrations.js";
+import { runMigrations } from "../db/migrations.js";
+import { repairLegacyChatThreadMessageCounts } from "./store.js";
+
+export const CHAT_THREADS_MIGRATIONS_TABLE = "_chat_threads_migrations";
+
+export const CHAT_THREADS_REPAIR_MESSAGE_COUNTS_MIGRATION =
+  "chat-threads-repair-legacy-message-counts";
+
+/**
+ * Rows written before `message_count` was maintained still carry 0, and both
+ * `listThreads` and `searchThreads` filter `message_count > 0` in SQL — so on a
+ * database that predates the column, threads that do have messages never appear
+ * in the sidebar. This entry is the only reachable caller of the repair; being
+ * name-tracked, the `thread_data` scan it performs runs once per database and
+ * is skipped entirely on every later boot.
+ */
+export const CHAT_THREADS_MIGRATIONS: MigrationEntry[] = [
+  {
+    version: 1,
+    name: CHAT_THREADS_REPAIR_MESSAGE_COUNTS_MIGRATION,
+    // Run-only: the count comes from `normalizeThreadRepository`, which dedupes
+    // and re-parents message entries. No portable SQL equivalent.
+    sql: {},
+    run: async () => {
+      const { scanned, updated } = await repairLegacyChatThreadMessageCounts();
+      if (scanned > 0) {
+        console.log(
+          `[chat-threads] repaired legacy message_count on ${updated} of ${scanned} scanned row(s)`,
+        );
+      }
+    },
+  },
+];
+
+/**
+ * Apply data migrations only in a long-lived process. A serverless cold start
+ * must never launch the legacy blob scan: concurrent isolates would all race
+ * the same repair and exhaust the shared database even if route readiness does
+ * not await it. Operators can run the app in a long-lived maintenance process
+ * against the target database to apply the name-tracked repair once.
+ */
+export async function runChatThreadDataMigrations(
+  nitroApp: unknown,
+): Promise<"applied" | "skipped-serverless"> {
+  if (isServerlessRuntime()) return "skipped-serverless";
+  const migrate = runMigrations(CHAT_THREADS_MIGRATIONS, {
+    table: CHAT_THREADS_MIGRATIONS_TABLE,
+  });
+  await migrate(nitroApp);
+  return "applied";
+}

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

@@ -35,6 +35,10 @@ const REACT_ROUTER_BUILD_DEPENDENCIES = [
   "vite",
 ] as const;
 const MINIMUM_RELEASE_AGE_EXCLUDES = [
+  '"@modelcontextprotocol/client"',
+  '"@modelcontextprotocol/core"',
+  '"@modelcontextprotocol/node"',
+  '"@modelcontextprotocol/server"',
   '"@typescript/*"',
   '"@sentry/*"',
   "fast-xml-parser",

package/corpus/core/src/cli/skills-content/design-visual-edit-skill.ts

@@ -27,10 +27,18 @@ exported instructions only, with no MCP connector registration.
 
 ## Put Design Beside The Chat
 
-After \`open-visual-edit\` returns \`openUrl\`, open that URL in the coding host's
-inline browser when one is available. This is the preferred working surface:
-the user can keep Design's canvas beside the conversation, inspect the same
-screens as the agent, and iterate without switching apps.
+Prefer the interactive MCP App returned by \`open-visual-edit\` when the coding
+host renders it. The user gets the Design canvas beside the conversation, and
+**Apply design updates** can submit the bounded source-edit handoff back to the
+current host conversation through the standard MCP Apps message bridge. The
+host may ask the user to confirm the current conversation or choose a new one.
+
+Otherwise, after \`open-visual-edit\` returns \`openUrl\`, open that URL in the
+coding host's inline browser when one is available. This still keeps Design
+beside the conversation, but an ordinary browser page has no trusted path into
+the host's current composer. In that fallback surface, **Apply design updates**
+uses Design's local agent; use **Copy prompt to your agent** to hand the same
+structured edit batch to the coding agent.
 
 - In Codex Desktop, use the in-app Browser tool to open \`openUrl\`. The built-in
   browser is the right surface for localhost and public pages that should stay
@@ -42,14 +50,13 @@ screens as the agent, and iterate without switching apps.
   sessions may not expose one. If the inline surface is unavailable or disabled,
   return the normal **Open design** link instead of claiming it opened.
 
-Prefer the host's browser/preview tool over telling the user to press a keyboard
-shortcut. Keep the canvas pane beside chat when the host supports rearrangeable
-panes.
+Prefer the MCP App surface for a connected Design plugin, then the host's
+browser/preview tool as the universal fallback. Keep the canvas beside chat
+when the host supports rearrangeable panes.
 
-Inside Design, use **Show/Hide UI** from the \`Cmd+K\` menu or press
-\`Cmd+Shift+\\\` on Apple platforms / \`Ctrl+Shift+\\\` elsewhere to toggle all
-editing chrome so only the canvas remains. The same action is available from
-Design's empty-canvas context menu.
+Inside Design, use **Show/Hide UI** from the \`Cmd+K\` menu or press Figma's
+\`Shift+\\\` shortcut to toggle all editing chrome so only the canvas remains.
+The same action is available from Design's empty-canvas context menu.
 
 ## Core Model
 
@@ -57,8 +64,16 @@ Design's empty-canvas context menu.
 - Each screen keeps URL metadata: \`connectionId\`, \`routeId\`, \`path\`,
   \`url\`, \`bridgeUrl\`, title, and viewport size.
 - Localhost Edit mode renders the running app through the local bridge as a live
-  iframe with the same editor bridge used by HTML designs. It is not a frozen
-  static DOM snapshot.
+  iframe with the same editor bridge used by HTML designs. It is never a frozen
+  static DOM snapshot. Editing is direct DOM manipulation against that live
+  document; the parallel \`/snapshot\` fetch feeds the editable source model only
+  and must never be rendered in the frame.
+- A viewer holding the connection's \`previewToken\` gets the proxied
+  \`/live-edit\` document with editor chrome. A viewer without one — a signed-out
+  session, a public link, or an inline browser with no cookies — gets the plain
+  dev-server URL: still live, but with no editor chrome, no layers, and no
+  editing. If the canvas looks right but selection and the layers panel do
+  nothing, the frame is unbridged; sign in rather than assuming Design is broken.
 - The live editor is same-origin through the local bridge proxy. This boots
   CSR apps and root-relative assets, but it is still a localhost editing proxy:
   app-origin cookies, WebSockets/HMR, SSE, and non-GET app API calls may need a
@@ -336,9 +351,11 @@ Fallback, only when \`open-visual-edit\` is unavailable:
 ## Applying Visual Edits Back To Source
 
 Canvas edits on a localhost screen do not write source as you make them. They
-accumulate as pending edits and the editor shows an "Apply with Design agent"
-button in the bottom-right corner of the canvas. Clicking it hands a structured
-prompt to the Design agent chat, which performs the real source write.
+accumulate as pending edits and the editor shows an **Apply design updates**
+button on the canvas. In an MCP App, clicking it hands the bounded structured
+prompt to the current host coding conversation. In an ordinary browser or
+standalone Design page, it falls back to the local Design agent. The dropdown's
+**Copy prompt to your agent** action is the universal manual fallback.
 
 - Style, text, and drag/drop structure edits all collect into the same pending
   batch, so the user can make several changes and apply once.
@@ -410,6 +427,9 @@ the connected app's text/code files through the bridge
 - The Design editor opens in overview mode.
 - Every requested screen renders the intended localhost URL, showing real app
   content rather than an endless loading spinner.
+- The screen iframe carries a \`src\`, not a \`srcdoc\`. A localhost screen with a
+  \`srcdoc\` is a bug, not a slow load — check it in the browser devtools before
+  reporting the canvas as working.
 - Alt-dragging a screen copies the URL-backed frame, not an inline HTML clone.
 - A query/path edit changes only the target screen's URL metadata and iframe.
 - The Code tab shows a local-files root for the connection and opens its files.

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

@@ -1173,6 +1173,7 @@ function writeSkillFolder(
       `${JSON.stringify(metadata, null, 2)}\n`,
       "utf-8",
     );
+    assertSkillFolderIsNotSymlink(dir);
     fs.rmSync(dir, { recursive: true, force: true });
     fs.renameSync(tempDir, dir);
   } catch (error: any) {
@@ -1186,6 +1187,21 @@ function writeSkillFolder(
   }
 }
 
+function assertSkillFolderIsNotSymlink(dir: string): void {
+  let stat: fs.Stats;
+  try {
+    stat = fs.lstatSync(dir);
+  } catch (error: any) {
+    if (error?.code === "ENOENT") return;
+    throw error;
+  }
+  if (stat.isSymbolicLink()) {
+    throw new Error(
+      `Refusing to replace symlinked Agent Native skill folder ${dir}. Update the linked source or remove the symlink before installing.`,
+    );
+  }
+}
+
 function isJsonRecord(value: unknown): value is Record<string, unknown> {
   return Boolean(value && typeof value === "object" && !Array.isArray(value));
 }