@agent-native/core 0.122.4 → 0.123.0

package/src/templates/workspace-core/AGENTS.md

@@ -4,140 +4,78 @@ These instructions apply to every app in the {{APP_TITLE}} workspace. Keep
 only rules that should be shared across all apps here. App-specific behavior
 belongs in that app's own `AGENTS.md` or `.agents/skills/` directory.
 
-## Framework Docs Lookup
-
-Version-matched Agent Native docs ship with `@agent-native/core` in
-`node_modules/@agent-native/core/docs`. A source-only corpus of core and
-first-party template patterns ships in `node_modules/@agent-native/core/corpus`.
-
-- From an app directory, use `pnpm action docs-search --query "<topic>"`,
-  `pnpm action docs-search --slug <slug>`, or `pnpm action docs-search --list`.
-  Use `pnpm action source-search --query "<pattern>"` or
-  `pnpm action source-search --path <path>` when source examples matter.
-- If the action runner is unavailable, read
-  `node_modules/@agent-native/core/docs/AGENTS.md` and search
-  `node_modules/@agent-native/core/docs/content/` directly with `rg`. Search
-  `node_modules/@agent-native/core/corpus/` for source examples.
-- For advanced workspace features, start with `workspace`, `multi-app-workspace`,
-  `a2a-protocol`, `pure-agent-apps`, `automations`, `recurring-jobs`,
-  `external-agents`, `mcp-protocol`, `feature-flags`, `sharing`, and `security`.
-
-Use package docs for framework APIs, the package corpus for reusable
-framework/template patterns, and this `AGENTS.md` plus `.agents/skills/` for
-workspace-specific conventions.
-Before building common workspace or agent UI, read `agent-native-toolkit` to
-inventory existing public kits and installed package seams. Read
-`customizing-agent-native` before adapting shared UI. Use the supported
-ladder: configure → compose → eject the smallest unit → propose a shared seam.
-Preview before `--apply`, commit `agent-native.ejections.json`, and never edit
-`node_modules` or eject protected runtime contracts.
+## Skills
+
+Read the matching skill in `.agents/skills/` before working in that area.
+
+| Skill | Read before |
+| --- | --- |
+| `workspace-conventions` | Shared vs app-owned code, file/blob storage, env and secrets, scratch files, Dispatch Resources |
+| `adding-workspace-apps` | Creating, scaffolding, mounting, or branding an app under `apps/<app-name>` |
+| `agent-native-docs` | Looking up version-matched framework docs, slugs, or the bundled source corpus |
+| `agent-native-toolkit` | Building workspace or agent UI, app chrome, settings, sharing, or collaboration |
+| `customizing-agent-native` | Adapting, overriding, or ejecting shared framework UI |
+| `delegate-to-agent` | Building agent-driven UI or any "AI" feature |
+| `actions` | Adding or changing an app operation the agent and UI share |
+| `composable-mini-apps` | Cross-app workflows, headless mini-apps, and A2A handoffs |
+| `shadcn-ui` | Adding, updating, or debugging a shadcn/ui primitive |
+| `security`, `sharing` | Access scoping, ownable data, and sharing user-authored resources |
+| `automations` | Event-triggered or scheduled background work (with `recurring-jobs`) |
 
 ## Shared Context
 
 Add company, product, compliance, or support-context notes that every app
 agent should know.
 
