@agent-native/core 0.146.8 → 0.147.0

package/corpus/templates/tasks/.agents/skills/adding-a-feature/SKILL.md

@@ -81,6 +81,13 @@ or other file-like payloads, design the upload path in the same change:
 provider upload first, then URL/id/blob handle in SQL. Do not add base64/binary
 columns or stuff files into `application_state`.
 
+If the feature adds a server-side dependency carrying a native binary or heavy
+runtime — headless browser, ffmpeg, image/video processing, ML runtime — read
+the `performance` skill §9 before adding it. A deployed app has one `/*` page
+function that every visitor's cache miss wakes, and it ships whatever the server
+bundle depends on. Run that work from a background function or a job so the page
+function never carries the weight.
+
 **If the action produces or lists a navigable resource**, add a `link` builder that returns `{ url: buildDeepLink({ app, view, params }), label }`. External coding agents and MCP hosts (Claude / ChatGPT / Claude Code / Cowork / Codex, over MCP/A2A) then surface an "Open in … →" deep link that drops the user back into the running UI focused on the record — for free. If a compatible MCP host should render an inline review/edit surface, also add `mcpApp` with `embedApp()` so the action embeds the real React app route instead of a one-off HTML UI. The `link` builder and `mcpApp` metadata must be pure and synchronous (no I/O). Any external-agent read/ingest action must be `http: { method: "GET" }` + `readOnly: true` + `publicAgent: { expose: true, readOnly: true, requiresAuth: true }`. See the `external-agents` skill.
 
 ### 3. Skills / Instructions
@@ -195,4 +202,6 @@ TL;DR: declare the vocabulary once with `defineAppRoles({ appId, roles, defaultR
 - **create-skill** — How to create skills for new patterns (area 3 in detail)
 - **storing-data** — Where to store the feature's data
 - **real-time-sync** — How the UI stays in sync when the agent writes data
+- **performance** — Query/load cost, and (§9) cold-start artifact size when a
+  feature adds a server-side dependency
 - **internationalization** — How to update localized UI copy and catalogs

package/corpus/templates/tasks/.agents/skills/turn-into-app/SKILL.md

@@ -3,8 +3,9 @@ name: turn-into-app
 description: >-
   Turn visible project context, a proven thread, skill, or workflow into a
   runnable Agent-Native app with simple buttons, visible agent steps, preview,
-  and deployment handoff. Use when a user invokes `/turn-into-app` or asks to
-  make a workflow into an app, including from Claude or ChatGPT on the web.
+  and deployment handoff. Use when a user invokes `/turn-into-app`,
+  `/make-into-app`, or asks to make a workflow into an app, including from
+  Claude or ChatGPT on the web.
 user-invocable: true
 scope: both
 metadata:
@@ -38,6 +39,15 @@ The build location depends on the host. Treat this as a hard routing rule:
   workspace, follow the local implementation steps below. The local agent may
   scaffold, edit, run, and verify the app there.
 
+Once the source brief is sufficient to identify a repeatable workflow, the
+handoff is non-interactive. Do not ask the user for visual, product, copy,
+layout, template, integration, or implementation choices that can be resolved
+from the source. Select the source's recommended option; otherwise choose the
+most direct conventional default and record the assumption for later review.
+Only stop for a genuine hard blocker such as missing authorization, a
+destructive external action, an ambiguous target workspace, or no identifiable
+workflow at all.
+
 ## Default behavior
 
 For a local code-agent runtime this is an end-to-end build skill, not a request
@@ -104,14 +114,16 @@ before creating the app. Read the host-provided context in this order:
 Record the brief with these headings before handoff: source and provenance,
 project goal, configuration and constraints, knowledge sources, repeatable
 workflow, inputs and outputs, judgment and review points, representative runs,
-integrations and permissions, and unknowns. This is the compact contract for
+integrations and permissions, and unknowns and assumptions. This is the compact contract for
 the app. It keeps the new app useful without pretending that hidden Project
 history was imported. See [the fresh Project reference](references/fresh-project.md)
 for the host setup and brief template.
 
-If the visible Project context has no concrete repeatable job, ask for one
-focused clarification or a representative artifact. Do not fall back to a
-generic “what app do you want to make?” builder.
+If the visible Project context has no concrete repeatable job and no primary
+goal can be inferred, ask for one focused clarification or a representative
+artifact. Otherwise use the project's primary goal and source conventions; do
+not ask a questionnaire and do not fall back to a generic “what app do you
+want to make?” builder.
 
 ## Source selection guard
 

package/corpus/templates/tasks/.agents/skills/turn-into-app/references/fresh-project.md

@@ -36,7 +36,7 @@ Inputs and outputs:
 Judgment and review points:
 Representative runs: none, or 1-3 selected examples
 Integrations and permissions:
-Unknowns and follow-up:
+Unknowns and assumptions:
 ```
 
 Keep source references bounded. Prefer a file name, URL, resource ID, or short
@@ -69,6 +69,13 @@ do not fall back to a local sandbox build. Claude Code and Codex Code are the
 local-agent exception and may follow the implementation steps in the main
 skill.
 
