@agent-native/core 0.152.0 → 0.153.0

package/dist/templates/workspace-core/.agents/skills/external-agents/references/mcp-apps-embedding.md

@@ -1,157 +0,0 @@
-# MCP Apps Embedding Internals
-
-Deep-dive reference for the optional MCP Apps UI surface — the `mcpApp` action
-field, `embedApp()`, the host bridges (Claude / ChatGPT), embed start tickets,
-extension-page rendering inside chat embeds, and host sizing. For the common
-case (adding a `link` builder, connecting hosts, ingest actions, the
-`/_agent-native/open` route), see `../SKILL.md`. This file is the expansion of
-that skill's "Optional MCP Apps UI" section.
-
-## Optional MCP Apps UI
-
-For hosts that support the MCP Apps extension, an action can also advertise an
-inline UI resource with `mcpApp`. This is a progressive enhancement for flows
-where the external agent should hand the user an interactive surface instead of
-only text — for example reviewing an email draft, editing a calendar invite, or
-choosing between generated dashboard variants.
-
-Use the real React app with `embedApp()` whenever the user needs UI. The mental
-model is simple: the action's `link` target is also the MCP App embed target.
-Expose the operation as a normal action/tool, return a focused deep link with
-`link`, and add `mcpApp.resource = embedApp(...)` so capable hosts load that
-same route inline instead of opening a new tab.
-
-`embedApp()` supports both host bridges. Standard MCP Apps hosts use the
-`ui/*` bridge; ChatGPT uses the `window.openai` compatibility bridge, reading
-`toolInput` / `toolOutput` / `toolResponseMetadata` and calling
-`create_embed_session` through `window.openai.callTool(...)`. Do not build a
-ChatGPT-only HTML surface. Keep the action result and `link` target focused so
-both bridges land on the same real app route.
-
-That means full-app embeds can do anything the route can do once opened:
-review or edit an email draft, show a filtered inbox/search, open a calendar
-event or event draft, load an extension page, inspect a full analytics
-dashboard or saved analysis, continue a deck in the Slides editor, or open a
-Design project/editor. Prefer URL/deep-link params and the existing
-`/_agent-native/open` navigation/app-state bridge over inventing a second
-state protocol for MCP Apps.
-
-On rare occasions the right target is a focused app route that renders one
-shared React component instead of the whole app shell. Analytics' `/chart`
-route is the model: it takes a compact `SqlPanel` payload in the URL and
-renders the same chart component the dashboard uses. This is still an app
-embed, not a plain HTML MCP App. Expose or call it through a normal action /
-`open_app({ path, embed: true })`, keep the URL deterministic, and let
-`embedApp()` render that route inline.
-
-Do not hand-write one-off plain HTML MCP Apps for product UI; if the action
-needs a custom surface, add or reuse a real app route/component first and embed
-that route.
-
-```ts
-import { embedApp } from "@agent-native/core";
-
-export default defineAction({
-  // ...schema, run, link...
-  mcpApp: {
-    resource: embedApp({
-      title: "Review draft",
-      description: "Open the generated draft in the real Mail compose UI.",
-      iframeTitle: "Agent-Native Mail",
-      openLabel: "Open in Mail",
-    }),
-  },
-});
-```
-
-The MCP server advertises extension `io.modelcontextprotocol/ui`, adds
-`_meta.ui.resourceUri` plus the legacy-compatible `_meta["ui/resourceUri"]` to
-`tools/list`, and also emits ChatGPT Apps SDK compatibility metadata
-(`openai/outputTemplate`, widget CSP/description/accessibility). It exposes the
-HTML through `resources/list`, `resources/templates/list`, and `resources/read`
-using MIME `text/html;profile=mcp-app`. The stdio proxy forwards those resource
-handlers from the live app, so local desktop/CLI clients see the same resources
-as HTTP clients.
-
-Keep the existing `link` builder even when adding `mcpApp`. CLI-only clients,
-older hosts, and any host that does not render MCP Apps will ignore the UI
-metadata and still need the "Open in … →" link. `embedApp()` uses that link as
-its launch target. Same-app `open_app({ embed: true })` mints the
-`/_agent-native/embed/start` ticket during the original tool call so production
-hosts do not need the iframe to make a second app-only helper call; custom
-actions can return `embedStartUrl` for the same fast path. The MCP layer keeps
-that ticket-bearing URL in hidden metadata and strips it from model-visible
-structured content and normal open-link metadata. Otherwise the resource falls
-back to the app-only `create_embed_session` helper. The embed start route
-exchanges a one-time SQL ticket, then launches the real app route with a
-short-lived browser session. Standard hosts navigate the MCP App frame
-directly. Claude web uses a single-frame transplant path that fetches the
-signed app HTML and hydrates it inside Claude's MCP App iframe because Claude
-does not reliably allow app-owned child iframes or external frame navigation.
-ChatGPT web uses a controlled route iframe for stable `window.openai` host APIs
-and bounded height control. You can force the
-single-frame transplant path in other hosts with `embedMode: "transplant"` or
-`frame: "transplant"` when debugging host module loading, or force the nested
-diagnostic iframe with `embedMode: "iframe"` /
-`renderMode: "iframe"` / `nested: true` when debugging host behavior. Pass
-additional `frameDomains` only for a custom MCP App that truly embeds a
-third-party frame. `open_app({ app, path, embed: true })` is the generic
-escape hatch for routes like full dashboards, filtered inboxes, calendar
-drafts, analyses, or extension pages, and should be used liberally when the
-full app is the clearest review/edit surface.
-
-Do not set standard `_meta.ui.domain` to an app URL. That field is
-host-specific: Claude validates hash subdomains such as
-`{hash}.claudemcpcontent.com`, while ChatGPT has its own widget-domain
-metadata. Let hosts choose their default sandbox origin unless you are emitting
-a host-specific value on purpose. `embedApp()` may still emit
-`openai/widgetDomain` for ChatGPT compatibility.
-
-Extension pages are a special case inside MCP chat embeds. The normal app uses
-`/_agent-native/extensions/:id/render` as a sandboxed child iframe, but MCP
-chat hosts add another ancestor frame and can block that route via
-`frame-ancestors` / `X-Frame-Options`. In MCP chat bridge mode the framework
-renders the extension document as sandboxed `srcDoc` inside the existing app
-route iframe instead; keep `sandbox="allow-scripts allow-forms"` and do not add
-`allow-same-origin`.
-
-For Dispatch, keep the single connector path first-class: the `open_app`
-resource CSP should include the exact origins of apps granted through Dispatch,
-not broad sources like `https:`. This lets Claude's transplant path fetch the
-signed target app HTML while keeping the connector's resource surface narrow.
-
-Host sizing rule: the MCP resource shell owns a bounded inline height and the
-embedded route should scroll internally. `embedApp({ height })` defaults to a
-`560px` shell, clamps to `320-900px`, and subtracts `44px` for the wrapper bar
-before sizing the route viewport. Do not re-enable host SDK auto-resize for
-full-app route embeds; Claude and ChatGPT can otherwise measure the whole
-document and create a huge chat iframe. After changing the shell or `ui://`
-resource version, verify with a fresh tool call because old conversation frames
-keep the behavior they were rendered with.
-
-Inside embedded routes, `sendToAgentChat({ submit: true })` posts
-`agentNative.submitChat`; MCP App hosts receive that as model context plus a
-visible `ui/message` turn, so an inline preview can intentionally continue the
-Claude/ChatGPT conversation. Hidden context stays in model context; do not put
-internal app-state file instructions into the visible prompt. `submit: false`
-stays local as a prefill/review path.
-
-When testing Claude through ngrok, use a production build (`pnpm exec agent-native build`
-then `pnpm exec agent-native start`) or a deployed preview/production URL. Claude's
-transplant path works with production asset chunks; raw Vite dev modules such
-as `/app/root.tsx` can be app-auth protected and fail dynamic imports from the
-Claude resource origin.
-
-For known first-party handoffs, prefer a direct action with `mcpApp` over
-letting the model hunt through screens. Examples: Mail `manage-draft` for email
-drafts, Analytics `open-traffic-dashboard` for the first-party traffic
-dashboard, Calendar `manage-event-draft` for invite drafts, and create/search
-actions for Forms, Content, Clips, Slides, and Design. The action should return
-concise structured content plus the link; it should not dump large catalogs or
-HTML.
-
-Compatibility target: build to the standard once, not per-client shims. MCP
-Apps-capable hosts should include Claude/Claude Desktop/Claude Code, ChatGPT
-custom MCP apps, VS Code GitHub Copilot, Goose, Postman, MCPJam, Cursor, and
-any future host that follows the extension negotiation. Host support varies by
-plan, release channel, and client version, so keep the deep link fallback.

