@agent-native/core 0.61.0 → 0.62.1

package/docs/content/getting-started.md

@@ -1,30 +1,42 @@
 ---
 title: "Getting Started"
-description: "Create a chat-first agent-native app, or start headless with one action and add UI later."
+description: "Start with one headless action, or start with Chat when the conversation UI is the product."
 ---
 
 # Getting Started
 
-Agent-Native is for apps where an AI agent and any UI around it share the same actions, data, and state. The default starting point is the [Chat template](/docs/template-chat): a minimal chat app with durable threads, a left sidebar, auth, live sync, and actions ready to extend.
+Agent-Native is for apps where an AI agent and any UI around it share the same
+actions, data, and state. The smallest useful app can be just one action. The
+first useful UI can be Chat. Both paths use the same runtime, so you can move
+between them without rewriting the operation the agent calls.
 
-Start with Chat when you want a browser app users can talk to immediately. Start headless when you only want actions and the local app-agent loop for now.
+Choose the first path that matches what you want to prove:
 
-If you already know you want a finished domain app, go to [Templates](/docs/cloneable-saas). If you are choosing between headless, chat, embedded, or full app, go to [Agent Surfaces](/docs/agent-surfaces). Otherwise, keep going.
+| Path                | Pick it when                                                                                                    | Creates                                                             |
+| ------------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
+| **Headless action** | You want the primitive first: one local action, the app-agent loop, CLI/HTTP/MCP/A2A, and no custom screen yet. | `actions/`, `.agents/`, runtime config, local SQLite state          |
+| **Chat app**        | You want a browser app users can talk to immediately, with durable threads and tool-call UI.                    | Everything above, plus the Chat route, sidebar, auth, and live sync |
 
-## Create a chat app {#create-your-agent}
+If you already know you want a finished domain app, go to
+[Templates](/docs/cloneable-saas). If you are choosing between headless, chat,
+embedded, or full app surfaces, go to [Agent Surfaces](/docs/agent-surfaces).
 
