@agent-native/core 0.152.1 → 0.153.0

package/src/templates/default/.agents/skills/workspace-conventions/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: workspace-conventions
+description: >-
+  Shared conventions for a multi-app Agent Native workspace: finding
+  version-matched framework docs and source, shared vs app-owned code, file and
+  blob storage, env and secrets, agent scratch files, and Dispatch Resources.
+  Use when working across workspace apps, storing files or credentials, or
+  looking up framework APIs.
+scope: dev
+---
+
+# Workspace Conventions
+
+The long-form detail behind the workspace `AGENTS.md` core rules. Read this
+before adding shared code, storing files or secrets, creating workspace
+resources, or looking up framework APIs.
+
+## Framework Docs Lookup
+
+Read `agent-native-docs` for the lookup workflow (`framework-search` first, then
+the focused `docs-search` / `source-search` readers, and the `rg` fallback).
+
+The workspace-specific slugs it does not list are `workspace` and
+`multi-app-workspace`. Feature flags and other specialized workflows are
+optional; read their skill only when the app uses them. 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.
+
+## 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.
+  Keep actions deterministic and focused. If a workflow is framed as research,
+  analysis, generation, recommendation, or synthesis, let the agent
+  orchestrate provider/data actions in the open AgentSidebar instead of hiding
+  the work in one opaque action or a separate follow-up textbox.
+  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.
+- Each app deploys its own `/*` page function, and that function ships whatever
+  the app's server bundle depends on — including a dependency only a background
+  job uses. Before an app takes on a heavy runtime (headless browser, ffmpeg,
+  media processing, ML), read `.agents/skills/performance/SKILL.md` §9 and keep
+  that work in a background function or job. A dependency belonging to one app
+  does not belong in `packages/shared`.
+- 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.
+
+## Related Skills
+
+- **adding-workspace-apps** — Creating and mounting a new app under `apps/`.
+- **agent-native-docs** — The full docs and source-corpus lookup workflow.
+- **agent-native-toolkit** — Inventory of shared workspace and agent UI.
+- **customizing-agent-native** — The configure → compose → eject ladder.
+- **delegate-to-agent** — Routing every AI feature through the agent chat.
+- **performance** — Load cost, and (§9) cold-start artifact size per app.
+- **secrets** — Registering API keys and service credentials.
+- **storing-data** — Where structured data and large payloads belong.

package/src/templates/default/AGENTS.md

@@ -55,6 +55,21 @@ cross-cutting work and `self-modifying-code` when changing app source.
 - A missing or unreadable value must stay distinguishable from success. Throw or
   return an explicit error instead of silently falling back to an empty value.
 
+## Lightweight defaults
+
+Apps are English-only and do not generate changelog entries by default. If an
+app needs more locales or user-facing release notes, opt in from
+`agent-native.config.ts`:
+
+```ts
+import { defineAgentNativeConfig } from "@agent-native/core";
+
+export default defineAgentNativeConfig({
+  translations: { locales: ["en-US", "fr-FR"] },
+  changelog: { enabled: true },
+});
+```
+
 ## Application state
 
 Use the existing `application_state` helpers for navigation and selection. Keep
@@ -92,5 +107,5 @@ private package internals.
 ## Verification
 
 Match checks to the change: run the existing focused tests, typecheck, and
-formatter. For a user-facing template change, record a changelog entry from
-the app with `agent-native changelog add` when appropriate.
+formatter. Add a changelog entry only when `changelog.enabled` is true in the
+app's `agent-native.config.ts`.

package/src/templates/default/agent-native.config.ts

@@ -0,0 +1,6 @@
+import { defineAgentNativeConfig } from "@agent-native/core";
+
+export default defineAgentNativeConfig({
+  translations: { locales: ["en-US"] },
+  changelog: { enabled: false },
+});

package/src/templates/default/app/i18n/ar-SA.ts