package/dist/templates/workspace-core/.agents/skills/feature-flags/SKILL.md

@@ -1,169 +0,0 @@
----
-name: feature-flags
-description: >-
-  Declare, evaluate, manage, and remove framework feature flags. Use when
-  shipping a capability gradually, targeting users or organizations, or
-  replacing a compile-time rollout switch with a production-safe runtime flag.
-scope: dev
-metadata:
-  internal: true
----
-
-# Feature Flags
-
-A feature flag is a boolean declared in app code, evaluated locally by Core,
-and managed from the Analytics fleet control plane. Code owns whether a flag
-exists. Runtime settings own only its rollout state.
-
-Flags let an app deploy dormant code and turn it on in the real environment
-without another deployment. They are not experiments: do not add variants,
-hypotheses, conversion metrics, exposure tracking, or lifecycle states.
-
-## When to use one
-
-Use a flag for a reversible rollout of a user-facing capability whose dormant
-code is safe to deploy. Flags are useful for production dogfooding, exact-user
-or organization pilots, and deterministic percentage rollouts.
-
-Do not use a flag for authentication, authorization, secrets, audit enablement,
-SSR cache behavior, or another security boundary. Client hiding is presentation
-only; every guarded server action must evaluate the same registered flag.
-
-## Agent workflow
-
-### 1. Declare
-
-Keep definitions in a shared TypeScript module so server and client code use the
-same stable key. Flags are boolean and default-off.
-
-```ts
-import { defineFeatureFlag } from "@agent-native/core/feature-flags/registry";
-
-export const FULL_APP_BUILDING = defineFeatureFlag({
-  key: "full-app-building",
-  displayName: "Full app building",
-  description: "Create and edit Fusion-backed applications.",
-});
-```
-
-Keys are immutable, never reused, and contain only letters, numbers, dots,
-underscores, or hyphens. Prefer a concise app-owned name. Do not create flag
-definitions or rollout rows from Analytics.
-
-### 2. Register
-
-Register app definitions from a Nitro plugin before actions are discovered.
-Do not add app-specific flags to a Core registry.
-
-```ts
-import { createFeatureFlagsPlugin } from "@agent-native/core/server";
-
-import { FULL_APP_BUILDING } from "../../shared/feature-flags.js";
-
-export default createFeatureFlagsPlugin({ flags: [FULL_APP_BUILDING] });
-```
-
-### 3. Guard server and client
-
-The server action is the enforcement boundary:
-
-```ts
-import { isFeatureFlagEnabled } from "@agent-native/core/feature-flags";
-
-run: async (args, ctx) => {
-  if (!(await isFeatureFlagEnabled(FULL_APP_BUILDING, ctx))) {
-    throw new Error("Full app building is not enabled for this account.");
-  }
-  // guarded operation
-}
-```
-
-Use the client hook only to hide or reveal hydrated UI:
-
-```tsx
-import { useFeatureFlag } from "@agent-native/core/client/feature-flags";
-
-const enabled = useFeatureFlag(FULL_APP_BUILDING.key);
-return enabled ? <FullAppOption /> : null;
-```
-
-The client hook intentionally returns false while loading or for an unknown
-flag. Never replace that fail-closed behavior with app-local bucketing or a
-compile-time fallback. Never evaluate personalized flags in the public SSR
-shell; it is shared and cached for every visitor.
-
-### 4. Verify and roll out
-
-1. Verify the off path before changing rollout state.
-2. Confirm the registered flag appears in **Analytics → Feature flags** for the
-   app and is Off by default.
-3. Use **Enable for me** for initial production dogfood.
-4. Expand to exact emails, organization IDs, or a percentage only from
-   Analytics.
-5. Confirm the client presentation and authoritative server action agree.
-
-## Management contract
-
-Core mounts three actions in registered apps:
-
-| Action | Purpose |
-| --- | --- |
-| `get-feature-flags` | Return the current caller's evaluated boolean values. |
-| `list-feature-flags` | Return definitions and rollout metadata to an authorized operator. |
-| `set-feature-flag` | Atomically turn a flag off, enable it for the operator, or replace targeting rules. |
-
-Analytics calls the app-local operator actions through narrowly scoped A2A
-delegation. Tokens require an exact audience, organization, scope, operator
-role, and audit correlation id. Management is permission-checked and audited
-by the target app. Never manage flags through generic settings routes, raw SQL,
-or per-app toggle UIs.
-
-## Rollout semantics
-
-The operator modes are **Off**, **Targeted**, and **Everyone**. Core stores them
-as `off`, `rules`, and `on`.
-
-Targeted rules combine exact normalized emails, exact organization IDs, and a
-percentage with OR semantics. Exact matches are checked first. Percentage
-buckets use Core's stable hash of the flag key and authenticated user identity;
-anonymous callers fail closed. Raising a percentage preserves the users already
-included at a lower percentage. Do not implement bucketing in app code.
-
-Unknown definitions, missing state, malformed state, storage errors, and
-evaluation errors all return the code default (`false` in v1). Explicit Off
-wins over every target; Everyone enables every authenticated caller.
-
-## Remove a flag
-
-After a rollout is permanent:
-
-1. Replace guarded branches with the chosen behavior.
-2. Delete the server and client gates.
-3. Delete the definition and registration entry.
-4. Verify the flag disappears from the Analytics fleet.
-5. Remove stale tests and rollout instructions.
-
-A permanent flag is just an if statement with a pension plan.
-
-## Verification checklist
-
-- Unknown and unregistered keys evaluate false.
-- UI hiding and server enforcement use the same registered key.
-- Exact-user, organization, deterministic percentage, Everyone, and Off paths
-  have focused tests.
-- Increasing a percentage is monotonic; anonymous percentage evaluation is off.
-- Unauthorized callers cannot list targeting details or mutate flags.
-- Mutations are atomic, read back stored state, emit refresh, and appear in the
-  audit log with the flag key.
-- Analytics represents ready, no-definition, unsupported, forbidden, legacy,
-  and unreachable directory apps honestly.
-- Future agents can find this skill from root `AGENTS.md`, and
-  `pnpm guard:workspace-skills` passes after syncing generated copies.
-
-## Related skills
-
-- **adding-a-feature** — preserve UI/action/instruction/application-state parity
-- **actions** — define and call guarded app operations
-- **audit-log** — inspect automatic action mutation history
-- **reliable-mutations** — make rollout changes atomic and provable
-- **security** — keep security controls out of feature flags