+The brief is an implementation authorization, not a questionnaire. After a
+repeatable workflow is identifiable, choose any source-recommended option
+automatically. For unresolved non-blocking choices, use the most direct
+conventional default, record it under assumptions, and continue. Ask only when
+there is no identifiable workflow, no authorized target workspace, or a
+destructive/credential boundary genuinely prevents the handoff.
+
 In a new Project chat, say:
 
 ```text

package/dist/agent/engine/builder-engine.d.ts

@@ -17,4 +17,14 @@ export declare const BUILDER_CAPABILITIES: EngineCapabilities;
 export declare const BUILDER_SUPPORTED_MODELS: readonly ["auto", string, "gpt-5-6-terra", "gpt-5-6-sol", "claude-haiku-4-5", "claude-sonnet-4-6" | "claude-sonnet-5", "claude-opus-4-8", "gemini-3-5-flash", "gemini-3-1-pro"];
 export declare const BUILDER_MODEL_UNAUTHORIZED_ERROR_CODE = "builder_model_unauthorized";
 export declare const BUILDER_DEFAULT_MODEL: string;
-export declare function createBuilderEngine(_config?: Record<string, unknown>): AgentEngine;
+/**
+ * Credentials captured by a durable caller that cannot rely on ambient
+ * request context staying attached to a later run-manager callback.
+ */
+export interface BuilderEngineCredentials {
+    privateKey: string | null;
+    publicKey: string | null;
+    userId?: string | null;
+    orgName?: string | null;
+}
+export declare function createBuilderEngine(config?: Record<string, unknown>): AgentEngine;

package/dist/agent/engine/builder-engine.js

@@ -95,13 +95,17 @@ async function buildUpgradeUrl() {
     return url.toString();
 }
 class BuilderEngine {
+    configuredCredentials;
     name = "builder";
     label = "Builder.io Gateway";
     defaultModel = BUILDER_DEFAULT_MODEL;
     supportedModels = BUILDER_SUPPORTED_MODELS;
     capabilities = BUILDER_CAPABILITIES;
+    constructor(configuredCredentials) {
+        this.configuredCredentials = configuredCredentials;
+    }
     async *stream(opts) {
-        const creds = await resolveBuilderCredentials();
+        const creds = this.configuredCredentials ?? (await resolveBuilderCredentials());
         const authHeader = creds.privateKey ? `Bearer ${creds.privateKey}` : null;
         const spaceId = creds.publicKey;
         const builderUserId = creds.userId;
@@ -255,7 +259,7 @@ class BuilderEngine {
             // self-healing path for workspace/env-managed credentials, which never
             // flow through writeBuilderCredentials.
             try {
-                const creds = await resolveBuilderCredentials();
+                const creds = this.configuredCredentials ?? (await resolveBuilderCredentials());
                 await clearBuilderCredentialAuthFailure({
                     privateKey: creds.privateKey,
                     publicKey: creds.publicKey,
@@ -765,8 +769,11 @@ function htmlToText(html) {
         .replace(/\n{3,}/g, "\n\n")
         .trim();
 }
-export function createBuilderEngine(_config = {}) {
-    return new BuilderEngine();
+export function createBuilderEngine(config = {}) {
+    const configuredCredentials = config.credentials && typeof config.credentials === "object"
+        ? config.credentials
+        : undefined;
+    return new BuilderEngine(configuredCredentials);
 }
 function resolveMaxBuilderGatewayTimeoutMs() {
     if (isInBackgroundFunctionRuntime()) {

package/dist/chat-threads/store.d.ts

@@ -73,6 +73,8 @@ export declare function createThread(ownerEmail: string, opts?: {
     title?: string;
     scope?: ChatThreadScope | null;
     source?: ChatThreadSource | null;
+    /** Explicit owner organization for durable/background callers. */
+    orgId?: string | null;
 }): Promise<ChatThread>;
 export declare function registerChatThreadsShareable(): void;
 export declare function ensureChatThreadTables(): Promise<void>;

package/dist/chat-threads/store.js

@@ -367,7 +367,7 @@ export async function createThread(ownerEmail, opts) {
     const title = opts?.title ?? "";
     const scope = opts?.scope ?? null;
     const source = opts?.source ?? null;
-    const orgId = getRequestOrgId() ?? null;
+    const orgId = opts?.orgId ?? getRequestOrgId() ?? null;
     await client.execute({
         sql: `INSERT INTO chat_threads (id, owner_email, title, preview, thread_data, message_count, created_at, updated_at, scope_type, scope_id, scope_label, source_platform, source_app_id, source_url, org_id, visibility) VALUES (?, ?, ?, '', '{}', 0, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'private')`,
         args: [

package/dist/cli/agent-plugin.d.ts

@@ -2,8 +2,9 @@
  * Import and validate the portable Agent Plugin format.
  *
  * The importer intentionally handles only local plugin directories. Skills are
- * copied as inert files, and remote Streamable HTTP MCP entries are translated
- * to the Agent-Native `mcp.config.json` shape without copying package headers.
+ * copied as inert files into the workspace's agent-visible `.agents/skills`
+ * tree, and remote Streamable HTTP MCP entries are translated to the
+ * Agent-Native `mcp.config.json` shape without copying package headers.
  * A plugin package is not a credential store and this command never executes
  * a plugin's scripts or stdio servers.
  */
@@ -62,6 +63,8 @@ export interface LoadedAgentPlugin {
 }
 export interface AgentPluginImportOptions {
     targetDir?: string;
+    /** Optional skills root used by hosts whose agent cwd is a child workspace. */
+    skillsTargetDir?: string;
     force?: boolean;
     dryRun?: boolean;
 }

package/dist/cli/agent-plugin.js

@@ -2,8 +2,9 @@
  * Import and validate the portable Agent Plugin format.
  *
  * The importer intentionally handles only local plugin directories. Skills are
- * copied as inert files, and remote Streamable HTTP MCP entries are translated
- * to the Agent-Native `mcp.config.json` shape without copying package headers.
+ * copied as inert files into the workspace's agent-visible `.agents/skills`
+ * tree, and remote Streamable HTTP MCP entries are translated to the
+ * Agent-Native `mcp.config.json` shape without copying package headers.
  * A plugin package is not a credential store and this command never executes
  * a plugin's scripts or stdio servers.
  */
@@ -42,7 +43,7 @@ Usage:
 Commands:
   import   Import a standard Agent Plugin's Skills and remote MCP servers into an Agent-Native workspace.
 
-The importer copies Skills into a namespaced skills/<plugin>/<skill> path and
+The importer copies Skills into a namespaced .agents/skills/<plugin>/<skill> path and
 maps Streamable HTTP MCP servers into mcp.config.json. Package headers are
 never imported as credentials; configure authentication through the app's
 normal Connections flow. Stdio and SSE servers are reported and skipped.`;