-You'll need [Node.js 22 or newer](https://nodejs.org) and [pnpm](https://pnpm.io) installed. Then run:
+## Path 1: One headless action {#headless-action}
+
+You'll need [Node.js 22 or newer](https://nodejs.org) and
+[pnpm](https://pnpm.io) installed. Then run:
 
 ```bash
-npx @agent-native/core@latest create my-chat-app --template chat
-cd my-chat-app
+npx @agent-native/core@latest create my-agent --headless
+cd my-agent
 pnpm install
-pnpm dev
+pnpm action hello --name Steve
+pnpm agent "Call the hello action for Steve and explain what happened."
 ```
 
-This creates the minimal Chat app: a full-page chat route, durable chat threads, the standard left sidebar, an `actions/` folder, the framework runtime, and a SQLite database at `data/app.db` unless you set `DATABASE_URL`.
-
-Open the local URL, then ask the chat what actions are available. The scaffold includes one example action:
+That is the primitive-first on-ramp: one action, no app screen, and the same
+production app-agent loop used by chat, jobs, webhooks, and hosted runtimes.
+The scaffold includes one example action:
 
 ```ts
 // actions/hello.ts
@@ -44,7 +56,33 @@ export default defineAction({
 });
 ```
 
-Run that action directly:
+Replace `hello` with the smallest real operation in your domain. That one
+operation is then callable through the CLI, HTTP, MCP, A2A, scheduled jobs,
+integration webhooks, and any future UI.
+
+Headless does not mean stateless. Actions, auth/session data, application
+state, threads, run history, credentials, and share records use SQL. Locally
+that defaults to SQLite at `data/app.db`; in production you will usually set
+`DATABASE_URL`. See [Deployment](/docs/deployment).
+
+## Path 2: Chat app {#chat-app}
+
+Use Chat when the first thing users need is a conversation UI with durable
+threads and visible tool calls:
+
+```bash
+npx @agent-native/core@latest create my-chat-app --template chat
+cd my-chat-app
+pnpm install
+pnpm dev
+```
+
+Open the local URL, then ask the chat what actions are available. The Chat
+template includes the same `actions/hello.ts` shape as the headless scaffold,
+plus a full-page chat route, the standard left sidebar, auth, live sync, and a
+SQLite database at `data/app.db` unless you set `DATABASE_URL`.
+
+Run the example action directly:
 
 ```bash
 pnpm action hello --name Steve
@@ -56,35 +94,83 @@ Then run the same app-agent loop from the terminal:
 pnpm agent "Call the hello action for Steve and explain what happened."
 ```
 
-That is the local app-agent loop. The chat UI, CLI, HTTP, MCP, A2A, jobs, and future screens can all call the same action surface.
+The chat UI, CLI, HTTP, MCP, A2A, jobs, and future screens all call the same
+action surface.
+
+## Move between paths {#move-between-paths}
+
+Headless and Chat are not separate products. Start headless when you want the
+operation first. Add Chat when a durable conversation UI helps users inspect,
+approve, or continue the work. Start with Chat when the conversation itself is
+the main workflow, then add screens only where structured UI clarifies the job.
+
+For a deeper comparison, see [Agent Surfaces](/docs/agent-surfaces). For the
+Chat template reference, see [Chat template](/docs/template-chat).
+
+## Run against a connected repo {#connected-repo}
 
-## Start headless instead {#headless}
+For a cloud headless app that works on repository files, connect GitHub through
+the connector/token model rather than cloning a long-lived sandbox checkout.
+The agent can list, search, read, create, update, and delete repository files
+through provider-scoped credentials.
 
-Use headless mode when you want no browser app yet:
+In local development, use the same shape with explicit environment variables:
 
 ```bash
-npx @agent-native/core@latest create my-agent --headless
-cd my-agent
-pnpm install
-pnpm action hello --name Steve
-pnpm agent "Call the hello action for Steve and explain what happened."
+GITHUB_REPOSITORY=owner/repo pnpm agent "Read README.md and suggest the next action."
 ```
 
-This creates the smallest local Agent-Native runtime: an `actions/` folder, instructions, the framework runtime, and SQL state. Later, add chat by starting from the [Chat template](/docs/template-chat) and moving your actions in, or by copying the Chat template's route/sidebar pattern into the headless app.
+The repo becomes context for the app-agent loop and `agent-native invoke`
+calls. This path is for repository CRUD over the GitHub API. Use a sandbox or
+Fusion-style code runtime only when you need true isolated code execution.
+
+## Compose mini-apps {#compose-mini-apps}
+
+Workspaces often become easier to reason about as several focused apps instead
+of one giant app. A `hubspot-pipeline` app can own CRM access, a
+`gong-evidence` app can own transcripts, and a `deal-brief` app can call both
+through A2A.
+
+From the CLI:
+
+```bash
+pnpm agent-native agents list
+pnpm agent-native invoke gong-evidence "Find transcript evidence for deal_123."
+```
+
+From TypeScript:
+
+```ts
+import { agentNative } from "@agent-native/core/agent-native";
+
+const agents = await agentNative.listAgents();
+const result = await agentNative.invoke(
+  "gong-evidence",
+  "Find transcript evidence for deal_123.",
+  { userEmail: "steve@example.com" },
+);
+```
 
-### Agent credentials {#agent-credentials}
+For production agent-native apps, set `A2A_SECRET` in each app environment and
+pass the caller identity (`userEmail`) so outbound calls are signed. Use
+`apiKeyEnv` only for legacy external peers that expect a static bearer token.
 
-In local development the agent command reads provider credentials from your environment, such as `ANTHROPIC_API_KEY` in a `.env` file in the project root. Browser chat surfaces can also use configured agent credentials. The full loop is not stateless: actions, auth/session data, application state, threads, and run history use SQL. Locally that defaults to SQLite; in production you will usually point `DATABASE_URL` at Postgres or another persistent SQL database. See [Deployment](/docs/deployment).
+See [A2A Protocol](/docs/a2a-protocol) and
+[Pure Agent Apps](/docs/pure-agent-apps) for the full pattern.
 
 ## What just happened? {#what-just-happened}
 
 You now have a real app-agent loop:
 
-- `hello` is one action definition, available to the agent, CLI, HTTP, MCP, A2A, and any future UI.
-- `pnpm agent` calls the same production app-agent loop used by chat, jobs, webhooks, and hosted runtimes.
-- Changes and history stay in sync because the local runtime uses SQL-backed state, even when you have no custom UI yet.
+- `hello` is one action definition, available to the agent, CLI, HTTP, MCP,
+  A2A, and any future UI.
+- `pnpm agent` calls the production app-agent loop, not an external coding
+  harness.
+- Changes and history stay in sync because the runtime uses SQL-backed state,
+  even when you have no custom UI yet.
 
-That parity between agent and UI is the whole point. See [What Is Agent-Native?](/docs/what-is-agent-native) for the bigger picture.
+That parity between agent and UI is the whole point. See
+[What Is Agent-Native?](/docs/what-is-agent-native) for the bigger picture.
 
 ## Project structure {#project-structure}
 
@@ -99,21 +185,34 @@ my-app/
   data/app.db      # Local SQLite runtime state when DATABASE_URL is unset
 ```
 
-Templates add domain-specific code on top: database schemas in `server/db/`, API routes in `server/routes/api/`, and actions in `actions/`. See [Creating Templates](/docs/creating-templates) when you are ready to build or publish a reusable template.
+Templates add domain-specific code on top: database schemas in `server/db/`,
+API routes in `server/routes/api/`, and actions in `actions/`. See
+[Creating Templates](/docs/creating-templates) when you are ready to build or
+publish a reusable template.
 
 ## Common next moves {#next-docs}
 
 Once your agent is running, the usual next step is small and concrete:
 
-- **Ask the built-in agent what it can do** — open Chat and type "what actions do you have, and what can you do here?" This verifies that the app-agent loop is connected.
-- **Add one real action** — replace `hello` with the smallest useful operation in your domain.
-- **Add UI only when it clarifies the work** — use [Agent Surfaces](/docs/agent-surfaces) to choose between headless, chat, embedded, and full-app surfaces.
-- **Deploy it** — see [Deployment](/docs/deployment) when you're ready to put the app on your own domain.
+- **Add one real action** - replace `hello` with the smallest useful operation
+  in your domain.
+- **Open Chat when conversation helps** - ask "what actions do you have, and
+  what can you do here?"
+- **Connect a repo** - give the app-agent loop explicit GitHub repository
+  context when file CRUD is the job.
+- **Compose siblings** - split provider-heavy workflows into focused mini-apps
+  and invoke them over A2A.
+- **Deploy it** - see [Deployment](/docs/deployment) when you're ready to put
+  the app on your own domain.
 
 Useful follow-up docs:
 
-- [Key Concepts](/docs/key-concepts) for the architecture: SQL, actions, polling sync, and context awareness
-- [Agent Surfaces](/docs/agent-surfaces) for choosing headless, rich chat, embedded sidecar, or full app
-- [Workspace](/docs/workspace) for instructions, skills, memory, and per-user MCP connections
-- [Messaging](/docs/messaging) for Slack, email, Telegram, and other ways to reach the agent
+- [Key Concepts](/docs/key-concepts) for the architecture: SQL, actions,
+  polling sync, and context awareness
+- [Agent Surfaces](/docs/agent-surfaces) for choosing headless, rich chat,
+  embedded, and full-app surfaces
+- [Workspace](/docs/workspace) for instructions, skills, memory, and per-user
+  MCP connections
+- [Messaging](/docs/messaging) for Slack, email, Telegram, and other ways to
+  reach the agent
 - [FAQ](/docs/faq) for setup and product questions

package/docs/content/pure-agent-apps.md

@@ -5,9 +5,19 @@ description: "Apps where the first product surface is the app-agent loop: define
 
 # Pure-Agent Apps
 
-This is the minimal end of agent-native: an app whose first user-facing surface is the agent loop, not a dashboard. For the full-UI end, start from a [template](/docs/cloneable-saas). If you are choosing between headless, chat-first, embedded, and full-app shapes, start with [Agent Surfaces](/docs/agent-surfaces).
-
-Imagine opening an app and seeing just a chat. No dashboard. No sidebar full of menus. No forms. You ask for what you want - "summarize my unread emails," "post the daily metrics to Slack," "find the candidates who replied last week" - and the agent goes off and does it. The output shows up in chat, in Slack, in your inbox, wherever it belongs.
+This is the minimal end of agent-native: an app whose first product surface is
+the agent loop, not a dashboard. That loop can start headlessly from CLI, jobs,
+webhooks, Slack, email, or A2A. Add Chat when a human-facing conversation UI is
+the right way to inspect and steer the work. For the full-UI end, start from a
+[template](/docs/cloneable-saas). If you are choosing between headless, chat,
+embedded, and full-app shapes, start with [Agent Surfaces](/docs/agent-surfaces).
+
+Imagine starting with one action and the app-agent loop. No dashboard. No
+sidebar full of menus. No forms. You ask for what you want from the terminal,
+from Slack, from email, from a scheduled job, from another agent, or from Chat -
+"summarize my unread emails," "post the daily metrics to Slack," "find the
+candidates who replied last week" - and the agent goes off and does it. The
+output shows up in the channel that asked, wherever it belongs.
 
 That's a pure-agent app. The agent _is_ the product.
 
@@ -17,7 +27,12 @@ It is still an app, not a stateless prompt. Actions, auth sessions, app state, t
 
 Most apps are built around a UI: a database table you browse, a form you fill, a chart you read. The agent is a sidekick.
 
-In a pure-agent app, that's flipped. The chat is the front door. You type a request; the agent takes action; you see the result. Everything else — settings, history, what's currently running — is one click away, but most of the time you don't need it.
+In a pure-agent app, that's flipped. The agent loop is the front door. You type
+or send a request; the agent takes action; you see the result. Chat can be the
+browser front door, but headless apps can also start from CLI, jobs, webhooks,
+or A2A. Everything else - settings, history, what's currently running - is
+available when you need it, but most of the time you do not need a custom
+dashboard.
 
 Examples of where this works really well:
 
@@ -39,9 +54,10 @@ Pick the pure-agent pattern when:
 
 If your product is built around persistent objects users browse, pivot, and share - emails, events, documents, charts - pick a [template](/docs/cloneable-saas) instead. Those have full UIs _plus_ the agent.
 
-## What ships in the box {#minimum-ui}
+## What ships in the box when you add Chat {#minimum-ui}
 
-Every pure-agent app gets five built-in surfaces, all provided by the framework — you don't build them:
+When you add the built-in Chat shell, a pure-agent app gets five built-in
+surfaces, all provided by the framework - you don't build them:
 
 1. **Chat** — the main input. Users talk to the agent, steer it, queue tasks.
 2. **Workspace** — skills, memory, instructions, custom sub-agents, connected MCP servers, scheduled jobs. Customize the agent's behavior without shipping code.
@@ -96,9 +112,9 @@ Future UI-grafting tooling should use a distinct verb or namespace. `agent-nativ
 ## Repo access for cloud headless {#repo-access}
 
 Local headless apps run against the folder on your machine. For cloud headless
-apps that need repository access, the intended model is connector-scoped access:
-a GitHub connector and token CRUD that can list repositories, search files, read
-files, create or edit files, and delete files with the user's permission.
+apps that need repository access, use connector-scoped access: a GitHub
+connector and token CRUD that can list repositories, search files, read files,
+create or edit files, and delete files with the user's permission.
 
 Do not design this as "clone the user's repo into our VM" or "give the agent a long-lived sandbox copy of the repo" as the primary model. Sandboxes are useful for isolated code execution, but repo access should be a provider integration with explicit tokens, scoped permissions, auditability, and revocation.
 

package/docs/content/template-dispatch.md

@@ -25,6 +25,7 @@ If you're running an [multi-app workspace](/docs/multi-app-workspace) with many
 
 - **Central inbox.** Slack DMs, Telegram messages, email notifications, A2A requests from other agents — all land in one place. The Dispatch agent triages and either handles them itself or delegates. See [Messaging](/docs/messaging) for how to wire Slack, email, and Telegram into your workspace.
 - **Orchestrator, not specialist.** Dispatch does _not_ try to be the email app or the analytics app. When someone asks "summarize last week's signups," Dispatch calls the analytics agent over A2A and returns the answer. When someone asks "draft a reply to Alice," Dispatch calls the mail agent.
+- **Control-plane shell.** Chats, projects, runs, workspace apps, agents, and automations live in one operational shell, with status-first lists and drill-downs instead of one-off dashboards.
 - **Secrets vault.** A central store for API keys, OAuth tokens, and shared credentials. Apps in the workspace resolve secrets from Dispatch instead of duplicating them in every `.env`. Requests + approvals for sensitive access.
 - **Workspace resources.** Global skills, guardrail instructions, custom agent profiles, reference resources, and HTTP MCP servers can be created once in Dispatch. All-app resources are inherited at runtime by every app with no copy or manual sync step; selected grants are for app-specific exceptions.
 - **Reusable integrations.** One place to connect provider accounts, track
@@ -63,6 +64,9 @@ Day-to-day, Dispatch is the place admins and ops folks open to keep the workspac
   Codex, Cursor, or another MCP host, then choose which workspace apps the
   connector can reach from Dispatch's **Agents** page. Use a direct app URL
   only when that host should be isolated to one app.
+- **Manage automations.** The Automations view shows enabled state, last run,
+  next run, and last error from the underlying `jobs/*.md` schedules, and lets
+  you enable or disable a job without editing files by hand.
 - **Keep company context global.** Put personas, positioning, messaging, company facts, brand guidelines, and guardrails in Dispatch Resources once, then preview the effective workspace -> app/org -> personal stack for any app/user or inspect the stack from an app card's Context view.
 - **Set up recurring jobs.** "Every Monday at 7am, ask the analytics agent for last week's signups and email me a summary." See [Recurring Jobs](/docs/recurring-jobs).
 - **Review dream proposals.** Dispatch Dreams inspect prior agent runs and create source-backed proposals for what the workspace should remember, which stale notes should be cleaned up, and which repeated lessons should become skills or jobs.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.61.0",
+  "version": "0.62.1",
   "type": "module",
   "engines": {
     "node": ">=22"
@@ -46,6 +46,10 @@
       "types": "./dist/action-ui.d.ts",
       "default": "./dist/action-ui.js"
     },
+    "./agent-native": {
+      "types": "./dist/agent-native/index.d.ts",
+      "default": "./dist/agent-native/index.js"
+    },
     "./agent-web": "./dist/agent-web/index.js",
     "./db": "./dist/db/index.js",
     "./db/schema": "./dist/db/schema.js",

package/src/templates/workspace-core/.agents/skills/composable-mini-apps/SKILL.md

@@ -45,6 +45,32 @@ The main agent should discover available siblings before assuming capability:
 Send narrow prompts to siblings: name the exact question, relevant ids, date
 ranges, and expected output shape. Preserve returned ids and URLs verbatim.
 
+## Artifact Handoff
+
+Mini-apps should hand off compact artifacts, not giant pasted transcripts or
+provider dumps. When a mini-app creates something another app may use, return
+or store an artifact with:
+
+- `artifactType` - what kind of output this is, such as `deal-set`,
+  `call-evidence`, `brief`, `dashboard`, or `report`.
+- `artifactId` - the stable app-owned id, file path, or resource id.
+- `createdAt` - an ISO timestamp.
+- `source` - provider/app/source ids used to create it.
+- `summary` - a short human-readable explanation.
+- `items` or `records` - the bounded structured data downstream apps need.
+- `links` - fully qualified URLs for user-visible artifacts.
+
+Downstream apps should receive artifact ids, URLs, and narrow follow-up
+questions. If a downstream app needs more detail, it should call back to the
+artifact-owning app instead of asking the orchestrator to paste the whole
+corpus into a prompt.
+
+Example: `hubspot-pipeline` returns `{ artifactType: "deal-set",
+artifactId: "hubspot-pipeline:deal-set:2026-06-18" }`. `deal-brief` passes
+that id to `gong-evidence`, which returns a `call-evidence` artifact id and
+URLs. `deal-brief` then synthesizes the final brief from the artifact ids and
+bounded summaries.
+
 ## Provider APIs
 
 Provider-specific actions are shortcuts, not limits. When the upstream API can