Add headless agent primitives and composable orchestration (#1304) · rangle/agent-native@ca3efcf · GitHub
Skip to content

Commit ca3efcf

Browse files
steve8708steve8708
authored
Add headless agent primitives and composable orchestration (BuilderIO#1304)
* fix navigation reliability for chat-first apps * fix(org): allow auto-join activation override * fix(org): auto-join matching domains during org resolution * test(org): cover auto-join activation override * test(org): cover domain auto-join during context resolution * chore: add changeset for domain auto-join * fix: address navigation review findings * fix: coordinate notification popover with extension iframe * fix: address navigation review edge cases * fix: address follow-up navigation review * fix: offer org join on plan access wall * feat: add headless agent orchestration primitives * fix: build dispatch packages before qa smokes * fix: ignore resource noise in dispatch automation smoke * fix: expose thread sharing helpers and gate repo writes * test: cover thread share client helpers * docs: tighten action agent loop copy * feat: render shared thread share pages * docs: update cloud repo access capabilities * docs: streamline getting started path * chore: add forms launch target * feat: add chat template on-ramp and local docs lookup * fix: address repo and workspace review feedback
1 parent 15fd8ac commit ca3efcf

320 files changed

Lines changed: 11812 additions & 2271 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.agents/skills/actions/SKILL.md‎

Lines changed: 5 additions & 5 deletions

‎.agents/skills/agent-native-docs/SKILL.md‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
---
2+
name: agent-native-docs
3+
description: >-
4+
How to find version-matched Agent Native framework docs bundled in
5+
node_modules. Use before implementing or answering questions about
6+
@agent-native/core APIs, generated apps, workspaces, or advanced features.
7+
metadata:
8+
internal: true
9+
---
10+
11+
# Agent Native Docs Lookup
12+
13+
## Rule
14+
15+
Before implementing or explaining non-trivial Agent Native behavior, read the
16+
version-matched docs installed with `@agent-native/core`.
17+
18+
## Why
19+
20+
Generated apps and workspaces may be on a different framework version than the
21+
public docs or model memory. The installed package is the source that matches
22+
the app in front of you.
23+
24+
## How
25+
26+
From a generated app directory:
27+
28+
```bash
29+
pnpm action docs-search --query "<feature>"
30+
pnpm action docs-search --slug <slug>
31+
pnpm action docs-search --list
32+
```
33+
34+
The headless `pnpm agent` loop and built-in app agent also expose a read-only
35+
`docs-search` tool with the same `query`, `slug`, and `list` options.
36+
37+
If the action runner is unavailable, search the package docs directly:
38+
39+
```bash
40+
rg -n "actions|automations|a2a|sharing" node_modules/@agent-native/core/docs
41+
```
42+
43+
Then read `node_modules/@agent-native/core/docs/AGENTS.md` or the matching file
44+
under `node_modules/@agent-native/core/docs/content/`.
45+
46+
## Useful Slugs
47+
48+
| Need | Slugs |
49+
| --- | --- |
50+
| Actions and typed client calls | `actions`, `client` |
51+
| SQL, auth, access, sharing | `database`, `authentication`, `security`, `sharing` |
52+
| UI state visible to the agent | `context-awareness` |
53+
| Headless and chat-first apps | `pure-agent-apps`, `agent-surfaces`, `using-your-agent` |
54+
| Automations and schedules | `automations`, `recurring-jobs` |
55+
| Cross-app and external agents | `a2a-protocol`, `external-agents`, `mcp-protocol`, `mcp-apps` |
56+
| Skills and instructions | `skills-guide`, `writing-agent-instructions` |
57+
58+
## Don't
59+
60+
- Do not rely on memory for framework APIs when package docs are present.
61+
- Do not add custom REST wrappers for app data before reading `actions`.
62+
- Do not add inline LLM calls before reading `using-your-agent` and
63+
`agent-surfaces`.

‎.agents/skills/composable-mini-apps/SKILL.md‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
---
2+
name: composable-mini-apps
3+
description: >-
4+
Build many focused workspace apps that compose through agent discovery and
5+
A2A. Use when designing headless mini-apps or cross-app workflows.
6+
---
7+
8+
# Composable Mini-Apps
9+
10+
## Rule
11+
12+
Prefer many one-job apps in a workspace over one oversized app. A headless app
13+
can own a provider, dataset, workflow, or specialist action surface without a
14+
full UI; the main agent composes those apps through discovery and A2A.
15+
16+
## Shape
17+
18+
- Give each mini-app one clear job, a concise `package.json` description, and
19+
action names that describe the job it owns.
20+
- Keep provider credentials and upstream API details in the app that owns that
21+
provider or workflow. Other apps should delegate to it instead of copying its
22+
integration code.
23+
- Use a tiny status/config screen only when users need to inspect state. A
24+
pure headless app is fine when its job is invoked by agents, automations, or
25+
sibling apps.
26+
- If two workflows only share a helper, put the helper in `packages/shared`;
27+
keep the workflow actions in separate apps.
28+
29+
## Discovery And Invocation
30+
31+
The main agent should discover available siblings before assuming capability:
32+
33+
- Runtime agents receive an `<available-apps>` block built from
34+
`discoverAgents()`. Workspace siblings are layered in by
35+
`discoverWorkspaceAgents()`.
36+
- UI shells, headless surfaces, and scripts can read the same registry through
37+
`GET /_agent-native/agents?selfAppId=<app-id>`.
38+
- Code or CLI callers should use the first-class A2A invocation path
39+
(`invokeAgent()` / `agent-native invoke`) when they need to call an app by
40+
id, name, or URL.
41+
- In the agent loop, use `call-agent` with the sibling app id when another app
42+
owns the work or data. Never call the current app through `call-agent`; use
43+
local actions instead.
44+
45+
Send narrow prompts to siblings: name the exact question, relevant ids, date
46+
ranges, and expected output shape. Preserve returned ids and URLs verbatim.
47+
48+
## Provider APIs
49+
50+
Provider-specific actions are shortcuts, not limits. When the upstream API can
51+
answer the question better than a first-class shortcut, call
52+
`provider-api-catalog` and `provider-api-docs` as needed, then
53+
`provider-api-request` against the real provider endpoint. For broad joins,
54+
searches, or absence claims, stage the bounded corpus with `stageAs` and reduce
55+
it with `query-staged-dataset` or code.
56+
57+
When composing apps, make the provider-owning mini-app do those
58+
`provider-api-request` calls. The orchestrator should delegate a bounded job;
59+
it should not reimplement every provider endpoint locally.
60+
61+
## Example
62+
63+
For a sales-intelligence workspace, split the job into small apps:
64+
65+
| App | Owns | Calls |
66+
| --- | --- | --- |
67+
| `hubspot-pipeline` | CRM deals, contacts, companies, associations | `provider-api-request` with provider `hubspot` |
68+
| `gong-evidence` | Calls, transcripts, snippets, speaker evidence | `provider-api-request` with provider `gong` |
69+
| `knowledge-base` | Internal docs, pricing rules, playbooks | local search/read actions |
70+
| `deal-brief` | Orchestration and final brief | `invokeAgent()` or `call-agent` to the three apps |
71+
72+
Flow: `deal-brief` asks `hubspot-pipeline` for the target account and open
73+
deals, asks `gong-evidence` for recent transcript evidence about those deals,
74+
asks `knowledge-base` for relevant playbook guidance, then synthesizes the
75+
answer. That is a HubSpot→Gong→knowledge-base chain made of focused apps,
76+
not a single app that clones every provider integration.
77+
78+
## Don't
79+
80+
- Do not clone Mail, Calendar, Analytics, Brain, Assets, or another first-party
81+
app just to reuse its data. Delegate or link to the existing app.
82+
- Do not hide a multi-provider workflow inside a giant "misc tools" app.
83+
- Do not add one-off provider endpoints when `provider-api-request` can express
84+
the upstream API safely.
85+
- Do not create wrapper routes that only re-export another app's action or A2A
86+
result.
87+
88+
## Related Skills
89+
90+
- **a2a-protocol** - How apps expose and call A2A endpoints.
91+
- **actions** - How each mini-app exposes its own operation surface.
92+
- **external-agents** - How external MCP hosts route through workspace apps.
93+
- **storing-data** - How app-owned data stays SQL-backed and portable.

‎.agents/skills/secrets/SKILL.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -111,7 +111,7 @@ row is written — status is derived from `hasOAuthTokens("google")`.
111111

112112
```ts
113113
import { z } from "zod";
114-
import { defineAction } from "@agent-native/core";
114+
import { defineAction } from "@agent-native/core/action";
115115
import { readAppSecret } from "@agent-native/core/secrets";
116116
import { getRequestUserEmail } from "@agent-native/core/server";
117117

‎.changeset/chat-template-onramp.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
"@agent-native/core": patch
3+
"@agent-native/dispatch": patch
4+
---
5+
6+
Add the Chat template as the public minimal app on-ramp and keep Starter as a legacy CLI alias.

‎.changeset/codex-cli-code-agent.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"@agent-native/core": patch
3+
---
4+
5+
Allow Agent-Native Code to run through the local Codex CLI when Codex is signed in, and update provider copy to mention Codex CLI auth.

‎.changeset/compact-integration-context.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"@agent-native/core": patch
3+
---
4+
5+
Load integration prompt resources in compact mode so Slack, email, and webhook runs do not inline full skill or memory context.

‎.changeset/composable-mini-apps-guidance.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"@agent-native/core": patch
3+
---
4+
5+
Add composable mini-apps guidance to workspace agent instructions and synced workspace-core skills so generated workspaces teach sibling discovery, A2A invocation, and provider-api composition patterns.

‎.changeset/dispatch-automation-controls.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
"@agent-native/core": patch
3+
"@agent-native/dispatch": patch
4+
---
5+
6+
Add Dispatch automation status controls backed by jobs markdown resources.

‎.changeset/fix-chat-queue-followups.md‎

Lines changed: 5 additions & 0 deletions

0 commit comments

Comments
 (0)