package/dist/templates/workspace-core/.agents/skills/generative-ui/SKILL.md

@@ -1,117 +0,0 @@
----
-name: generative-ui
-description: >-
-  Generate transient or saved inline chat UI with Alpine/Tailwind controls,
-  outputs, app state, and extensions. Use for knobs, pickers, calculators,
-  dashboards, widgets, or reusable mini-apps.
----
-
-# Generative UI
-
-Generative UI is sandboxed Alpine.js HTML rendered inline in chat. It is not a
-source-code change and does not go through Builder.
-
-## Pick the Lifetime
-
-- Use `render-inline-extension` for one-off UI that belongs only in the current
-  chat: knobs, controls, pickers, calculators, temporary charts, and previews.
-- Use `create-extension` when the UI should be saved, reusable, or visible in
-  the Extensions view. It also renders inline after creation.
-- Use `show-extension-inline` to reopen a saved extension inside chat.
-- Use `update-extension` to edit an existing saved extension.
-
-## Inputs From Chat
-
-Pass initial values through the action `context` argument. The iframe reads them
-from `window.slotContext` and can subscribe to changes with
-`window.onSlotContext(fn)`.
-
-```html
-<script>
-  Alpine.data("controls", () => ({
-    threshold: 50,
-    init() {
-      this.threshold = Number(window.slotContext?.threshold ?? 50);
-      window.onSlotContext?.((ctx) => {
-        if (ctx.threshold !== undefined) {
-          this.threshold = Number(ctx.threshold);
-        }
-      });
-    },
-  }));
-</script>
-```
-
-## Outputs To The Agent
-
-Use passive output when a control's current value should be visible to the agent
-on the next turn without requiring a submit click:
-
-```html
-<input
-  type="range"
-  min="0"
-  max="100"
-  x-model.number="threshold"
-  @input="agentNative.ui.output({ threshold }, { label: 'Threshold' })"
-/>
-```
-
-`agentNative.ui.output(value, opts?)` writes application state at:
-
-```txt
-inline-ui:<extensionId>:output
-```
-
-The id is scoped automatically; the HTML author must not pass it. When the user
-says "use that value", "apply the current setting", or "run it with the current
-selection", read the value with:
-
-```ts
-const output = await readAppState("inline-ui:<id>:output");
-```
-
-The stored payload includes `value`, `updatedAt`, `extensionId`, and
-`source: "inline-ui"`, plus optional `label`, `context`, or `meta`.
-
-Use `agentNative.chat.send(message, opts?)` or `sendToAgentChat(message, opts?)`
-for a visible Apply/Submit button that should send a prompt or selected value
-into the chat. Pass `{ submit: true }` explicitly for that user-triggered
-action; extension messages are draft-only otherwise. Never call these helpers
-from polling, refresh, or error handlers.
-
-## App Data And State
-
-- Prefer `appAction(name, params)` for template data and operations.
-- Use `appFetch(path, options)` only for allowed framework endpoints under
-  `/_agent-native/*`, including application-state reads and writes.
-- Do not call template `/api/*` routes from generated UI.
-- Use `dbQuery`/`dbExec` only for known existing SQL tables when no action fits.
-- Use `extensionFetch` for external APIs through the sandbox proxy and secrets.
-
-## Transient extensionData Boundary
-
-For saved extensions, `extensionData` uses the authenticated database-backed
-extension data API.
-
-For transient inline UIs, `extensionData` is host `localStorage`. The agent
-cannot read it, it does not sync across devices, it does not migrate when a UI
-is promoted to a saved Extension, and the server does not garbage-collect it.
-Use it only for throwaway local UI state.
-
-For anything the agent or app must observe, use `agentNative.ui.output`,
-application state through `appFetch`, an `appAction`, or
-`agentNative.chat.send`.
-
-## Styling
-
-Use semantic Tailwind classes so the iframe inherits the parent app theme:
-
-- `bg-background`, `text-foreground`, `border-border`
-- `bg-card`, `text-card-foreground`
-- `bg-primary`, `text-primary-foreground`
-- `text-muted-foreground`, `bg-accent`
-
-Do not hardcode provider tokens, private data, or internal secrets in generated
-HTML. Do not call an LLM directly from the iframe; route AI work through the
-agent chat.