-## Shared Conventions
-
-- All AI/LLM behavior goes through the app's agent chat. UI and server code
-  must not call model providers, AI SDK `generateText()` / `streamText()`, or
-  other inline LLM APIs directly. Use `sendToAgentChat()` for local app-agent
-  work, including hidden `context` and `submit: false` prefill/review flows.
-  Only use `useAgentChatContext`, `setAgentChatContextItem`,
-  `listAgentChatContext`, `removeAgentChatContextItem`, and
-  `clearAgentChatContext` when UI needs two-way sync with staged context chips.
-  Read `.agents/skills/delegate-to-agent/SKILL.md` before building agent-driven
-  UI or "AI" features.
-- Put shared code in `packages/shared` only when multiple apps need it.
-- Keep app-specific screens, actions, state, and skills inside `apps/<app>`.
-- SQL is for structured records, metadata, references, and searchable text. Store
-  large files/blob payloads (base64, `data:` URLs, images, video/audio, PDFs,
-  ZIPs, screenshots, thumbnails, session replay chunks) in configured file/blob
-  storage and persist only URLs, ids, or handles.
-- Store shared runtime configuration in the workspace root `.env`; use
-  `apps/<app>/.env` only for app-specific overrides. Never hardcode API keys,
-  tokens, webhook URLs, signing secrets, private Builder/internal data, customer
-  data, or credential-looking literals in source, docs, prompts, fixtures,
-  application state, action responses, or generated app content. Use
-  secrets/OAuth/runtime configuration and obvious placeholders in examples.
+## Core Rules
+
+- All AI/LLM behavior goes through the app's agent chat. UI and server code must
+  not call model providers or AI SDK `generateText()` / `streamText()` directly;
+  use `sendToAgentChat()`. Read `.agents/skills/delegate-to-agent/SKILL.md`
+  before building agent-driven UI or "AI" features.
+- Normal app data must flow through actions. Define `defineAction` files in
+  `actions/`, mark reads with `http: { method: "GET" }`, and call them from React
+  with `useActionQuery` / `useActionMutation`. Do not add `/api/*` routes that
+  duplicate, wrap, proxy, or re-export an action.
+- Keep app-specific screens, actions, state, and skills inside `apps/<app>`. Put
+  shared code in `packages/shared` only when multiple apps need it.
+- App database code must be provider-agnostic: `@agent-native/core/db/schema`
+  helpers plus Drizzle's query builder. Never import `drizzle-orm/sqlite-core`
+  or `drizzle-orm/pg-core` from an app.
+- SQL is for structured records, metadata, references, and searchable text.
+  Large files and blob payloads belong in configured file/blob storage; persist
+  only URLs, ids, or handles.
+- Never hardcode API keys, tokens, webhook URLs, signing secrets, private
+  Builder/internal data, customer data, or credential-looking literals anywhere,
+  including application state, action responses, and generated app content. Use
+  secrets/OAuth/runtime configuration and obvious placeholders.
+- Never hardcode `localhost`, `127.0.0.1`, or a dev port. Use relative workspace
+  links like `/<app-name>`; the workspace gateway origin owns the port.
+- Do not implement a new app by adding routes, pages, or files to `apps/chat` or
+  another existing app unless the user explicitly asks to modify that app. Read
+  `adding-workspace-apps` first.
 - Prefer framework defaults until the workspace has a real custom rule,
   component, plugin, action, or skill to share.
-- Keep the Workspace files view for user-authored or user-requested resources.
-  Agents may create hidden `agent_scratch` resources for temporary working
-  notes, scripts, task plans, or intermediate outputs, but should promote them
-  to normal workspace visibility only when the user explicitly asks to keep or
-  manage the file.
-- Runtime-editable global resources can be managed from Dispatch Resources.
-  Use `AGENTS.md` or `instructions/<slug>.md` for always-on guardrails,
-  `skills/<slug>/SKILL.md` for workspace skills, `context/<slug>.md` for
-  personas/positioning/messaging/company facts/brand guidelines, and
-  `agents/<slug>.md` for custom agent profiles. Scope them to All apps when
-  every workspace app should inherit them. All-app resources are inherited at
-  runtime; do not copy or sync them into individual apps.
+- Before building common workspace or agent UI, read `agent-native-toolkit` to
+  inventory existing public kits and installed package seams. Read
+  `customizing-agent-native` before adapting shared UI: configure → compose →
+  eject the smallest unit → propose a shared seam. Never edit `node_modules`.
 
-## Adding Apps
+## Framework Docs
 
-When a user asks from Dispatch chat or through `@agent-native` in Slack or
-Telegram to create, build, make, scaffold, or generate an "agent", classify
-the ask first.
-Simple Dispatch-native behavior such as a reminder, digest, monitor, routing
-rule, saved instruction, or recurring workflow can stay in Dispatch as a
-recurring job/resource/destination. Robust unique products or teammates that
-need their own UI, data model, actions, integrations, or domain workflow should
-become a separate workspace app under `apps/<app-name>`, mounted at
-`/<app-name>`.
+Version-matched Agent Native docs and a source-only corpus of core and
+first-party template patterns ship with `@agent-native/core`. From an app
+directory, use `pnpm action docs-search --query "<topic>"` and
+`pnpm action source-search --query "<pattern>"`. Read `workspace-conventions`
+for slugs, the `--list` / `--slug` / `--path` options, and the `rg` fallback.
 
