@agent-native/dispatch 0.15.19 → 0.15.21

package/dist/server/lib/provider-api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider-api.d.ts","sourceRoot":"","sources":["../../../src/server/lib/provider-api.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,sBAAsB,EAE3B,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,sBAAsB,EAC5B,MAAM,iCAAiC,CAAC;AAGzC,eAAO,MAAM,eAAe,aAAa,CAAC;AAC1C,eAAO,MAAM,yBAAyB,kVAAmB,CAAC;AAC1D,MAAM,MAAM,qBAAqB,GAAG,aAAa,CAAC;AAClD,YAAY,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,CAAC;AA0C1D,wBAAgB,sBAAsB,CAAC,QAAQ,CAAC,EAAE,MAAM;;;;;;;;;;;;;;;;;yBAEvD;AAED,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,sBAAsB,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,oBAGvD;AAED,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,sBAAsB,oBAErE"}
+{"version":3,"file":"provider-api.d.ts","sourceRoot":"","sources":["../../../src/server/lib/provider-api.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,sBAAsB,EAE3B,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,sBAAsB,EAC5B,MAAM,iCAAiC,CAAC;AAGzC,eAAO,MAAM,eAAe,aAAa,CAAC;AAC1C,eAAO,MAAM,yBAAyB,kVAAmB,CAAC;AAC1D,MAAM,MAAM,qBAAqB,GAAG,aAAa,CAAC;AAClD,YAAY,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,CAAC;AA0C1D,wBAAgB,sBAAsB,CAAC,QAAQ,CAAC,EAAE,MAAM;;;;;;;;;;;;;;;;;;yBAEvD;AAED,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,sBAAsB,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,oBAGvD;AAED,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,sBAAsB,oBAErE"}

package/dist/server/plugins/integrations.js

@@ -36,7 +36,7 @@ When a user asks for something:
 - If the user asks to create, build, make, scaffold, or generate an "agent" from Dispatch chat or by tagging @agent-native in Slack, email, or Telegram, first classify the ask. If it is a simple Dispatch-native behavior like a reminder, digest, monitor, routing rule, saved instruction, or recurring workflow, create or update the recurring job/resource/destination in Dispatch. If it is a robust unique product or teammate that needs its own UI, data model, actions, integrations, or domain workflow, treat it as a new workspace app and call start-workspace-app-creation.
 - If a new-app prompt asks for access to Mail, Calendar, Analytics, Brain, Assets, or similar first-party app data/agents, keep using the existing hosted/connected app and A2A path. Do not ask Builder to scaffold those apps as children of the new app unless the user explicitly asks for a customized fork/copy.
 - If the chat template is used, treat it as scaffolding only: the finished app must be branded as the requested app with its own home screen/navigation/package metadata/manifest, and must not leave visible "Chat", "Starter", "Blank app", or "New app" UI behind.
-- If the user explicitly asks for a new app or workspace app, call start-workspace-app-creation with their prompt and include a concise generated description by default. Do not satisfy a new-app request by adding a route, page, component, or file inside apps/chat or another existing app unless the user explicitly asks to modify that existing app. If the request is too vague to classify, ask one concise follow-up. If the action returns mode "builder", reply with the Builder branch URL; Builder is responsible for creating the separate workspace app under apps/<app-id>, mounting it at /<app-id>, ensuring apps/<app-id>/package.json exists with name/displayName and description so Dispatch discovers it, using relative /<app-id> links instead of hardcoded localhost/dev ports, and preserving APP_BASE_PATH/VITE_APP_BASE_PATH via appBasePath() in the React Router client entry. The new app lives at the workspace root /<app-id>, NOT under /dispatch/<app-id>, /apps/<app-id>, or any other Dispatch tab — when telling the user where to find it, link to /<app-id> only. There is no separate workspace app registry to edit. If it returns mode "local-agent", tell the user it is ready for the local code agent and include the returned app path/prompt summary. If it returns mode "coming-soon", say this requires a code change and they can edit locally or use Builder.io to edit this code in the cloud and continue customizing the app any way they like; do not send them to Builder org/beta settings. If it returns mode "builder-unavailable", report the action's message exactly enough to preserve the missing identity/credential detail.
+- If the user explicitly asks for a new app or workspace app, call start-workspace-app-creation with their prompt and include a concise generated description by default. Do not satisfy a new-app request by adding a route, page, component, or file inside apps/chat or another existing app unless the user explicitly asks to modify that existing app. If the request is too vague to classify, ask one concise follow-up. If the action returns mode "builder", reply with the Builder branch URL; Builder is responsible for creating the separate workspace app under apps/<app-id>, mounting it at /<app-id>, ensuring apps/<app-id>/package.json exists with name/displayName and description so Dispatch discovers it, using relative /<app-id> links instead of hardcoded localhost/dev ports, and preserving APP_BASE_PATH/VITE_APP_BASE_PATH via appBasePath() in the React Router client entry. The new app lives at the workspace root /<app-id>, NOT under /dispatch/<app-id>, /apps/<app-id>, or any other Dispatch tab — when telling the user where to find it, link to /<app-id> only. There is no separate workspace app registry to edit. If it returns mode "local-agent", tell the user it is ready for the local code agent and include the returned app path/prompt summary. If it returns mode "coming-soon", say this requires a code change and they can edit locally or use Builder.io to edit this code in the cloud and continue customizing the app any way they like; do not send them to Builder org/beta settings. If it returns mode "builder-unavailable", the action also returns a \`reason\` code plus a user-facing \`message\` and (for some reasons) an operator-facing \`detail\`. Relay the \`message\` to the user as-is; only surface \`detail\` when the user is clearly an operator debugging the deployment (e.g. troubleshooting a broken Builder connection for the workspace), never as routine detail for an end user.
 - For digests, reminders, or saved behavior, prefer recurring jobs, resources, or destinations over chat replies.
 - Keep responses concise and operational — messaging platforms have character limits.
 - Use markdown sparingly (bold and lists are fine, avoid complex formatting).

package/dist/server/plugins/integrations.js.map

@@ -1 +1 @@
-{"version":3,"file":"integrations.js","sourceRoot":"","sources":["../../../src/server/plugins/integrations.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AAErE,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EACL,qBAAqB,EACrB,+BAA+B,GAChC,MAAM,iCAAiC,CAAC;AAEzC,MAAM,0BAA0B,GAAG;IACjC,GAAG,eAAe;IAClB,2EAA2E;IAC3E,6EAA6E;IAC7E,6EAA6E;IAC7E,OAAO,EAAE;QACP,GAAG,eAAe,CAAC,OAAO;QAC1B,SAAS,EAAE,KAAK;KACjB;CACF,CAAC;AAEF,MAAM,kCAAkC,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;4FA4BiD,CAAC;AAE7F;;;;GAIG;AACH,MAAM,0BAA0B,GAAG,KAAK,EAAE,QAAa,EAAE,EAAE;IACzD,MAAM,EAAE,YAAY,GAAG,EAAE,EAAE,GAAG,iBAAiB,EAAE,CAAC;IAClD,MAAM,cAAc,GAAG,YAAY,CAAC,YAAY,CAAC;IACjD,MAAM,YAAY,GAChB,OAAO,cAAc,KAAK,QAAQ;QAChC,CAAC,CAAC,cAAc;QAChB,CAAC,CAAC,OAAO,cAAc,KAAK,UAAU;YACpC,CAAC,CAAC,cAAc,CAAC,kCAAkC,CAAC;YACpD,CAAC,CAAC,kCAAkC,CAAC;IAE3C,MAAM,MAAM,GAAG,wBAAwB,CAAC;QACtC,KAAK,EAAE,UAAU;QACjB,OAAO,EAAE,0BAA0B;QACnC,uBAAuB,EAAE,+BAA+B;QACxD,aAAa,EAAE,qBAAqB;QACpC,YAAY;QACZ,wDAAwD;QACxD,yEAAyE;QACzE,+DAA+D;QAC/D,6EAA6E;KAC9E,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC;AAC1B,CAAC,CAAC;AAEF,eAAe,0BAA0B,CAAC","sourcesContent":["import { createIntegrationsPlugin } from \"@agent-native/core/server\";\n\nimport { dispatchActions } from \"../../actions/index.js\";\nimport { getDispatchConfig } from \"../index.js\";\nimport {\n  beforeDispatchProcess,\n  resolveDispatchExecutionContext,\n} from \"../lib/dispatch-integrations.js\";\n\nconst dispatchIntegrationActions = {\n  ...dispatchActions,\n  // Messaging integrations should use the core call-agent tool for cross-app\n  // delegation because it queues A2A continuations when serverless budgets are\n  // tight. The MCP-facing ask_app action is still available outside this path.\n  ask_app: {\n    ...dispatchActions.ask_app,\n    agentTool: false,\n  },\n};\n\nconst DISPATCH_INTEGRATION_SYSTEM_PROMPT = `You are the central dispatch for this workspace, responding via a messaging platform integration (Slack, Telegram, email, etc.).\n\nDefault posture:\n- Treat Slack, Telegram, and email as shared entrypoints into the workspace.\n- Heavily delegate domain work to specialized agents through A2A (call-agent) when another app owns the job. Apps you can delegate to include slides (decks/presentations), analytics (data/dashboards), content (docs/articles), forms (form builder), clips (screen recordings), design (visual designs), and assets (brand libraries plus generated images/videos).\n- Use the available-apps prompt context first, then list-connected-agents when you need fresh details, to see what agents are available before assuming a request must be handled locally.\n- Hosted/connected A2A neighbors such as Analytics and Content come from the available-apps context or list-connected-agents. list-workspace-apps only inventories apps mounted inside this workspace deployment; never use a missing row there to conclude that a connected agent is unavailable.\n- When asked whether a mounted workspace app exposes an agent card or A2A endpoint, call list-workspace-apps with includeAgentCards=true. Without that probe, missing agent-card fields mean unchecked, not unavailable.\n- Treat first-party apps such as Mail, Calendar, Analytics, Brain, Assets, and Dispatch as existing hosted/connected neighbors available through links and A2A/default connected agents. Do not create wrapper apps, child apps, nested routes, or cloned template copies just to give a new app access to them; build only the genuinely new workflow and delegate cross-app work to those existing apps.\n- Integration grants are not provider capability limits. For ad hoc provider inspection, querying, reporting, or troubleshooting, call provider-api-catalog/provider-api-docs, then provider-api-request against the provider's real HTTP API. Use connectionId for a specific shared grant and accountId for a specific OAuth account. Never expose secret values or silently widen app access while doing this.\n- Keep durable memory and operating instructions in resources rather than ephemeral chat.\n- Reply in the originating thread unless the user explicitly asks you to send to a saved destination.\n\nWhen a user asks for something:\n- If it belongs to analytics, content, slides, clips, assets, etc., delegate via call-agent — do not re-implement the domain logic in dispatch.\n- Synthetic uptime, health-check, and URL-availability monitors belong to Analytics, even when the monitored target is another app such as Clips. Delegate creation to Analytics and relay its exact monitor URL. Dispatch-native recurring jobs are for reminders, digests, and agent workflows, not HTTP uptime probes.\n- Route by the requested artifact type, not by organization-specific names stored in code. For structured records, databases, tables, queues, boards, and intake forms, resolve the owning app and canonical destination from loaded workspace instructions/resources plus discovered app capabilities; do not assume Content, a database ID, schema, owner, or required fields. Visual designs, mockups, wireframes, screens, and interfaces belong to Design. A trusted Required target agent hint in integration context is authoritative.\n- When delegating structured intake to the resolved owning app, preserve the exact Source thread URL and the workspace instruction context, inspect the destination's current required fields, ask only for missing values, submit once, verify the saved record, and return the exact link.\n- In messaging integrations, use call-agent for cross-app delegation; do not use ask_app.\n- After call-agent returns an answer, RELAY IT DIRECTLY to the user with at most a one-line preface — do not rephrase, summarize, or add commentary. The downstream agent already crafted the answer; your job is delivery, not editing. This minimizes round-trips and keeps the user-visible reply fast.\n- Exception: if the downstream agent reports a missing model/provider credential, do not name exact env vars, Vault keys, tokens, or secrets. Say the target app needs an LLM connection and recommend connecting Builder/managed LLM for that app; keep bring-your-own provider keys as a secondary option only if the user asks.\n- If the user asks to create, build, make, scaffold, or generate an \"agent\" from Dispatch chat or by tagging @agent-native in Slack, email, or Telegram, first classify the ask. If it is a simple Dispatch-native behavior like a reminder, digest, monitor, routing rule, saved instruction, or recurring workflow, create or update the recurring job/resource/destination in Dispatch. If it is a robust unique product or teammate that needs its own UI, data model, actions, integrations, or domain workflow, treat it as a new workspace app and call start-workspace-app-creation.\n- If a new-app prompt asks for access to Mail, Calendar, Analytics, Brain, Assets, or similar first-party app data/agents, keep using the existing hosted/connected app and A2A path. Do not ask Builder to scaffold those apps as children of the new app unless the user explicitly asks for a customized fork/copy.\n- If the chat template is used, treat it as scaffolding only: the finished app must be branded as the requested app with its own home screen/navigation/package metadata/manifest, and must not leave visible \"Chat\", \"Starter\", \"Blank app\", or \"New app\" UI behind.\n- If the user explicitly asks for a new app or workspace app, call start-workspace-app-creation with their prompt and include a concise generated description by default. Do not satisfy a new-app request by adding a route, page, component, or file inside apps/chat or another existing app unless the user explicitly asks to modify that existing app. If the request is too vague to classify, ask one concise follow-up. If the action returns mode \"builder\", reply with the Builder branch URL; Builder is responsible for creating the separate workspace app under apps/<app-id>, mounting it at /<app-id>, ensuring apps/<app-id>/package.json exists with name/displayName and description so Dispatch discovers it, using relative /<app-id> links instead of hardcoded localhost/dev ports, and preserving APP_BASE_PATH/VITE_APP_BASE_PATH via appBasePath() in the React Router client entry. The new app lives at the workspace root /<app-id>, NOT under /dispatch/<app-id>, /apps/<app-id>, or any other Dispatch tab — when telling the user where to find it, link to /<app-id> only. There is no separate workspace app registry to edit. If it returns mode \"local-agent\", tell the user it is ready for the local code agent and include the returned app path/prompt summary. If it returns mode \"coming-soon\", say this requires a code change and they can edit locally or use Builder.io to edit this code in the cloud and continue customizing the app any way they like; do not send them to Builder org/beta settings. If it returns mode \"builder-unavailable\", report the action's message exactly enough to preserve the missing identity/credential detail.\n- For digests, reminders, or saved behavior, prefer recurring jobs, resources, or destinations over chat replies.\n- Keep responses concise and operational — messaging platforms have character limits.\n- Use markdown sparingly (bold and lists are fine, avoid complex formatting).\n- If a task requires many steps, summarize what you did rather than streaming every detail.`;\n\n/**\n * Defer plugin construction until the Nitro plugin actually fires so the\n * config-aware system prompt resolves AFTER `setupDispatch(config)` has\n * stamped the active config (plugin module load order is not guaranteed).\n */\nconst dispatchIntegrationsPlugin = async (nitroApp: any) => {\n  const { integrations = {} } = getDispatchConfig();\n  const promptOverride = integrations.systemPrompt;\n  const systemPrompt =\n    typeof promptOverride === \"string\"\n      ? promptOverride\n      : typeof promptOverride === \"function\"\n        ? promptOverride(DISPATCH_INTEGRATION_SYSTEM_PROMPT)\n        : DISPATCH_INTEGRATION_SYSTEM_PROMPT;\n\n  const plugin = createIntegrationsPlugin({\n    appId: \"dispatch\",\n    actions: dispatchIntegrationActions,\n    resolveExecutionContext: resolveDispatchExecutionContext,\n    beforeProcess: beforeDispatchProcess,\n    systemPrompt,\n    // Inherit the framework default (claude-sonnet-4-6 from\n    // packages/core/src/integrations/plugin.ts). Haiku was tried for latency\n    // but hallucinated URLs/IDs after delegated call-agent results\n    // (e.g. inventing `https://slides.workspace.com/deck/builder-io-deck-2024`).\n  });\n\n  return plugin(nitroApp);\n};\n\nexport default dispatchIntegrationsPlugin;\n"]}
+{"version":3,"file":"integrations.js","sourceRoot":"","sources":["../../../src/server/plugins/integrations.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AAErE,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EACL,qBAAqB,EACrB,+BAA+B,GAChC,MAAM,iCAAiC,CAAC;AAEzC,MAAM,0BAA0B,GAAG;IACjC,GAAG,eAAe;IAClB,2EAA2E;IAC3E,6EAA6E;IAC7E,6EAA6E;IAC7E,OAAO,EAAE;QACP,GAAG,eAAe,CAAC,OAAO;QAC1B,SAAS,EAAE,KAAK;KACjB;CACF,CAAC;AAEF,MAAM,kCAAkC,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;4FA4BiD,CAAC;AAE7F;;;;GAIG;AACH,MAAM,0BAA0B,GAAG,KAAK,EAAE,QAAa,EAAE,EAAE;IACzD,MAAM,EAAE,YAAY,GAAG,EAAE,EAAE,GAAG,iBAAiB,EAAE,CAAC;IAClD,MAAM,cAAc,GAAG,YAAY,CAAC,YAAY,CAAC;IACjD,MAAM,YAAY,GAChB,OAAO,cAAc,KAAK,QAAQ;QAChC,CAAC,CAAC,cAAc;QAChB,CAAC,CAAC,OAAO,cAAc,KAAK,UAAU;YACpC,CAAC,CAAC,cAAc,CAAC,kCAAkC,CAAC;YACpD,CAAC,CAAC,kCAAkC,CAAC;IAE3C,MAAM,MAAM,GAAG,wBAAwB,CAAC;QACtC,KAAK,EAAE,UAAU;QACjB,OAAO,EAAE,0BAA0B;QACnC,uBAAuB,EAAE,+BAA+B;QACxD,aAAa,EAAE,qBAAqB;QACpC,YAAY;QACZ,wDAAwD;QACxD,yEAAyE;QACzE,+DAA+D;QAC/D,6EAA6E;KAC9E,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC;AAC1B,CAAC,CAAC;AAEF,eAAe,0BAA0B,CAAC","sourcesContent":["import { createIntegrationsPlugin } from \"@agent-native/core/server\";\n\nimport { dispatchActions } from \"../../actions/index.js\";\nimport { getDispatchConfig } from \"../index.js\";\nimport {\n  beforeDispatchProcess,\n  resolveDispatchExecutionContext,\n} from \"../lib/dispatch-integrations.js\";\n\nconst dispatchIntegrationActions = {\n  ...dispatchActions,\n  // Messaging integrations should use the core call-agent tool for cross-app\n  // delegation because it queues A2A continuations when serverless budgets are\n  // tight. The MCP-facing ask_app action is still available outside this path.\n  ask_app: {\n    ...dispatchActions.ask_app,\n    agentTool: false,\n  },\n};\n\nconst DISPATCH_INTEGRATION_SYSTEM_PROMPT = `You are the central dispatch for this workspace, responding via a messaging platform integration (Slack, Telegram, email, etc.).\n\nDefault posture:\n- Treat Slack, Telegram, and email as shared entrypoints into the workspace.\n- Heavily delegate domain work to specialized agents through A2A (call-agent) when another app owns the job. Apps you can delegate to include slides (decks/presentations), analytics (data/dashboards), content (docs/articles), forms (form builder), clips (screen recordings), design (visual designs), and assets (brand libraries plus generated images/videos).\n- Use the available-apps prompt context first, then list-connected-agents when you need fresh details, to see what agents are available before assuming a request must be handled locally.\n- Hosted/connected A2A neighbors such as Analytics and Content come from the available-apps context or list-connected-agents. list-workspace-apps only inventories apps mounted inside this workspace deployment; never use a missing row there to conclude that a connected agent is unavailable.\n- When asked whether a mounted workspace app exposes an agent card or A2A endpoint, call list-workspace-apps with includeAgentCards=true. Without that probe, missing agent-card fields mean unchecked, not unavailable.\n- Treat first-party apps such as Mail, Calendar, Analytics, Brain, Assets, and Dispatch as existing hosted/connected neighbors available through links and A2A/default connected agents. Do not create wrapper apps, child apps, nested routes, or cloned template copies just to give a new app access to them; build only the genuinely new workflow and delegate cross-app work to those existing apps.\n- Integration grants are not provider capability limits. For ad hoc provider inspection, querying, reporting, or troubleshooting, call provider-api-catalog/provider-api-docs, then provider-api-request against the provider's real HTTP API. Use connectionId for a specific shared grant and accountId for a specific OAuth account. Never expose secret values or silently widen app access while doing this.\n- Keep durable memory and operating instructions in resources rather than ephemeral chat.\n- Reply in the originating thread unless the user explicitly asks you to send to a saved destination.\n\nWhen a user asks for something:\n- If it belongs to analytics, content, slides, clips, assets, etc., delegate via call-agent — do not re-implement the domain logic in dispatch.\n- Synthetic uptime, health-check, and URL-availability monitors belong to Analytics, even when the monitored target is another app such as Clips. Delegate creation to Analytics and relay its exact monitor URL. Dispatch-native recurring jobs are for reminders, digests, and agent workflows, not HTTP uptime probes.\n- Route by the requested artifact type, not by organization-specific names stored in code. For structured records, databases, tables, queues, boards, and intake forms, resolve the owning app and canonical destination from loaded workspace instructions/resources plus discovered app capabilities; do not assume Content, a database ID, schema, owner, or required fields. Visual designs, mockups, wireframes, screens, and interfaces belong to Design. A trusted Required target agent hint in integration context is authoritative.\n- When delegating structured intake to the resolved owning app, preserve the exact Source thread URL and the workspace instruction context, inspect the destination's current required fields, ask only for missing values, submit once, verify the saved record, and return the exact link.\n- In messaging integrations, use call-agent for cross-app delegation; do not use ask_app.\n- After call-agent returns an answer, RELAY IT DIRECTLY to the user with at most a one-line preface — do not rephrase, summarize, or add commentary. The downstream agent already crafted the answer; your job is delivery, not editing. This minimizes round-trips and keeps the user-visible reply fast.\n- Exception: if the downstream agent reports a missing model/provider credential, do not name exact env vars, Vault keys, tokens, or secrets. Say the target app needs an LLM connection and recommend connecting Builder/managed LLM for that app; keep bring-your-own provider keys as a secondary option only if the user asks.\n- If the user asks to create, build, make, scaffold, or generate an \"agent\" from Dispatch chat or by tagging @agent-native in Slack, email, or Telegram, first classify the ask. If it is a simple Dispatch-native behavior like a reminder, digest, monitor, routing rule, saved instruction, or recurring workflow, create or update the recurring job/resource/destination in Dispatch. If it is a robust unique product or teammate that needs its own UI, data model, actions, integrations, or domain workflow, treat it as a new workspace app and call start-workspace-app-creation.\n- If a new-app prompt asks for access to Mail, Calendar, Analytics, Brain, Assets, or similar first-party app data/agents, keep using the existing hosted/connected app and A2A path. Do not ask Builder to scaffold those apps as children of the new app unless the user explicitly asks for a customized fork/copy.\n- If the chat template is used, treat it as scaffolding only: the finished app must be branded as the requested app with its own home screen/navigation/package metadata/manifest, and must not leave visible \"Chat\", \"Starter\", \"Blank app\", or \"New app\" UI behind.\n- If the user explicitly asks for a new app or workspace app, call start-workspace-app-creation with their prompt and include a concise generated description by default. Do not satisfy a new-app request by adding a route, page, component, or file inside apps/chat or another existing app unless the user explicitly asks to modify that existing app. If the request is too vague to classify, ask one concise follow-up. If the action returns mode \"builder\", reply with the Builder branch URL; Builder is responsible for creating the separate workspace app under apps/<app-id>, mounting it at /<app-id>, ensuring apps/<app-id>/package.json exists with name/displayName and description so Dispatch discovers it, using relative /<app-id> links instead of hardcoded localhost/dev ports, and preserving APP_BASE_PATH/VITE_APP_BASE_PATH via appBasePath() in the React Router client entry. The new app lives at the workspace root /<app-id>, NOT under /dispatch/<app-id>, /apps/<app-id>, or any other Dispatch tab — when telling the user where to find it, link to /<app-id> only. There is no separate workspace app registry to edit. If it returns mode \"local-agent\", tell the user it is ready for the local code agent and include the returned app path/prompt summary. If it returns mode \"coming-soon\", say this requires a code change and they can edit locally or use Builder.io to edit this code in the cloud and continue customizing the app any way they like; do not send them to Builder org/beta settings. If it returns mode \"builder-unavailable\", the action also returns a \\`reason\\` code plus a user-facing \\`message\\` and (for some reasons) an operator-facing \\`detail\\`. Relay the \\`message\\` to the user as-is; only surface \\`detail\\` when the user is clearly an operator debugging the deployment (e.g. troubleshooting a broken Builder connection for the workspace), never as routine detail for an end user.\n- For digests, reminders, or saved behavior, prefer recurring jobs, resources, or destinations over chat replies.\n- Keep responses concise and operational — messaging platforms have character limits.\n- Use markdown sparingly (bold and lists are fine, avoid complex formatting).\n- If a task requires many steps, summarize what you did rather than streaming every detail.`;\n\n/**\n * Defer plugin construction until the Nitro plugin actually fires so the\n * config-aware system prompt resolves AFTER `setupDispatch(config)` has\n * stamped the active config (plugin module load order is not guaranteed).\n */\nconst dispatchIntegrationsPlugin = async (nitroApp: any) => {\n  const { integrations = {} } = getDispatchConfig();\n  const promptOverride = integrations.systemPrompt;\n  const systemPrompt =\n    typeof promptOverride === \"string\"\n      ? promptOverride\n      : typeof promptOverride === \"function\"\n        ? promptOverride(DISPATCH_INTEGRATION_SYSTEM_PROMPT)\n        : DISPATCH_INTEGRATION_SYSTEM_PROMPT;\n\n  const plugin = createIntegrationsPlugin({\n    appId: \"dispatch\",\n    actions: dispatchIntegrationActions,\n    resolveExecutionContext: resolveDispatchExecutionContext,\n    beforeProcess: beforeDispatchProcess,\n    systemPrompt,\n    // Inherit the framework default (claude-sonnet-4-6 from\n    // packages/core/src/integrations/plugin.ts). Haiku was tried for latency\n    // but hallucinated URLs/IDs after delegated call-agent results\n    // (e.g. inventing `https://slides.workspace.com/deck/builder-io-deck-2024`).\n  });\n\n  return plugin(nitroApp);\n};\n\nexport default dispatchIntegrationsPlugin;\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/dispatch",
-  "version": "0.15.19",
+  "version": "0.15.21",
   "description": "Dispatch — workspace control plane for agent-native apps. Vault, integrations, destinations, scheduled jobs, and cross-app delegation, shipped as a single drop-in package.",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {
@@ -86,7 +86,7 @@
     "tailwind-merge": "^3.5.0",
     "vaul": "^1.1.2",
     "zod": "^4.3.6",
-    "@agent-native/toolkit": "0.10.5"
+    "@agent-native/toolkit": "0.10.6"
   },
   "devDependencies": {
     "@react-router/dev": "^8.1.0",
@@ -100,7 +100,7 @@
     "typescript-7": "npm:typescript@^7.0.2",
     "vite": "8.1.0",
     "vitest": "^4.1.5",
-    "@agent-native/core": "0.120.3"
+    "@agent-native/core": "0.122.0"
   },
   "peerDependencies": {
     "@agent-native/core": ">=0.8.0",

package/src/actions/set-app-creation-settings.ts

@@ -5,7 +5,7 @@ import { setAppCreationSettings } from "../server/lib/app-creation-store.js";
 
 export default defineAction({
   description:
-    "Set Dispatch settings for creating new workspace apps. Does not write env vars or files.",
+    "Set Dispatch settings for creating new workspace apps, and the Builder project this organization uses for cloud code changes. Stores the project id as an organization-scoped credential; does not write env vars or files.",
   schema: z.object({
     builderProjectId: z
       .string()
@@ -14,7 +14,9 @@ export default defineAction({
       .max(128)
       .optional()
       .nullable()
-      .describe("Default Builder project ID to use for app creation branches"),
+      .describe(
+        "Builder project ID used for app-creation branches and for cloud code-change branches across this organization's workspace apps. Pass null to clear it and return those apps to the connect/waitlist prompt.",
+      ),
   }),
   run: async (args) => setAppCreationSettings(args),
 });

package/src/components/create-app-popover.spec.tsx

@@ -0,0 +1,249 @@
+// @vitest-environment happy-dom
+import React, { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { CreateAppFlow } from "./create-app-popover";
+
+const sendToAgentChatMock = vi.hoisted(() => vi.fn());
+const devState = vi.hoisted(() => ({ isDevMode: false }));
+const frameState = vi.hoisted(() => ({ inBuilderFrame: false }));
+const builderConnectFlowState = vi.hoisted(() => ({
+  connecting: false,
+  start: vi.fn(),
+}));
+const startWorkspaceAppCreationResponse = vi.hoisted<{ result: unknown }>(
+  () => ({
+    result: {
+      mode: "builder",
+      appId: "qa-dashboard",
+      url: "https://branch.example.test",
+    },
+  }),
+);
+
+vi.mock("@agent-native/core/client/agent-chat", () => ({
+  sendToAgentChat: sendToAgentChatMock,
+  useDevMode: () => ({ isDevMode: devState.isDevMode }),
+}));
+
+vi.mock("@agent-native/core/client/host", () => ({
+  isInBuilderFrame: () => frameState.inBuilderFrame,
+}));
+
+vi.mock("@agent-native/core/client/settings/useBuilderStatus", () => ({
+  useBuilderConnectFlow: () => ({
+    configured: false,
+    connecting: builderConnectFlowState.connecting,
+    error: null,
+    start: builderConnectFlowState.start,
+  }),
+}));
+
+vi.mock("@agent-native/core/client/composer", async () => {
+  const ReactModule = await import("react");
+  return {
+    PromptComposer: ({
+      onSubmit,
+      placeholder,
+      disabled,
+    }: {
+      onSubmit: (text: string, files: File[], references: unknown[]) => void;
+      placeholder?: string;
+      disabled?: boolean;
+    }) => {
+      const [value, setValue] = ReactModule.useState("");
+      return ReactModule.createElement(
+        "div",
+        null,
+        ReactModule.createElement("textarea", {
+          "aria-label": "Prompt",
+          placeholder,
+          value,
+          onChange: (event: React.ChangeEvent<HTMLTextAreaElement>) =>
+            setValue(event.target.value),
+        }),
+        ReactModule.createElement(
+          "button",
+          {
+            disabled: disabled || !value.trim(),
+            onClick: () => onSubmit(value, [], []),
+            type: "button",
+          },
+          "Create app",
+        ),
+      );
+    },
+  };
+});
+
+function jsonResponse(data: unknown, status = 200): Response {
+  return new Response(JSON.stringify(data), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+function findButton(container: HTMLElement, text: string): HTMLButtonElement {
+  const button = Array.from(container.querySelectorAll("button")).find(
+    (candidate) => candidate.textContent?.includes(text),
+  );
+  if (!button) throw new Error(`Button not found: ${text}`);
+  return button as HTMLButtonElement;
+}
+
+function changeValue(
+  element: HTMLInputElement | HTMLTextAreaElement,
+  value: string,
+) {
+  const setter = Object.getOwnPropertyDescriptor(
+    Object.getPrototypeOf(element),
+    "value",
+  )?.set;
+  act(() => {
+    setter?.call(element, value);
+    element.dispatchEvent(new Event("input", { bubbles: true }));
+    element.dispatchEvent(new Event("change", { bubbles: true }));
+  });
+}
+
+describe("CreateAppFlow", () => {
+  let container: HTMLDivElement;
+  let root: Root;
+  let fetchSpy: ReturnType<typeof vi.fn>;
+
+  beforeEach(() => {
+    vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
+    devState.isDevMode = false;
+    frameState.inBuilderFrame = false;
+    builderConnectFlowState.connecting = false;
+    builderConnectFlowState.start.mockReset();
+    startWorkspaceAppCreationResponse.result = {
+      mode: "builder",
+      appId: "qa-dashboard",
+      url: "https://branch.example.test",
+    };
+    sendToAgentChatMock.mockReset();
+    fetchSpy = vi.fn(async (input: RequestInfo | URL) => {
+      const url = String(input);
+      if (url.includes("get-vault-access-settings")) {
+        return jsonResponse({ mode: "all-apps" });
+      }
+      if (url.includes("list-vault-secret-options")) {
+        return jsonResponse([]);
+      }
+      if (url.includes("list-workspace-resource-options")) {
+        return jsonResponse([]);
+      }
+      if (url.includes("start-workspace-app-creation")) {
+        return jsonResponse(startWorkspaceAppCreationResponse.result);
+      }
+      return jsonResponse({ error: `Unexpected URL: ${url}` }, 404);
+    });
+    vi.stubGlobal("fetch", fetchSpy);
+    container = document.createElement("div");
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+    vi.unstubAllGlobals();
+  });
+
+  async function renderAndSubmit(prompt: string) {
+    await act(async () => {
+      root.render(React.createElement(CreateAppFlow, {}));
+    });
+
+    changeValue(
+      container.querySelector('textarea[aria-label="Prompt"]')!,
+      prompt,
+    );
+
+    await act(async () => {
+      findButton(container, "Create app").click();
+    });
+  }
+
+  it("renders a Connect Builder control when Builder is not connected", async () => {
+    startWorkspaceAppCreationResponse.result = {
+      mode: "builder-unavailable",
+      reason: "builder-not-connected",
+      message: "Connect Builder for this user",
+      appId: "quality",
+    };
+    await renderAndSubmit("Build a quality dashboard");
+
+    await act(async () => {
+      await vi.waitFor(() =>
+        expect(container.textContent).toContain(
+          "Connect Builder for this user",
+        ),
+      );
+    });
+
+    const connectButton = findButton(container, "Connect Builder");
+    act(() => {
+      connectButton.click();
+    });
+    expect(builderConnectFlowState.start).toHaveBeenCalledTimes(1);
+  });
+
+  it("renders the error affordance and a Try again control for builder-error, without a Connect Builder control", async () => {
+    startWorkspaceAppCreationResponse.result = {
+      mode: "builder-unavailable",
+      reason: "builder-error",
+      message: "Builder rejected the request.",
+      appId: "quality",
+      detail: "500 from Builder",
+      projectId: "proj_1",
+    };
+    await renderAndSubmit("Build a quality dashboard");
+
+    await act(async () => {
+      await vi.waitFor(() =>
+        expect(container.textContent).toContain(
+          "Builder rejected the request.",
+        ),
+      );
+    });
+
+    const matchingDivs = Array.from(container.querySelectorAll("div")).filter(
+      (el) => el.textContent?.includes("Builder rejected the request."),
+    );
+    expect(
+      matchingDivs.some((el) => el.className.includes("border-destructive")),
+    ).toBe(true);
+
+    expect(() => findButton(container, "Connect Builder")).toThrow();
+    expect(findButton(container, "Try again")).toBeTruthy();
+  });
+
+  it("renders coming-soon messages neutrally with no Connect Builder control", async () => {
+    startWorkspaceAppCreationResponse.result = {
+      mode: "coming-soon",
+      message: "This template is coming soon.",
+      appId: "quality",
+    };
+    await renderAndSubmit("Build a quality dashboard");
+
+    await act(async () => {
+      await vi.waitFor(() =>
+        expect(container.textContent).toContain(
+          "This template is coming soon.",
+        ),
+      );
+    });
+
+    const matchingDivs = Array.from(container.querySelectorAll("div")).filter(
+      (el) => el.textContent?.includes("This template is coming soon."),
+    );
+    expect(
+      matchingDivs.some((el) => el.className.includes("border-destructive")),
+    ).toBe(false);
+    expect(() => findButton(container, "Connect Builder")).toThrow();
+    expect(() => findButton(container, "Try again")).toThrow();
+  });
+});

package/src/components/create-app-popover.tsx

@@ -6,8 +6,10 @@ import {
 } from "@agent-native/core/client/api-path";
 import { PromptComposer } from "@agent-native/core/client/composer";
 import { isInBuilderFrame } from "@agent-native/core/client/host";
+import { useBuilderConnectFlow } from "@agent-native/core/client/settings/useBuilderStatus";
 import { getWorkspaceAppIdValidationError } from "@agent-native/core/shared";
 import {
+  IconAlertTriangle,
   IconArrowLeft,
   IconArrowUpRight,
   IconBook,
@@ -160,6 +162,16 @@ function actionUrl(basePath: string | null, action: string): string {
   return `${normalized}${path}`;
 }
 
+const ERROR_FAILURE_REASONS = new Set([
+  "builder-error",
+  "builder-not-connected",
+  "credential-store-unavailable",
+]);
+
+function isErrorFailureReason(reason: string | null): boolean {
+  return !!reason && ERROR_FAILURE_REASONS.has(reason);
+}
+
 /**
  * Inline two-step app-creation flow: prompt → optional access picker → submit.
  * Used both in the popover form and in the dedicated `/new-app` page so the
@@ -184,11 +196,25 @@ export function CreateAppFlow({
   const [resourcesError, setResourcesError] = useState<string | null>(null);
   const [statusMessage, setStatusMessage] = useState<string | null>(null);
   const [branchUrl, setBranchUrl] = useState<string | null>(null);
+  const [failureReason, setFailureReason] = useState<string | null>(null);
   const [isSubmitting, setIsSubmitting] = useState(false);
   const { isDevMode } = useDevMode();
 
   const basePath = useMemo(() => defaultDispatchBasePath(), []);
 
+  // Enabled only while the connect CTA is on screen. Left always-on, the hook
+  // would poll Builder status on every popover mount and fire onConnected on
+  // its first status read for anyone already connected.
+  const connectFlow = useBuilderConnectFlow({
+    enabled: failureReason === "builder-not-connected",
+    trackingSource: "dispatch_create_app",
+    trackingFlow: "create_app",
+    onConnected: () => {
+      setFailureReason(null);
+      setStatusMessage("Builder connected. Press Create app to try again.");
+    },
+  });
+
   // Fetch access options eagerly so step 2 has them ready immediately.
   useEffect(() => {
     let cancelled = false;
@@ -285,6 +311,7 @@ export function CreateAppFlow({
     setIsSubmitting(true);
     setStatusMessage(null);
     setBranchUrl(null);
+    setFailureReason(null);
 
     try {
       if (isInBuilderFrame()) {
@@ -321,10 +348,14 @@ export function CreateAppFlow({
             result?.message ||
               "This requires a code change. Edit locally or use Builder.io to edit this code in the cloud and continue customizing the app any way you like.",
           );
+          setFailureReason(
+            result?.mode === "builder-unavailable" ? result.reason : null,
+          );
         }
       }
     } catch (err: any) {
       setStatusMessage(err?.message || "Could not start the new app flow.");
+      setFailureReason(null);
     } finally {
       setIsSubmitting(false);
     }
@@ -548,17 +579,53 @@ export function CreateAppFlow({
       )}
 
       {statusMessage ? (
-        <div className="rounded-md border border-border bg-muted/40 px-3 py-2 text-xs text-muted-foreground">
-          {statusMessage}
-          {branchUrl ? (
-            <a
-              href={branchUrl}
-              target="_blank"
-              rel="noreferrer"
-              className="ml-2 inline-flex items-center gap-1 font-medium text-foreground underline"
+        <div
+          className={`flex flex-col gap-2 rounded-md border px-3 py-2 text-xs ${
+            isErrorFailureReason(failureReason)
+              ? "border-destructive/40 bg-destructive/10 text-destructive"
+              : "border-border bg-muted/40 text-muted-foreground"
+          }`}
+        >
+          <div className="flex flex-wrap items-center gap-2">
+            {isErrorFailureReason(failureReason) ? (
+              <IconAlertTriangle className="h-3.5 w-3.5 shrink-0" />
+            ) : null}
+            <span>{statusMessage}</span>
+            {branchUrl ? (
+              <a
+                href={branchUrl}
+                target="_blank"
+                rel="noreferrer"
+                className="inline-flex items-center gap-1 font-medium text-foreground underline"
+              >
+                Open branch <IconArrowUpRight className="h-3 w-3" />
+              </a>
+            ) : null}
+          </div>
+          {failureReason === "builder-not-connected" ? (
+            <Button
+              type="button"
+              size="sm"
+              variant="outline"
+              onClick={() => connectFlow.start()}
+              disabled={connectFlow.connecting}
+              className="w-fit"
             >
-              Open branch <IconArrowUpRight className="h-3 w-3" />
-            </a>
+              {connectFlow.connecting ? "Connecting..." : "Connect Builder"}
+            </Button>
+          ) : null}
+          {failureReason === "credential-store-unavailable" ||
+          failureReason === "builder-error" ? (
+            <Button
+              type="button"
+              size="sm"
+              variant="outline"
+              onClick={submitWithSelectedAccess}
+              disabled={isSubmitting}
+              className="w-fit"
+            >
+              Try again
+            </Button>
           ) : null}
         </div>
       ) : null}

package/src/components/layout/Layout.tsx

@@ -747,13 +747,16 @@ export function NavContent({
           </nav>
         </div>
 
-        {!collapsed ? (
-          <div className="mt-auto shrink-0">
-            <div className="px-3 py-2">
-              <OrgSwitcher />
-            </div>
+        <div className="mt-auto shrink-0">
+          <div
+            className={cn(
+              "py-2",
+              collapsed ? "flex justify-center px-1" : "px-3",
+            )}
+          >
+            <OrgSwitcher compact={collapsed} />
           </div>
-        ) : null}
+        </div>
         <SidebarFooterActions
           collapsed={collapsed}
           feedback={feedbackButton}

package/src/components/workspace-template-card.tsx

@@ -151,7 +151,17 @@ export function WorkspaceTemplateCard({
   const setupNote = template.integrationSetup || template.setupNote;
   const remix = useActionMutation("remix-workspace-template", {
     onSuccess: (result) => {
-      toast.success(labels.remixSuccess);
+      const mode = (result as { mode?: string } | null)?.mode;
+      const message = (result as { message?: string } | null)?.message;
+      if (mode === "builder") {
+        toast.success(labels.remixSuccess);
+      } else if (mode === "builder-unavailable") {
+        toast.error(message || labels.remixError);
+      } else if (mode === "coming-soon") {
+        toast.info(message || labels.remixSuccess);
+      } else {
+        toast.success(labels.remixSuccess);
+      }
       setOpen(false);
       onRemixSuccess?.(result, template);
     },