package/dist/templates/workspace-core/.agents/skills/harness-agents/SKILL.md

@@ -1,170 +0,0 @@
----
-name: harness-agents
-description: >-
-  Add or use full agent harness runtimes like Claude Code, Codex, Pi, Cursor, Mastra, or ACP agents inside Agent Native.
-scope: dev
----
-
-# Harness Agents
-
-## Rule
-
-Full agent harnesses are not `AgentEngine` providers. Use the `AgentHarness`
-substrate in `@agent-native/core/agent/harness`.
-
-## Why
-
-`AgentEngine` is for one model round trip beneath `runAgentLoop`. Harnesses like
-Claude Code, Codex, Pi, Cursor, and Mastra own their own loop, workspace,
-native tools, session state, compaction, approval model, and sandbox behavior.
-Putting a harness under `AgentEngine.stream()` double-runs the loop and loses
-session lifecycle semantics.
-
-## How
-
-1. Register or resolve a harness adapter.
-
-```ts
-import {
-  registerBuiltinAgentHarnesses,
-  resolveAgentHarness,
-} from "@agent-native/core/agent/harness";
-
-registerBuiltinAgentHarnesses();
-const harness = resolveAgentHarness("ai-sdk-harness:codex");
-```
-
-2. Start a turn through the run-manager bridge.
-
-```ts
-import { startAgentHarnessRun } from "@agent-native/core/agent/harness";
-
-startAgentHarnessRun({
-  runId,
-  threadId,
-  adapter: harness,
-  input: { prompt },
-  createSession: {
-    sessionId,
-    resumeState,
-    instructions,
-    sandbox,
-    permissionMode: "allow-reads",
-  },
-  ownerEmail,
-  orgId,
-});
-```
-
-3. Persist native session state in SQL.
-
-Use `saveAgentHarnessSession`, `updateAgentHarnessSession`, and
-`getLatestAgentHarnessSessionForThread`. The `resumeState` is opaque; Agent
-Native stores it but does not inspect it.
-
-4. Surface runs through background agents.
-
-Harness runs are projected into the shared `BackgroundAgentRun` shape with
-`createAgentHarnessBackgroundAgentController()` and are available through the
-existing run routes as `goalId=agent-harness`.
-
-## ACP Agents
-
-Agent Native can act as an [ACP](https://agentclientprotocol.com) (Agent Client
-Protocol) client and drive a local coding agent — Gemini CLI, Claude Code, or
-any ACP-compliant agent — through this same substrate. This is scoped to **local
-coding**: the agent is spawned as a child process speaking newline-delimited
-JSON-RPC over stdio, and inherits the parent environment so it reuses the user's
-local CLI login. It is not a hosted/sandboxed transport, and it is not a
-chat/A2A transport.
-
-```ts
-import {
-  registerBuiltinAgentHarnesses,
-  resolveAgentHarness,
-} from "@agent-native/core/agent/harness";
-
-registerBuiltinAgentHarnesses();
-
-// Built-in presets (commands overridable via the resolve config):
-const gemini = resolveAgentHarness("acp:gemini");
-const claude = resolveAgentHarness("acp:claude-code");
-
-// Or any ACP agent by command:
-const custom = resolveAgentHarness("acp", {
-  command: "gemini",
-  args: ["--experimental-acp"],
-});
-```
-
-- The protocol transport (`@zed-industries/agent-client-protocol`) is an optional
-  dependency loaded lazily; `installPackage` surfaces a clear install hint.
-- The agent binary (e.g. `@google/gemini-cli`, `@zed-industries/claude-code-acp`)
-  is a separate external CLI the user installs; presets launch it through `npx`
-  by default and the command/args are overridable because agent ACP entry flags
-  still evolve.
-- `permissionMode` maps onto ACP `session/request_permission` using the reported
-  tool-call kind: reads always run, edits run under `allow-edits`, everything
-  risky prompts unless `allow-all`. Approvals surface as `approval-request`
-  events; answer them through the harness session's `approve()`.
-- `resumeState` carries the ACP `sessionId`; resume works when the agent
-  advertises the `loadSession` capability and degrades to a fresh session
-  otherwise.
-- `fs/read_text_file` and `fs/write_text_file` are served against the session
-  workspace and refuse paths that escape it; terminal methods are not advertised
-  (the agent uses its own shell).
-
-## Adapter Guidance
-
-- Keep harness packages optional. Use dynamic imports in adapters and expose an
-  install hint through `installPackage`.
-- Use the AI SDK harness adapter as one implementation, not as Agent Native's
-  public abstraction.
-- For bridge-backed coding harnesses, require a real sandbox/workspace provider.
-  Do not run arbitrary coding agents in the host process by default.
-- Pass only a narrow, intentional set of Agent Native actions as host tools.
-  Preserve `defineAction` auth, request context, timeouts, truncation, and
-  read-only metadata.
-
-## Code Execution Sandbox
-
-- The `run-code` tool executes through a pluggable `SandboxAdapter`
-  (`packages/core/src/coding-tools/sandbox/`). The default
-  `LocalChildProcessAdapter` spawns a locked-down local Node child process;
-  swap it via `AGENT_NATIVE_SANDBOX` or `registerSandboxAdapter()` for a
-  Docker/remote backend. An adapter only runs the already-prepared, non-secret
-  module source — it never sees app secrets. See the Sandbox Adapters doc;
-  `agent-native add sandbox docker` emits a full Docker-adapter recipe.
-- Long compute exceeds the hosted ~40s run ceiling via the built-in durable
-  background backend: per-call `background: true` on `run-code` (or
-  `AGENT_NATIVE_SANDBOX=background` to queue every call) enqueues to the
-  `sandbox_executions` table and executes out-of-band — self-dispatched to
-  `/_agent-native/sandbox/_process-execution` on serverless, in-process on
-  long-lived Node — with lease-based claiming, retries, and owner-scoped
-  polling via `run-code {executionId}` / `get-code-execution`.
-
-## Sub-Agent Delegation Depth
-
-- Sub-agent spawning is capped server-side (default depth `2`) so delegation
-  chains can't fan out indefinitely. Override at deploy time with
-  `AGENT_NATIVE_MAX_SUBAGENT_DEPTH` (`0` disables sub-agents; clamped to `16`).
-  Enforcement is ambient via `evaluateSubagentDepth` in
-  `packages/core/src/server/agent-teams.ts` — independent of any tool-level
-  guard. See the Agent Teams doc for the depth model.
-
-## Don't
-
-- Don't add Claude Code, Codex, Cursor, Mastra, or Pi as an `AgentEngine`.
-- Don't replay full Agent Native chat history into a native harness each turn.
-  Resume the harness session instead.
-- Don't store resume state in `application_state`; it belongs in the harness
-  session SQL table.
-- Don't expose every app action to every harness session by default.
-
-## Related Skills
-
-- `adding-a-feature` — feature parity across UI/actions/instructions/state.
-- `delegate-to-agent` — background agents use run-manager infrastructure.
-- `external-agents` — expose openable resources and external-agent surfaces.
-- `storing-data` — durable SQL state and additive schema changes.
-