-Do not implement a new app by adding a route, page, component, or file to
-`apps/chat` or another existing app unless the user explicitly asks to modify
-that existing app.
-
-Dispatch vault access is workspace-wide by default: every saved vault key is
-available to every workspace app. Only create or request per-app vault grants
-when Dispatch's vault access setting is switched to manual mode.
-
-Workspace apps are discovered from `apps/<app-name>/package.json`. There is no
-separate workspace app registry to edit for Dispatch to list the app. Always
-save a concise, human-readable `description` there; Dispatch lists and A2A
-connected-agent context use the app name plus description so agents know what
-the app does. Use relative workspace links like `/<app-name>` and never
-hardcode `localhost`, `127.0.0.1`, `8080`, `8100`, or any dev port in app
-cards, instructions, redirects, or navigation; the active workspace
-gateway/browser origin owns the port. React Router apps must preserve
-`APP_BASE_PATH` / `VITE_APP_BASE_PATH` in
-`app/entry.client.tsx` via `appBasePath()` so the app hydrates correctly when
-mounted at `/<app-name>`. Use the framework/template UI stack for standard UI:
-shadcn/ui components and `@tabler/icons-react`. Do not add `lucide-react` or
-another icon library. Read `.agents/skills/shadcn-ui/SKILL.md` before adding,
-updating, or debugging shadcn components.
-
-Normal app data must flow through actions. For CRUD that the agent can perform,
-create `defineAction` files in `actions/`, mark reads with
-`http: { method: "GET" }`, and call them from React with `useActionQuery` /
-`useActionMutation`. Do not add duplicate JSON CRUD routes under `/api/*` for
-the same data unless the route is for uploads, streaming, webhooks, OAuth, or
-another route-only concern. Do not add routes whose main job is to wrap,
-proxy, or re-export an action; the action endpoint already exists at
-`/_agent-native/actions/:name`. Action-backed UI is what makes agent-created or
-agent-edited records appear without a manual refresh.
-
-App database code must be provider-agnostic. Define schemas with
-`@agent-native/core/db/schema` helpers and write app reads/writes with Drizzle's
-query builder and portable `drizzle-orm` operators. Do not import from
-`drizzle-orm/sqlite-core` or `drizzle-orm/pg-core` in app templates. Keep raw SQL
-for additive migrations, health checks, or carefully scoped maintenance, and
-never write SQLite-only or Postgres-only product code. Do not use SQL as object
-storage; file bytes belong in upload/private-blob providers with only references
-saved to app tables.
+Use package docs for framework APIs, the package corpus for reusable
+framework/template patterns, and this `AGENTS.md` plus `.agents/skills/` for
+workspace-specific conventions.
 
-In local development, run
-`pnpm exec agent-native create <app-name> --template=<template>` from the
-workspace root. In production, Dispatch posts new-app requests to Builder
-branch creation; Builder should still scaffold the separate workspace app. The
-workspace dev gateway (`pnpm dev`) detects new `apps/<app-name>` directories
-automatically.
+## Actions
 
-When using the chat template, 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 domain workflow. Do not leave visible
-`Chat`, `Starter`, `Blank app`, `Start building`, or `New app` UI in a chat-derived
-app.
+| Action | Purpose |
+| --- | --- |
+| `docs-search` | Search version-matched framework docs by query or slug, or list |
+| `source-search` | Search the bundled core/template source corpus by pattern or path |

package/src/templates/workspace-root/AGENTS.md

@@ -76,6 +76,9 @@ refreshes framework-provided shared skills and repairs `CLAUDE.md` /
 
 ## Workspace Scope
 
+- Scale effort to the task. A small, well-specified change is a short read, the
+  edit, and the existing checks — not a codebase survey, unrequested tests, or
+  browser automation.
 - Keep root changes focused on workspace orchestration, shared configuration,
   deploy settings, and monorepo tooling.
 - Keep application routes, actions, server plugins, and app state inside the
@@ -156,7 +159,9 @@ refreshes framework-provided shared skills and repairs `CLAUDE.md` /
   for the same data unless the route is for uploads, streaming, webhooks,
   OAuth, or another route-only concern. Do not add routes whose main job is to
   wrap, proxy, or re-export an action; the action endpoint already exists at
-  `/_agent-native/actions/:name`. Action-backed UI is what makes agent-created
+  `/_agent-native/actions/:name`. If you are about to create a file under
+  `server/routes/api/`, or middleware to guard one, stop and write a
+  `defineAction` instead. Action-backed UI is what makes agent-created
   or agent-edited records appear without a manual refresh.
 - App database code must be provider-agnostic. Define schemas with
   `@agent-native/core/db/schema` helpers and write app reads/writes with

package/src/triggers/dispatcher.ts

@@ -18,6 +18,7 @@ import {
   getOwnerActiveApiKey,
   type ActionEntry,
 } from "../agent/production-agent.js";
+import { runAgentLoopDirectWithSoftTimeout } from "../agent/run-loop-with-resume.js";
 import { attachToolSearch } from "../agent/tool-search.js";
 import type { AgentChatEvent } from "../agent/types.js";
 import { createThread } from "../chat-threads/store.js";