@@ -279,6 +279,8 @@ const messages = {
     publicDescription: "يمكن لأي شخص قام بتسجيل الدخول باستخدام الرابط المشاهدة",
     viewer: "Viewer",
     viewerDescription: "يمكن عرض",
+    commenter: "معلّق",
+    commenterDescription: "يمكنه العرض وإضافة التعليقات",
     editor: "Editor",
     editorDescription: "يمكن تحرير",
     admin: "مسؤول",

package/src/templates/default/app/i18n/de-DE.ts

@@ -282,6 +282,8 @@ const messages = {
       "Jeder, der mit dem Link angemeldet ist, kann es ansehen",
     viewer: "Viewer",
     viewerDescription: "Kann angesehen werden",
+    commenter: "Kommentator",
+    commenterDescription: "Kann ansehen und Kommentare hinzufügen",
     editor: "Editor",
     editorDescription: "Kann bearbeiten",
     admin: "Admin",

package/src/templates/default/app/i18n/en-US.ts

@@ -164,7 +164,7 @@ const messages = {
       appBuildingSuffix:
         "after its branch is merged and the workspace deploy finishes.",
       branch: "Branch: {{branch}}",
-      openBuilderBranch: "Open Builder branch",
+      openBuilderBranch: "Open in Builder",
       openingApp: "Opening {{name}}",
       redirectingTo: "Redirecting to",
       openApp: "Open app",
@@ -276,6 +276,8 @@ const messages = {
     publicDescription: "Anyone signed in with the link can view",
     viewer: "Viewer",
     viewerDescription: "Can view",
+    commenter: "Commenter",
+    commenterDescription: "Can view and add comments",
     editor: "Editor",
     editorDescription: "Can edit",
     admin: "Admin",

package/src/templates/default/app/i18n/es-ES.ts

@@ -283,6 +283,8 @@ const messages = {
       "Cualquiera que haya iniciado sesión con el enlace puede ver",
     viewer: "Viewer",
     viewerDescription: "puede ver",
+    commenter: "Comentarista",
+    commenterDescription: "Puede ver y añadir comentarios",
     editor: "Editor",
     editorDescription: "puede editar",
     admin: "Administrador",

package/src/templates/default/app/i18n/fr-FR.ts

@@ -283,6 +283,8 @@ const messages = {
     publicDescription: "Toute personne connectée avec le lien peut voir",
     viewer: "Viewer",
     viewerDescription: "Peut voir",
+    commenter: "Commentateur",
+    commenterDescription: "Peut consulter et ajouter des commentaires",
     editor: "Editor",
     editorDescription: "Peut modifier",
     admin: "Admin",

package/src/templates/default/app/i18n/hi-IN.ts

@@ -268,6 +268,8 @@ const messages = {
     publicDescription: "लिंक से साइन इन किया गया कोई भी व्यक्ति देख सकता है",
     viewer: "Viewer",
     viewerDescription: "देख सकते हैं",
+    commenter: "टिप्पणीकार",
+    commenterDescription: "देख और टिप्पणियां जोड़ सकते हैं",
     editor: "Editor",
     editorDescription: "संपादित कर सकते हैं",
     admin: "व्यवस्थापक",

package/src/templates/default/app/i18n/ja-JP.ts

@@ -278,6 +278,8 @@ const messages = {
       "リンクを使用してサインインしている人は誰でも閲覧できます",
     viewer: "Viewer",
     viewerDescription: "閲覧可能",
+    commenter: "コメント投稿者",
+    commenterDescription: "閲覧してコメントを追加できます",
     editor: "Editor",
     editorDescription: "編集可能",
     admin: "管理者",

package/src/templates/default/app/i18n/ko-KR.ts

@@ -272,6 +272,8 @@ const messages = {
     publicDescription: "링크로 로그인한 사람은 누구나 볼 수 있습니다.",
     viewer: "Viewer",
     viewerDescription: "볼 수 있음",
+    commenter: "댓글 작성자",
+    commenterDescription: "보고 댓글을 추가할 수 있습니다",
     editor: "Editor",
     editorDescription: "편집 가능",
     admin: "관리자",

package/src/templates/default/app/i18n/pt-BR.ts

@@ -282,6 +282,8 @@ const messages = {
     publicDescription: "Qualquer pessoa conectada com o link pode visualizar",
     viewer: "Viewer",
     viewerDescription: "Pode visualizar",
+    commenter: "Comentarista",
+    commenterDescription: "Pode visualizar e adicionar comentários",
     editor: "Editor",
     editorDescription: "Pode editar",
     admin: "Admin",

package/src/templates/default/app/i18n/zh-CN.ts

@@ -266,6 +266,8 @@ const messages = {
     publicDescription: "使用链接登录的任何人都可以查看",
     viewer: "Viewer",
     viewerDescription: "可以查看",
+    commenter: "评论者",
+    commenterDescription: "可以查看并添加评论",
     editor: "Editor",
     editorDescription: "可以编辑",
     admin: "管理员",

package/src/templates/default/app/i18n/zh-TW.ts

@@ -264,6 +264,8 @@ const messages = {
     publicDescription: "使用連結登入的任何人都可以檢視",
     viewer: "Viewer",
     viewerDescription: "可以檢視",
+    commenter: "評論者",
+    commenterDescription: "可以檢視並新增評論",
     editor: "Editor",
     editorDescription: "可以編輯",
     admin: "管理員",

package/src/templates/headless/.agents/skills/delegate-to-agent/SKILL.md

@@ -0,0 +1,289 @@
+---
+name: delegate-to-agent
+description: >-
+  How to delegate all AI work to the agent chat. Use when delegating AI work
+  from UI or scripts to the agent, when a user asks for agent behavior or
+  LLM-powered features, when tempted to add inline LLM calls, or when sending
+  messages to the agent from application code.
+scope: dev
+metadata:
+  internal: true
+---
+
+# Delegate All AI to the Agent
+
+## Rule
+
+The app's default AI surface is the agent chat. Any user-facing work that asks
+the model to research, analyze, generate, recommend, synthesize, or reason over
+multiple steps must start or continue in the AgentSidebar so users can see,
+steer, and audit the work. UI buttons use `sendToAgentChat()` with
+`openSidebar: true`, and follow-up or revision text belongs in that same thread
+instead of a second app-local textbox.
+
+Actions are tools, not alternate AI runtimes. Keep them deterministic and
+focused: provider reads, validation, deterministic transforms, CRUD, and
+persistence are good action work. Let the agent orchestrate several such tools
+when the workflow is AI-shaped or user-steerable. Server-side one-shot model
+calls are a rare escape hatch for narrow text transforms only; use
+`completeText()` from `@agent-native/core/server` only when the work
+intentionally does not need tools, chat history, run state, side effects, or
+user steering.
+
+## Why
+
+The agent is the single AI interface. It has context about the full project, can read/write any file, and can run scripts. Inline LLM calls bypass this — they create a shadow AI that doesn't know what the agent knows and can't coordinate with it.
+
+## How
+
+**From the UI (client):**
+
+```ts
+import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
+
+sendToAgentChat({
+  message: "Generate a summary of this document",
+  context: documentContent, // optional hidden context (not shown in chat UI)
+  submit: true, // auto-submit to the agent
+  openSidebar: true,
+});
+```
+
+### Keep user text separate from injected context
+
+Treat the visible `message` as the user's request or the shortest clear
+description of an app-initiated operation. Put context the user did not type —
+IDs, URLs, filenames, current selection or screen state, serialized records,
+upload instructions, and bounded source excerpts — in the `context` field.
+`context` is model input carried through the agent turn; it is stripped from
+the rendered user message, so do not concatenate it into `message` with labels,
+blank-line sections, or `<context>` tags yourself.
+
+Use the related surface for each kind of supporting input:
+
+| Surface | Use for |
+| --- | --- |
+| `message` | User-authored intent or a concise app action description |
+| `context` | Derived metadata and bounded text needed to carry out that intent |
+| `setAgentChatContextItem` | Context staged for a later user-submitted prompt; keep it keyed so updates replace stale context |
+| `images`, `referenceImagePaths`, attachments | Binary or visual inputs; describe only the handling instructions in `context` |
+
+If an app builds a prompt from a form, selection, upload, or editor state, keep
+the visible message short and pass the assembled details as `context`. Preserve
+the user's actual freeform text in `message` when it is the request; do not
+restate it as metadata in `context` unless the agent needs a structured copy.
+
+This boundary applies to auto-submitted turns and prefills. A hidden context
+field is not a license to send unbounded records or secrets: cap excerpts,
+prefer stable IDs and URLs, and use an action or resource lookup for full data.
+
+**From the UI, in the background:**
+
+```ts
+import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
+
+sendToAgentChat({
+  message: "Analyze this import and create any missing records",
+  context: `Import batch id: ${batchId}`,
+  submit: true,
+  newTab: true,
+  background: true,
+  openSidebar: false,
+});
+```
+
+This is still a full agent run: tools, actions, thread state, and run tracking
+all remain active. It simply does not focus or open the sidebar.
+
+Use this silent form only for explicitly background or system-initiated work.
+It is not the default for a user clicking an AI-labeled button; visible work
+should open the sidebar so the user can follow and redirect the run.
+
+**From scripts (Node):**
+
+```ts
+import { agentChat } from "@agent-native/core";
+
+agentChat.submit("Process the uploaded images and create thumbnails");
+```
+
+**For narrow server-side text transforms:**
+
+```ts
+import { completeText } from "@agent-native/core/server";
+
+const result = await completeText({
+  systemPrompt: "Return exactly one sentiment label.",
+  input: messageBody,
+  maxOutputTokens: 12,
+  temperature: 0,
+});
+```
+
+If the narrow exception is exposed to the UI, wrap it in an action so the UI
+and agent share the same operation. Keep it clearly non-conversational and do
+not call provider SDKs directly.
+
+**From the UI, detecting when agent is done:**
+
+```ts
+import { useAgentChatGenerating } from "@agent-native/core/client/agent-chat";
+
+function MyComponent() {
+  const isGenerating = useAgentChatGenerating();
+  // Show loading state while agent is working
+}
+```
+
+## `submit` vs Prefill
+
+The `submit` option controls whether the message is sent automatically or placed in the chat input for user review:
+
+| `submit` value | Behavior                                | Use when                                                                            |
+| -------------- | --------------------------------------- | ----------------------------------------------------------------------------------- |
+| `true`         | Auto-submits to the agent immediately   | Routine operations with clear intent; keep `openSidebar: true` for visible work |
+| `false`        | Prefills the AgentSidebar composer      | Review, edit, or add detail before the run; use the existing sidebar thread   |
+| omitted        | Uses the project's default setting      | General-purpose delegation                                                       |
+
+```ts
+// Auto-submit: routine operation
+sendToAgentChat({ message: "Update the project summary", submit: true });
+
+// Prefill: let user review before sending
+sendToAgentChat({
+  message: "Delete all projects older than 30 days",
+  submit: false,
+  openSidebar: true,
+});
+```
+
+## Capture user input in the sidebar
+
+The AgentSidebar composer is the default prompt surface. When a button needs
+the user to describe what to create, prefill that same composer and let the
+user edit or complete it:
+
+```tsx
+<Button
+  onClick={() =>
+    sendToAgentChat({
+      message: "Help me create a research report from this brief:",
+      context: researchBrief,
+      submit: false,
+      openSidebar: true,
+    })
+  }
+>
+  Start in agent
+</Button>
+```
+
+Never auto-submit a generic creative prompt when the user has not said what
+they want. Auto-submit without additional input is fine when intent is
+unambiguous:
+
+- "Try to fix" on a tool error — submits the error details with a clear fix instruction
+- "Retry the last operation" after a transient failure
+- Single-purpose buttons where there is nothing meaningful for the user to add
+
+Use a Popover only for compact, structured parameters the UI must validate,
+such as a date range, target, or approval choice. Do not add a second freeform
+prompt or follow-up textbox for an AI workflow; keep the conversation and
+revisions in the AgentSidebar thread.
+
+## Delegating to a Sub-Agent (Agent Teams)
+
+`sendToAgentChat()` delegates from app code _to_ the agent. The other axis of
+delegation is the agent handing work _to a sub-agent_ through the Agent Teams
+run-manager. The main chat stays the orchestrator: it spawns sub-agents, then
+reads and integrates their results.
+
+### When to spawn a sub-agent vs do it yourself
+
+- **Do it yourself** when the work is small, on the critical path, or tightly
+  coupled to what you're already doing. Sub-agent overhead and coordination risk
+  outweigh the benefit.
+- **Spawn a sub-agent** for a self-contained unit of work that can run
+  independently — a disjoint investigation, an isolated implementation slice, a
+  long-running search — especially when it frees the main thread to keep
+  orchestrating.
+
+### Briefing contract
+
+Every sub-agent brief must specify four things, or the sub-agent will guess:
+
+- **Objective** — the one concrete outcome it owns, in a sentence.
+- **Context** — the facts it needs (paths, prior findings, constraints) so it
+  doesn't re-derive them.
+- **Output** — the exact shape you want back (a summary, a file edited, a list
+  of paths, a yes/no with rationale).
+- **Boundaries** — what it must NOT touch (files, branches, side effects) and
+  when to stop and report rather than push forward.
+
+### Fan-out discipline
+
+- **Default to a single sub-agent.** Most delegation is one focused task.
+- **Spawn multiple only for genuinely independent units** that don't share state
+  or files. Never parallelize coupled work — if B needs A's output, run them in
+  sequence.
+- **Cap parallel fan-out at ~3.** More sub-agents means more synthesis cost and
+  more chance of conflicting edits to the same area.
+
+### Synthesis discipline
+
+- **Read every result** before concluding — don't act on the first one back.
+- **Reconcile conflicts** between sub-agent findings explicitly; decide which is
+  right rather than averaging or ignoring.
+- **Integrate into one answer.** The main thread produces the single coherent
+  result; it never just forwards raw sub-agent transcripts to the user.
+
+Background sub-agents must use the core run-manager / Agent Teams infrastructure
+rather than ad-hoc LLM calls.
+
+## Don't
+
+- Don't `import Anthropic from "@anthropic-ai/sdk"` in client or server code
+- Don't `import OpenAI from "openai"` in client or server code
+- Don't make direct API calls to any LLM provider
+- Don't use AI SDK functions like `generateText()`, `streamText()`, etc.
+- Don't build "AI features" that bypass the agent chat
+- Don't auto-submit a hardcoded prompt for generative actions — capture user input first (see above)
+- Don't use `completeText()` for workflows that need tools, database writes,
+  auditability, user steering, or multi-step reasoning. Use the agent chat
+  instead, optionally with `background: true`.
+
+## Exception
+
+Scripts may call external APIs (image generation, search, etc.) — but the AI
+reasoning and orchestration still goes through the agent. A script is a tool
+the agent uses, not a replacement for the agent.
+
+`completeText()` is allowed for small server-side transforms such as
+classification, extraction, rewriting a short string, or normalizing messy
+provider text. It deliberately runs with `tools: []` and does not create chat
+thread state.
+
+## When to Use A2A Instead
+
+`sendToAgentChat()` delegates work to the **local** agent — the one running alongside your app. When the work should go to a **different** agent entirely (e.g., asking an analytics agent for data, or a calendar agent for availability), use the A2A (agent-to-agent) protocol instead.
+
+```ts
+import { callAgent } from "@agent-native/core/a2a";
+
+// Call a different agent — not the local agent chat
+const stats = await callAgent(
+  "https://analytics.example.com",
+  "What were last week's signups?",
+  { apiKey: process.env.ANALYTICS_A2A_KEY },
+);
+```
+
+See the **a2a-protocol** skill for the full pattern.
+
+## Related Skills
+
+- **a2a-protocol** — When the work goes to a different agent, not the local one
+- **actions** — The agent invokes actions via `pnpm action <name>` to perform complex operations
+- **self-modifying-code** — The agent operates through the chat bridge to make code changes
+- **storing-data** — The agent writes results to the database after processing requests
+- **real-time-sync** — The UI updates automatically when the agent writes data