@@ -691,10 +692,10 @@ function planMcpServers(plugin, existing, force) {
     }
     return planned;
 }
-function planSkills(plugin, targetDir, targetPluginSlug, force) {
+function planSkills(plugin, skillsRoot, force) {
     return plugin.skills.map((skill) => {
-        const destination = path.join(targetDir, "skills", targetPluginSlug, skill.name);
-        assertPathInside(targetDir, destination, "Imported skill destination");
+        const destination = path.join(skillsRoot, skill.name);
+        assertPathInside(skillsRoot, destination, "Imported skill destination");
         assertPathOutside(plugin.rootDir, destination, "Imported skill destination");
         assertNoSymlinkInExistingPath(path.dirname(destination), "Imported skill destination");
         if (!pathExists(destination)) {
@@ -878,12 +879,19 @@ export function importAgentPlugin(input, options = {}) {
     }
     assertNoSymlinkInExistingPath(targetDir, "Agent-Native import target");
     const slug = pluginSlug(plugin.manifest.name);
-    const skillsRoot = path.join(targetDir, "skills", slug);
+    const skillsTargetDir = canonicalPathForComparison(options.skillsTargetDir ?? path.join(targetDir, ".agents", "skills"));
+    if (pathExists(skillsTargetDir) &&
+        !fs.statSync(skillsTargetDir).isDirectory()) {
+        throw new Error(`Agent-Native skills target must be a directory: ${skillsTargetDir}`);
+    }
+    assertPathOutside(plugin.rootDir, skillsTargetDir, "Imported skills target");
+    assertNoSymlinkInExistingPath(skillsTargetDir, "Imported skills target");
+    const skillsRoot = path.join(skillsTargetDir, slug);
     const metadataFile = path.join(targetDir, ".agent-native", "plugins", `${slug}.json`);
     const mcpFile = path.join(targetDir, "mcp.config.json");
-    assertPathInside(targetDir, skillsRoot, "Imported skills root");
     assertPathInside(targetDir, metadataFile, "Imported metadata path");
     assertPathInside(targetDir, mcpFile, "Imported MCP config path");
+    assertPathInside(skillsTargetDir, skillsRoot, "Imported skills root");
     assertPathOutside(plugin.rootDir, skillsRoot, "Imported skills root");
     assertPathOutside(plugin.rootDir, metadataFile, "Imported metadata path");
     assertPathOutside(plugin.rootDir, mcpFile, "Imported MCP config path");
@@ -892,7 +900,7 @@ export function importAgentPlugin(input, options = {}) {
     const force = options.force ?? false;
     const dryRun = options.dryRun ?? false;
     const existingMcp = readExistingMcpConfig(mcpFile);
-    const skillPlans = planSkills(plugin, targetDir, slug, force);
+    const skillPlans = planSkills(plugin, skillsRoot, force);
     const mcpPlans = planMcpServers(plugin, existingMcp, force);
     const existingMetadata = readExistingMetadata(metadataFile);
     const metadataIsSame = metadataMatches(existingMetadata, plugin);

package/dist/cli/code-agent-executor.js

@@ -14,6 +14,7 @@ import { readAgentsBundleFromFs, generateDevelopmentSkillsPromptBlock, } from ".
 import { getAmbientOrgId, getAmbientUserEmail, runWithRequestContext, } from "../server/request-context.js";
 import { isReasoningEffort, } from "../shared/reasoning-effort.js";
 import { createAgentNativeConfigContext, loadResolvedAgentNativeConfig, } from "../vite/agent-native-config-loader.js";
+import { codexMcpConfigArgs, mergeCodeAgentMcpConfig, restrictCodeAgentMcpConfig, } from "./code-agent-mcp-config.js";
 import { createCodeAgentOutputSmoother } from "./code-agent-output-smoother.js";
 import { addCodeAgentCommandToAllowlist, appendCodeAgentTranscriptEvent, dequeueCodeAgentFollowUp, getCodeAgentRunRecord, isCodeAgentCommandAllowed, listCodeAgentTranscriptEvents, updateCodeAgentRunRecord, } from "./code-agent-runs.js";
 const DEFAULT_COMMAND_TIMEOUT_MS = 120_000;
@@ -443,20 +444,26 @@ async function executeCodexCliRun(options) {
     const model = normalizeCodexCliModel(options.model);
     const streamToolOutputToStdout = options.streamToolOutputToStdout ??
         process.env.AGENT_NATIVE_CODE_AGENT_STRUCTURED_STDOUT !== "1";
+    const additionalSkillsRoot = process.env.AGENT_NATIVE_CODE_AGENT_SKILLS_ROOT?.trim();
     const args = [
+        ...codexMcpConfigArgs(),
         "--ask-for-approval",
         "never",
-        "exec",
+        "--sandbox",
+        codexSandboxForPermissionMode(options.permissionMode),
         "--cd",
         cwd,
+        "exec",
         "--color",
         "never",
         "--skip-git-repo-check",
-        "--sandbox",
-        codexSandboxForPermissionMode(options.permissionMode),
+        "--ignore-user-config",
         "--output-last-message",
         outputPath,
     ];
+    if (additionalSkillsRoot && fs.existsSync(additionalSkillsRoot)) {
+        args.splice(args.indexOf("--output-last-message"), 0, "--add-dir", additionalSkillsRoot);
+    }
     if (model)
         args.push("--model", model);
     args.push("-");
@@ -663,9 +670,15 @@ function buildCodexCliPrompt(run, prompt) {
     const modeInstruction = mode === "Plan"
         ? "Inspect and explain only. Do not edit files or run mutating commands."
         : "Edit and verify as needed. Do not create, switch, reset, rebase, or stash git branches.";
+    const additionalSkillsRoot = process.env.AGENT_NATIVE_CODE_AGENT_SKILLS_ROOT?.trim();
     return [
         `You are running from Agent-Native Code in ${run.cwd || process.cwd()}.`,
         "Follow the repository AGENTS.md and any relevant skill instructions.",
+        ...(additionalSkillsRoot
+            ? [
+                `Additional installed Agent Plugin skills are available under ${additionalSkillsRoot}. Read any relevant SKILL.md files before acting.`,
+            ]
+            : []),
         `Run mode: ${mode} (${permissionMode}). ${modeInstruction}`,
         "",
         "# User request",
@@ -933,9 +946,12 @@ async function startCodeAgentMcpManager(runId) {
         });
         return null;
     });
-    if (!config || Object.keys(config.servers ?? {}).length === 0)
+    const effectiveConfig = restrictCodeAgentMcpConfig(mergeCodeAgentMcpConfig(config));
+    if (!effectiveConfig ||
+        Object.keys(effectiveConfig.servers ?? {}).length === 0) {
         return null;
-    const manager = new McpClientManager(config);
+    }
+    const manager = new McpClientManager(effectiveConfig);
     await manager.start().catch((err) => {
         const message = err instanceof Error ? err.message : String(err);
         appendCodeAgentTranscriptEvent({
@@ -1299,6 +1315,10 @@ export async function buildCodeAgentSystemPrompt(cwd, permissionMode) {
     const appConfig = await loadResolvedAgentNativeConfig(cwd, createAgentNativeConfigContext("serve", "development"));
     const bundle = readAgentsBundleFromFs(cwd, null, {
         instructions: appConfig.instructions,
+        additionalSkillDirs: (process.env.AGENT_NATIVE_CODE_AGENT_SKILLS_ROOT ?? "")
+            .split(path.delimiter)
+            .map((value) => value.trim())
+            .filter(Boolean),
     });
     // If the bundle has no AGENTS.md, try CLAUDE.md as a fallback — many repos
     // use that name for agent instructions (e.g. Claude Code projects).

package/dist/cli/code-agent-mcp-config.d.ts

@@ -0,0 +1,21 @@
+import type { McpConfig } from "../mcp-client/config.js";
+/**
+ * Keep a desktop coding run on the app registry's MCP servers. The normal
+ * server-side manager merges persisted MCP settings for web requests, but a
+ * local shell must not inherit arbitrary user MCP servers when the desktop
+ * host has supplied an explicit workspace allowlist.
+ */
+export declare function restrictCodeAgentMcpConfig(config: McpConfig | null, environment?: NodeJS.ProcessEnv): McpConfig | null;
+/**
+ * Add host-provided app/plugin servers to the normal merged config. The
+ * filesystem and environment layers have different precedence rules, so the
+ * child process combines them explicitly instead of silently dropping one.
+ */
+export declare function mergeCodeAgentMcpConfig(config: McpConfig | null, environment?: NodeJS.ProcessEnv): McpConfig | null;
+/**
+ * Convert the host-scoped HTTP MCP config into Codex CLI's `-c` overrides.
+ * The caller adds `--ignore-user-config` in the `exec` segment so a local
+ * coding session receives the workspace apps, not the user's global MCP
+ * catalog.
+ */
+export declare function codexMcpConfigArgs(environment?: NodeJS.ProcessEnv): string[];

package/dist/cli/code-agent-mcp-config.js

@@ -0,0 +1,103 @@
+const DESKTOP_MCP_ALLOWLIST_ENV = "AGENT_NATIVE_CODE_AGENT_MCP_SERVER_ALLOWLIST";
+function parseServerAllowlist(raw) {
+    if (raw === undefined)
+        return null;
+    return new Set(raw
+        .split(",")
+        .map((value) => value.trim())
+        .filter(Boolean));
+}
+/**
+ * Keep a desktop coding run on the app registry's MCP servers. The normal
+ * server-side manager merges persisted MCP settings for web requests, but a
+ * local shell must not inherit arbitrary user MCP servers when the desktop
+ * host has supplied an explicit workspace allowlist.
+ */
+export function restrictCodeAgentMcpConfig(config, environment = process.env) {
+    const allowlist = parseServerAllowlist(environment[DESKTOP_MCP_ALLOWLIST_ENV]);
+    if (!allowlist || !config)
+        return config;
+    const servers = Object.fromEntries(Object.entries(config.servers).filter(([id]) => allowlist.has(id)));
+    return { ...config, servers };
+}
+function codexConfigKey(serverId) {
+    const normalized = serverId.replace(/[^A-Za-z0-9_-]/g, "_");
+    return normalized || "workspace";
+}
+function tomlString(value) {
+    return JSON.stringify(value);
+}
+function tomlInlineTable(headers) {
+    return `{${Object.entries(headers)
+        .map(([key, value]) => `${tomlString(key)}=${tomlString(value)}`)
+        .join(",")}}`;
+}
+function parseMcpServers(environment) {
+    const raw = environment.MCP_SERVERS?.trim();
+    if (!raw)
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error("MCP_SERVERS is not valid JSON.");
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error("MCP_SERVERS must contain a servers object.");
+    }
+    const serverMap = "servers" in parsed &&
+        parsed.servers &&
+        typeof parsed.servers === "object" &&
+        !Array.isArray(parsed.servers)
+        ? parsed.servers
+        : parsed;
+    return Object.fromEntries(Object.entries(serverMap).map(([id, value]) => {
+        if (!value || typeof value !== "object" || Array.isArray(value)) {
+            throw new Error(`MCP_SERVERS entry ${id} is invalid.`);
+        }
+        return [id, value];
+    }));
+}
+/**
+ * Add host-provided app/plugin servers to the normal merged config. The
+ * filesystem and environment layers have different precedence rules, so the
+ * child process combines them explicitly instead of silently dropping one.
+ */
+export function mergeCodeAgentMcpConfig(config, environment = process.env) {
+    const environmentServers = parseMcpServers(environment);
+    if (Object.keys(environmentServers).length === 0)
+        return config;
+    return {
+        ...(config ?? { servers: {} }),
+        servers: {
+            ...(config?.servers ?? {}),
+            ...environmentServers,
+        },
+        source: config?.source
+            ? `${config.source}+desktop-environment`
+            : "env:MCP_SERVERS",
+    };
+}
+/**
+ * Convert the host-scoped HTTP MCP config into Codex CLI's `-c` overrides.
+ * The caller adds `--ignore-user-config` in the `exec` segment so a local
+ * coding session receives the workspace apps, not the user's global MCP
+ * catalog.
+ */
+export function codexMcpConfigArgs(environment = process.env) {
+    const servers = parseMcpServers(environment);
+    if (Object.keys(servers).length === 0)
+        return [];
+    const args = [];
+    for (const [serverId, server] of Object.entries(servers)) {
+        if (server.type !== "http" || !server.url)
+            continue;
+        const key = codexConfigKey(serverId);
+        args.push("-c", `mcp_servers.${tomlString(key)}.url=${tomlString(server.url)}`);
+        if (server.headers && Object.keys(server.headers).length > 0) {
+            args.push("-c", `mcp_servers.${tomlString(key)}.http_headers=${tomlInlineTable(server.headers)}`);
+        }
+    }
+    return args;
+}

package/dist/client/NewWorkspaceAppFlow.js

@@ -43,6 +43,7 @@ const ERROR_FAILURE_REASONS = new Set([
     "builder-not-connected",
     "credential-store-unavailable",
 ]);
+const LOCAL_APP_DOCS_URL = "https://agent-native.com/docs/multi-app-workspace#adding-a-new-app";
 function isErrorFailureReason(reason) {
     return !!reason && ERROR_FAILURE_REASONS.has(reason);
 }
@@ -267,7 +268,9 @@ export function NewWorkspaceAppFlow({ sourceApp = "chat", className = "", dispat
     }
     return (_jsx("section", { className: `mx-auto flex w-full max-w-5xl flex-col gap-5 px-4 py-6 ${className}`, children: _jsxs("div", { className: "grid gap-5 lg:grid-cols-[minmax(0,1fr)_320px]", children: [_jsxs("div", { className: "flex flex-col gap-3", children: [_jsx(PromptComposer, { autoFocus: true, disabled: isSubmitting, placeholder: "Describe the app your teammate should be able to use...", draftScope: "dispatch:new-app", preserveDraftOnSubmit: true, onSubmit: (text) => submit(text) }), statusMessage ? (_jsxs("div", { className: `flex flex-col gap-2 rounded-md border px-3 py-2 text-sm ${isErrorFailureReason(failureReason)
                                 ? "border-destructive/40 bg-destructive/10 text-destructive"
-                                : "border-border bg-muted/40 text-muted-foreground"}`, children: [_jsxs("div", { className: "flex flex-wrap items-center gap-2", children: [isErrorFailureReason(failureReason) ? (_jsx(IconAlertTriangle, { className: "h-4 w-4 shrink-0" })) : null, _jsx("span", { children: statusMessage }), branchUrl ? (_jsxs("a", { href: branchUrl, target: "_blank", rel: "noreferrer", className: "inline-flex items-center gap-1 font-medium text-foreground underline", children: ["Open branch ", _jsx(IconArrowUpRight, { className: "h-3 w-3" })] })) : null] }), failureReason === "builder-not-connected" ? (_jsx("button", { type: "button", onClick: () => connectFlow.start(), disabled: connectFlow.connecting, className: "inline-flex w-fit cursor-pointer items-center gap-1 rounded-md border border-border bg-background px-2.5 py-1 text-xs font-medium text-foreground hover:bg-accent/40 disabled:cursor-not-allowed disabled:opacity-60", children: connectFlow.connecting ? "Connecting..." : "Connect Builder" })) : null, failureReason === "credential-store-unavailable" ||
+                                : "border-border bg-muted/40 text-muted-foreground"}`, children: [_jsxs("div", { className: "flex flex-wrap items-center gap-2", children: [isErrorFailureReason(failureReason) ? (_jsx(IconAlertTriangle, { className: "h-4 w-4 shrink-0" })) : null, _jsx("span", { children: statusMessage }), branchUrl ? (_jsxs("a", { href: branchUrl, target: "_blank", rel: "noreferrer", className: "inline-flex items-center gap-1 font-medium text-foreground underline", children: ["Open branch ", _jsx(IconArrowUpRight, { className: "h-3 w-3" })] })) : null] }), failureReason === "builder-not-connected" ? (_jsxs("div", { className: "flex flex-wrap items-center gap-2", children: [_jsx("button", { type: "button", onClick: () => connectFlow.start(), disabled: connectFlow.connecting, className: "inline-flex w-fit cursor-pointer items-center gap-1 rounded-md border border-border bg-background px-2.5 py-1 text-xs font-medium text-foreground hover:bg-accent/40 disabled:cursor-not-allowed disabled:opacity-60", children: connectFlow.connecting
+                                                ? "Connecting..."
+                                                : "Connect Builder" }), _jsxs("a", { href: LOCAL_APP_DOCS_URL, target: "_blank", rel: "noreferrer", "data-create-app-local-link": true, className: "inline-flex items-center gap-1 text-xs font-medium text-foreground underline underline-offset-2", children: ["Create locally ", _jsx(IconArrowUpRight, { className: "h-3 w-3" })] })] })) : null, failureReason === "credential-store-unavailable" ||
                                     failureReason === "builder-error" ? (_jsx("button", { type: "button", onClick: () => submit(lastSubmittedPrompt), disabled: isSubmitting, className: "inline-flex w-fit cursor-pointer items-center gap-1 rounded-md border border-border bg-background px-2.5 py-1 text-xs font-medium text-foreground hover:bg-accent/40 disabled:cursor-not-allowed disabled:opacity-60", children: "Try again" })) : null] })) : null] }), _jsxs("aside", { className: "overflow-hidden rounded-lg border border-border bg-card", children: [_jsx("div", { className: "border-b border-border px-4 py-3", children: _jsxs("div", { className: "flex items-center justify-between gap-3", children: [_jsxs("div", { className: "flex items-center gap-2 text-sm font-medium", children: [_jsx(IconKey, { className: "h-4 w-4" }), "Dispatch keys"] }), _jsx("span", { className: "shrink-0 rounded border border-border bg-background/40 px-2 py-0.5 text-[11px] text-muted-foreground", children: selectedSecretLabel })] }) }), _jsx("div", { className: "max-h-[220px] space-y-2 overflow-y-auto p-3", children: vaultAccessMode === "all-apps" ? (_jsx("p", { className: "rounded-md border border-dashed border-border px-3 py-3 text-xs text-muted-foreground", children: "Every saved Dispatch vault key is available to new apps." })) : secretsError ? (_jsx("p", { className: "rounded-md border border-dashed border-border px-3 py-3 text-xs text-muted-foreground", children: secretsError })) : secrets.length === 0 ? (_jsx("p", { className: "rounded-md border border-dashed border-border px-3 py-3 text-xs text-muted-foreground", children: "No Dispatch vault keys found yet." })) : (secrets.map((secret) => {
                                 const selected = selectedSecretIds.includes(secret.id);
                                 return (_jsxs("div", { className: `group rounded-md border text-sm transition ${selected

package/dist/client/agent-chat/index.d.ts

@@ -11,6 +11,8 @@ export { CREDENTIAL_GAP_SIGNAL, isCredentialGapCodeAgentEvent, } from "../../cod
 export { useSendToAgentChat } from "../use-send-to-agent-chat.js";
 export { useChatModels, type UseChatModelsResult, type EngineModelGroup, } from "../use-chat-models.js";
 export { CodeRequiredDialog, type CodeRequiredDialogProps, } from "../components/CodeRequiredDialog.js";
+export { ChatFirstAgentActivityPanel, type ChatFirstAgentActivityPanelProps, } from "../chat-first-agent-activity.js";
+export { ChatFirstSurfacePanelToggle } from "../chat-first-surface-panel-toggle.js";
 export { useAgentEngineConfigured, type AgentEngineConfiguredState, type UseAgentEngineConfiguredResult, } from "../use-agent-engine-configured.js";
 export { BuilderSetupCard } from "../chat/run-recovery.js";
 export { AgentConversation, AgentConversationMessageView, normalizeCodeAgentTranscriptForConversation, useNearBottomAutoscroll, type CodeAgentConversationTranscriptEvent, type CodeAgentConversationTranscriptEventType, type NormalizeCodeAgentTranscriptOptions, type AgentConversationArtifact, type AgentConversationAttachment, type AgentConversationMessage, type AgentConversationMessagePart, type AgentConversationMessageRole, type AgentConversationNotice, type AgentConversationNoticeTone, type AgentConversationToolCall, type AgentConversationToolState, } from "../conversation/index.js";
@@ -29,7 +31,7 @@ export { useChatThreads, type ChatThreadScope, type ChatThreadSnapshot, type Cha
 export { ChatHistoryList, type ChatHistoryItem, type ChatHistorySection, type ChatHistoryListProps, } from "../chat/ChatHistoryList.js";
 export { AgentChatHome, type AgentChatHomeProps } from "../AgentChatHome.js";
 export { AgentChatSurface, AgentPanel, AgentSidebar, AgentToggleButton, focusAgentChat, type AgentChatSurfaceMode, type AgentChatSurfaceProps, type AgentPanelProps, type AgentSidebarProps, } from "../AgentPanel.js";
-export { AgentTabsPage, type AgentPageExtraTabContext, type AgentPageExtraTabFactory, type AgentTabsPageProps, } from "../agent-page/AgentTabsPage.js";
+export { AgentTabsPage, ConnectionsTab, type AgentPageExtraTabContext, type AgentPageExtraTabFactory, type AgentTabsPageProps, } from "../agent-page/AgentTabsPage.js";
 export type { AgentPageScope, AgentPageTabProps } from "../agent-page/types.js";
 export { AGENT_CHAT_HOME_HANDOFF_TTL_MS, AGENT_CHAT_VIEW_TRANSITION_CLASS, AGENT_CHAT_VIEW_TRANSITION_NAME, consumeAgentChatHomeHandoff, getAgentChatViewTransitionStyle, isAgentChatHomeHandoffActive, markAgentChatHomeHandoff, navigateWithAgentChatViewTransition, startAgentChatViewTransition, supportsAgentChatViewTransition, type AgentChatHomeHandoffOptions, type AgentChatViewTransition, type AgentChatViewTransitionOptions, } from "../chat-view-transition.js";
 export { useAgentChatHomeHandoff, useAgentChatHomeHandoffLinks, type UseAgentChatHomeHandoffLinksOptions, type UseAgentChatHomeHandoffOptions, } from "../use-agent-chat-home-handoff.js";
@@ -37,3 +39,4 @@ export { AGENT_SIDEBAR_DEFAULT_MAX_WIDTH, AGENT_SIDEBAR_MIN_WIDTH, AGENT_SIDEBAR
 export { clearReservedToolRenderersForTests, clearToolRenderersForTests, registerActionChatRenderer, registerFallbackToolRenderer, registerReservedActionChatRenderer, registerReservedFallbackToolRenderer, registerReservedToolRenderer, registerToolRenderer, resolveToolRenderer, type ActionChatRendererRegistration, type ToolRendererComponent, type ToolRendererContext, type ToolRendererMatch, type ToolRendererProps, type ToolRendererRegistration, } from "../chat/tool-render-registry.js";
 export * from "../chat/connectors.js";
 export * from "../chat/runtime.js";
+export { CHAT_FIRST_APP_LAYOUT_STORAGE_KEY, CHAT_FIRST_DEFAULT_APP_IDS, CHAT_FIRST_SURFACE_TABS_STORAGE_KEY, CHAT_FIRST_SURFACE_PANEL_STORAGE_KEY, CHAT_FIRST_SURFACE_WIDTH_DEFAULT, CHAT_FIRST_SURFACE_WIDTH_MIN, clampChatFirstSurfaceWidth, CHAT_FIRST_MODE_STORAGE_KEY, CHAT_FIRST_MODE_CHANGED_EVENT, CHAT_FIRST_OPEN_APP_EVENT, CHAT_FIRST_OPEN_BROWSER_EVENT, CHAT_FIRST_WATCH_SESSION_EVENT, CHAT_FIRST_SURFACE_CATALOG, chatFirstSurfaceTabId, closeChatFirstSessionWatch, emitChatFirstOpenApp, emitChatFirstOpenBrowser, emitChatFirstSessionWatch, getChatFirstSessionWatchStore, getChatFirstSurfaceTabsStore, getChatFirstSurfacePanelStore, orderChatFirstAppIds, readChatFirstAppLayout, resolveChatFirstAppTarget, resolveChatFirstBrowserTarget, resolveChatFirstSessionId, normalizeChatFirstSessionReference, readChatFirstMode, readChatFirstModeState, readChatFirstSurfaceWidth, subscribeChatFirstOpenApp, subscribeChatFirstOpenBrowser, subscribeChatFirstSessionWatch, useChatFirstSessionWatch, useChatFirstSurfaceResize, useChatFirstSurfacePanel, useChatFirstSurfaceTabs, writeChatFirstAppLayout, writeChatFirstMode, writeChatFirstSurfaceWidth, type ChatFirstAppLayoutPreference, type ChatFirstModeReadResult, type ChatFirstAppRegistration, type ChatFirstAppResolution, type ChatFirstAppTarget, type ChatFirstAgentActivity, type ChatFirstAgentActivityStatus, type ChatFirstOpenAppDelivery, type ChatFirstOpenAppDetail, type ChatFirstOpenBrowserDetail, type ChatFirstBrowserResolution, type ChatFirstSessionKind, type ChatFirstSessionReference, type ChatFirstSessionWatchDelivery, type ChatFirstSessionWatchState, type ChatFirstSessionWatchStore, type ChatFirstSurfaceKind, type ChatFirstSurfaceTab, type ChatFirstSurfacePanelState, type ChatFirstSurfacePanelStore, type ChatFirstSurfaceTabsState, type ChatFirstSurfaceTabsStore, } from "../chat-first.js";

package/dist/client/agent-chat/index.js

@@ -11,6 +11,8 @@ export { CREDENTIAL_GAP_SIGNAL, isCredentialGapCodeAgentEvent, } from "../../cod
 export { useSendToAgentChat } from "../use-send-to-agent-chat.js";
 export { useChatModels, } from "../use-chat-models.js";
 export { CodeRequiredDialog, } from "../components/CodeRequiredDialog.js";
+export { ChatFirstAgentActivityPanel, } from "../chat-first-agent-activity.js";
+export { ChatFirstSurfacePanelToggle } from "../chat-first-surface-panel-toggle.js";
 export { useAgentEngineConfigured, } from "../use-agent-engine-configured.js";
 export { BuilderSetupCard } from "../chat/run-recovery.js";
 export { AgentConversation, AgentConversationMessageView, normalizeCodeAgentTranscriptForConversation, useNearBottomAutoscroll, } from "../conversation/index.js";
@@ -29,10 +31,11 @@ export { useChatThreads, } from "../use-chat-threads.js";
 export { ChatHistoryList, } from "../chat/ChatHistoryList.js";
 export { AgentChatHome } from "../AgentChatHome.js";
 export { AgentChatSurface, AgentPanel, AgentSidebar, AgentToggleButton, focusAgentChat, } from "../AgentPanel.js";
-export { AgentTabsPage, } from "../agent-page/AgentTabsPage.js";
+export { AgentTabsPage, ConnectionsTab, } from "../agent-page/AgentTabsPage.js";
 export { AGENT_CHAT_HOME_HANDOFF_TTL_MS, AGENT_CHAT_VIEW_TRANSITION_CLASS, AGENT_CHAT_VIEW_TRANSITION_NAME, consumeAgentChatHomeHandoff, getAgentChatViewTransitionStyle, isAgentChatHomeHandoffActive, markAgentChatHomeHandoff, navigateWithAgentChatViewTransition, startAgentChatViewTransition, supportsAgentChatViewTransition, } from "../chat-view-transition.js";
 export { useAgentChatHomeHandoff, useAgentChatHomeHandoffLinks, } from "../use-agent-chat-home-handoff.js";
 export { AGENT_SIDEBAR_DEFAULT_MAX_WIDTH, AGENT_SIDEBAR_MIN_WIDTH, AGENT_SIDEBAR_WIDE_WIDTH_RATIO, clampAgentSidebarWidth, getAgentSidebarMaxWidth, getAgentSidebarWideWidth, requestAgentSidebarOpen, SIDEBAR_STATE_CHANGE_EVENT, setAgentSidebarOpenPreference, } from "../agent-sidebar-state.js";
 export { clearReservedToolRenderersForTests, clearToolRenderersForTests, registerActionChatRenderer, registerFallbackToolRenderer, registerReservedActionChatRenderer, registerReservedFallbackToolRenderer, registerReservedToolRenderer, registerToolRenderer, resolveToolRenderer, } from "../chat/tool-render-registry.js";
 export * from "../chat/connectors.js";
 export * from "../chat/runtime.js";
+export { CHAT_FIRST_APP_LAYOUT_STORAGE_KEY, CHAT_FIRST_DEFAULT_APP_IDS, CHAT_FIRST_SURFACE_TABS_STORAGE_KEY, CHAT_FIRST_SURFACE_PANEL_STORAGE_KEY, CHAT_FIRST_SURFACE_WIDTH_DEFAULT, CHAT_FIRST_SURFACE_WIDTH_MIN, clampChatFirstSurfaceWidth, CHAT_FIRST_MODE_STORAGE_KEY, CHAT_FIRST_MODE_CHANGED_EVENT, CHAT_FIRST_OPEN_APP_EVENT, CHAT_FIRST_OPEN_BROWSER_EVENT, CHAT_FIRST_WATCH_SESSION_EVENT, CHAT_FIRST_SURFACE_CATALOG, chatFirstSurfaceTabId, closeChatFirstSessionWatch, emitChatFirstOpenApp, emitChatFirstOpenBrowser, emitChatFirstSessionWatch, getChatFirstSessionWatchStore, getChatFirstSurfaceTabsStore, getChatFirstSurfacePanelStore, orderChatFirstAppIds, readChatFirstAppLayout, resolveChatFirstAppTarget, resolveChatFirstBrowserTarget, resolveChatFirstSessionId, normalizeChatFirstSessionReference, readChatFirstMode, readChatFirstModeState, readChatFirstSurfaceWidth, subscribeChatFirstOpenApp, subscribeChatFirstOpenBrowser, subscribeChatFirstSessionWatch, useChatFirstSessionWatch, useChatFirstSurfaceResize, useChatFirstSurfacePanel, useChatFirstSurfaceTabs, writeChatFirstAppLayout, writeChatFirstMode, writeChatFirstSurfaceWidth, } from "../chat-first.js";

package/dist/client/agent-page/AgentTabsPage.d.ts

@@ -3,6 +3,7 @@ import type { ResourceView } from "../resources/ResourcesPanel.js";
 import type { SettingsTabItem } from "../settings/SettingsTabsPage.js";
 import type { AgentPageTabProps } from "./types.js";
 export declare const AGENT_RESOURCE_DOCS_HREF: Record<ResourceView, string>;
+export declare function ConnectionsTab({ canManageOrg, }?: Partial<AgentPageTabProps>): import("react").JSX.Element;
 export declare const AGENT_ACCESS_DOCS_HREF: {
     readonly mcp: "https://agent-native.com/docs/mcp-protocol";
     readonly a2a: "https://agent-native.com/docs/a2a-protocol";

package/dist/client/agent-page/AgentTabsPage.js

@@ -113,7 +113,7 @@ function ServerStatus({ server }) {
     }
     return (_jsx("span", { className: "text-[11px] text-muted-foreground", children: "Status unknown" }));
 }
-function ConnectionsTab({ canManageOrg = false }) {
+export function ConnectionsTab({ canManageOrg, } = {}) {
     const t = useT();
     const serversQuery = useMcpServers();
     const createServer = useCreateMcpServer();
@@ -123,8 +123,9 @@ function ConnectionsTab({ canManageOrg = false }) {
     const [deleteTarget, setDeleteTarget] = useState(null);
     const [error, setError] = useState(null);
     const data = serversQuery.data;
+    const resolvedCanManageOrg = canManageOrg ?? (data?.role === "owner" || data?.role === "admin");
     const hasOrg = Boolean(data?.orgId);
-    const canCreateOrgMcp = hasOrg && canManageOrg;
+    const canCreateOrgMcp = hasOrg && resolvedCanManageOrg;
     const onCreateMcpServer = useCallback(async (args) => {
         if (args.scope === "org" && !canCreateOrgMcp) {
             throw new Error("Only organization admins can add organization agent integrations.");
@@ -152,7 +153,7 @@ function ConnectionsTab({ canManageOrg = false }) {
     };
     const renderServer = (server) => {
         const key = `${server.scope}:${server.id}`;
-        const canDelete = server.scope === "user" || canManageOrg;
+        const canDelete = server.scope === "user" || resolvedCanManageOrg;
         const selected = selectedServer?.id === server.id && selectedServer.scope === server.scope;
         return (_jsxs("div", { className: cn("group/connection-row py-4 transition-colors first:pt-5 last:pb-5", selected && "bg-accent/20"), children: [_jsxs("div", { className: "flex items-start gap-3", children: [_jsxs("button", { type: "button", onClick: () => setSelectedServer(selected ? null : server), className: "min-w-0 flex-1 cursor-pointer text-start", children: [_jsx("div", { className: "flex flex-wrap items-center gap-2", children: _jsx("span", { className: "truncate text-sm font-medium text-foreground", children: server.name }) }), _jsx("code", { className: "mt-1 block truncate text-[11px] text-muted-foreground", children: server.url }), _jsxs("div", { className: "mt-2 flex items-center gap-2", children: [_jsx(ServerStatus, { server: server }), server.description && (_jsx("span", { className: "truncate text-[11px] text-muted-foreground/70", children: server.description }))] })] }), canDelete && (_jsx("button", { type: "button", onClick: () => void removeServer(server), disabled: deleteServer.isPending, className: cn("cursor-pointer rounded-md px-2 py-1 text-[11px] font-medium text-muted-foreground hover:bg-destructive/10 hover:text-destructive", deleteTarget === key && "bg-destructive/10 text-destructive"), children: deleteTarget === key ? "Confirm" : "Delete" }))] }), selected && (_jsx("div", { className: "mt-3 border-t border-border/70 pt-3", children: _jsx(McpServerDetail, { server: server }) }))] }, key));
     };

package/dist/client/app-providers.d.ts

@@ -108,6 +108,8 @@ export interface AppProvidersProps {
      * its own scoped token. Public/SEO routes should use `isPublicPath` instead.
      */
     sessionBypass?: boolean;
+    /** Fallback used if route metadata leaves the browser title empty or structured. */
+    documentTitleFallback?: string;
     children: React.ReactNode;
 }
-export declare function AppProviders({ queryClient, isPublicPath, clientOnlyFallback, sessionBypass, defaultTheme, themeAttribute, tooltipDelayDuration, toaster, disableThemeTransitions, i18n, children, }: AppProvidersProps): React.JSX.Element;
+export declare function AppProviders({ queryClient, isPublicPath, clientOnlyFallback, sessionBypass, defaultTheme, themeAttribute, tooltipDelayDuration, toaster, disableThemeTransitions, i18n, documentTitleFallback, children, }: AppProvidersProps): React.JSX.Element;