@@ -485,24 +486,34 @@ ${body}`;
           null;
 
         try {
-          triggerUsage = await runAgentLoop({
-            engine,
-            model,
-            systemPrompt,
-            tools,
-            availableTools,
-            messages,
-            actions,
-            send: (event) => events.push(event),
-            signal: controller.signal,
-            threadId: thread.id,
-            actionCaller: "automation",
-            automation: {
-              triggerId: resource.id,
-              triggerName,
-              policyId: meta.delegatedPolicyId,
+          // Wrapper, not raw `runAgentLoop`: an automation runs with nobody
+          // watching, so a transport-level cut (gateway 45s, socket hang up)
+          // has to be resumed inside this invocation or the trigger silently
+          // does nothing. `undefined` budget + the hosted default keeps the
+          // soft timeout under the serverless wall on hosts that have one and
+          // disabled locally.
+          triggerUsage = await runAgentLoopDirectWithSoftTimeout(
+            {
+              engine,
+              model,
+              systemPrompt,
+              tools,
+              availableTools,
+              messages,
+              actions,
+              send: (event) => events.push(event),
+              signal: controller.signal,
+              threadId: thread.id,
+              actionCaller: "automation",
+              automation: {
+                triggerId: resource.id,
+                triggerName,
+                policyId: meta.delegatedPolicyId,
+              },
             },
-          });
+            undefined,
+            { useHostedDefault: true },
+          );
         } finally {
           clearTimeout(timeout);
         }

package/src/vite/client.ts

@@ -1648,18 +1648,30 @@ function baseRedirectGuard(): Plugin {
         if (serveMountedEmbedRuntimeModule(server, req, res, base)) {
           return;
         }
-        // Nitro's pre-middleware only intercepts document/iframe/frame/empty
-        // fetch-dest requests. For video/audio/image etc. it calls next() and
-        // the post-internal Nitro middleware handles them instead. If we strip
-        // the base path here for those requests, Vite's base middleware sees the
-        // stripped path (e.g. /api/video/:id without /clips/) and responds with
-        // a "did you mean /clips/api/video/:id" error before Nitro can handle it.
-        // Only strip when the request type matches Nitro's pre-middleware gate.
+        // stripMountedDevApiPath only rewrites paths that resolve to /api/**
+        // (see isApiDevPath below), so this never touches static asset or
+        // document requests — only mounted API calls. Nitro's dev router
+        // matches routes against req.url with the mount prefix still in
+        // place (its own baseURL is unset in dev), so a mounted API request
+        // must have that prefix stripped before Nitro's router ever sees it,
+        // regardless of Sec-Fetch-Dest — otherwise it falls through to
+        // Vite/connect's generic 404 instead of the real handler. This used
+        // to be gated to document/iframe/frame/empty only, because stripping
+        // for video/audio/image previously made Vite's base middleware see
+        // the stripped path (e.g. /api/video/:id without /clips/) before
+        // Nitro's router got a chance to match it. That gate is stale: image
+        // and video requests hit the exact same "Cannot GET" fallback today,
+        // because the browser sends Sec-Fetch-Dest: image/video/audio/track
+        // for <img>/<video>/<audio> fetches, not empty — so those requests
+        // were never actually reaching Nitro pre-strip in the first place.
         const secFetchDest = req.headers["sec-fetch-dest"] as
           | string
           | undefined;
         const isNitroPreHandled =
-          !secFetchDest || /^(document|iframe|frame|empty)$/.test(secFetchDest);
+          !secFetchDest ||
+          /^(document|iframe|frame|empty|image|video|audio|track)$/.test(
+            secFetchDest,
+          );
         if (isNitroPreHandled) {
           req.url = stripMountedDevApiPath(req.url, base);
         }

package/corpus/core/src/client/components/MissingKeyCard.tsx

@@ -1,61 +0,0 @@
-export interface MissingKeyCardProps {
-  label: string;
-  message: string;
-  settingsPath: string;
-}
-
-export function MissingKeyCard({
-  label,
-  message,
-  settingsPath,
-}: MissingKeyCardProps) {
-  return (
-    <div
-      style={{
-        border: "1px solid hsl(var(--border))",
-        borderRadius: 8,
-        padding: "24px 28px",
-        maxWidth: 420,
-        margin: "32px auto",
-        background: "hsl(var(--card))",
-        color: "hsl(var(--card-foreground))",
-        textAlign: "center",
-      }}
-    >
-      <div
-        style={{
-          fontSize: 14,
-          fontWeight: 600,
-          color: "hsl(var(--card-foreground))",
-          marginBottom: 8,
-        }}
-      >
-        {label}
-      </div>
-      <p
-        style={{
-          fontSize: 13,
-          color: "hsl(var(--muted-foreground))",
-          margin: "0 0 16px",
-        }}
-      >
-        {message}
-      </p>
-      <a
-        href={settingsPath}
-        style={{
-          display: "inline-block",
-          padding: "8px 16px",
-          fontSize: 13,
-          fontWeight: 500,
-          color: "hsl(var(--primary-foreground))",
-          background: "hsl(var(--primary))",
-          borderRadius: 6,
-          textDecoration: "none",
-        }}
-      >
-        Go to Settings
-      </a>
-    </div>
-  );
-}