AIP-53: APP (app/v1): agent app bundle + UI surface
A markdown + frontmatter format for bundling one or more AIP-42 agents with the AIP-15 workflows they run, plus an optional static UI surface, into one shippable unit — `.agentproto/APP.md` on disk, `.agentapp` as a packaged, checksummed distributable. Defines the emitted bundle layout, the `window.McpApp` bridge contract a UI surface consumes, the tools-allowlist enforcement a host applies to UI-originated calls, and the three runtime modes (host / bridge / standalone) a UI's client library resolves between.
| Field | Value |
|---|---|
| AIP | 53 |
| Title | APP (app/v1): agent app bundle + UI surface |
| Status | Review |
| Type | Schema |
| Domain | apps.sh |
| Requires | AIP-14 (TOOL), AIP-15 (WORKFLOW), AIP-34 (WORKSPACE), AIP-42 (AGENT), AIP-73 (TUNNEL, for exposed services) |
| Resources | ./resources/aip-53 — ADAPTER.md, APP.schema.json |
| Reference Impl | @agentproto/app |
Abstract
app/v1 names and fixes the contract for an app: the smallest
shippable unit that couples one or more AGENT.md (AIP-42)
agents with the WORKFLOW.md (AIP-15) workflows they run,
optionally alongside a static UI surface, into a single bundle a host can
install, run, and expose. On disk an app is a directory carrying
.agentproto/APP.md — a root index manifest listing every agent/workflow
ref the app bundles — plus the referenced AGENT.md / WORKFLOW.md
files themselves and, when the app ships one, a ui/ static surface.
Packaged for distribution, an app becomes a single .agentapp file: a
tar.gz with a manifest.json carrying an aggregate SHA-256 over every
bundled file's contents.
This AIP also fixes the UI surface contract: the static-file layout
under .agentproto/ui/, the window.McpApp bridge object a host injects
so the UI can call tools, the tools allowlist a host enforces against
every UI-originated call, and the three runtime modes (host, bridge,
standalone) a UI's client library resolves between so the same
index.html runs unmodified whether embedded in an MCP-Apps panel,
served standalone by the reference CLI, or opened bare with no daemon at
all.
Motivation
Before this AIP, "an agent that does something end-to-end and shows you the result" had no canonical shape. Three things existed in isolation:
-
Agents and workflows composed only by convention. AGENT.md (AIP-42) declares a
workflows[]ref list and WORKFLOW.md (AIP-15) declareskind: agentsteps that ref an agent back — but nothing validated that the two sides of that reference actually resolved against each other inside one shipped bundle. A workflow could reference an agent the bundle never included; an agent could list a workflow nobody shipped. -
No shippable unit. A multi-agent capability (search jobs, tailor a CV, hand back a dossier) lived as a scatter of files a host had to assemble by hand — there was no single directory a host could point
installat and get a validated, runnable whole. -
UI surfaces had no bridge contract. Several daemon-side app UIs shipped ad hoc (
packages/runtime/src/*-app.tsin the reference implementation: session panels, a terminal panel, an agents overview) each hand-wiring its own way of calling back into the daemon. Nothing named the shape of that callback object, so every UI reinventedwindow.McpApp-equivalent plumbing, and nothing enforced which tools a given UI was allowed to call — an embedded HTML surface had the same reach as the agent that installed it. -
No portable package format. Handing an app to another host or another machine meant copying a directory by hand, with no integrity check and no metadata describing what was inside.
app/v1 fixes all four: the attachment invariant (agents and
workflows must reference each other, checked at bundle-definition time),
the bundle layout (.agentproto/agents/<id>/AGENT.md,
.agentproto/workflows/<id>/WORKFLOW.md, .agentproto/ui/, plus
optional .agentproto/artifact/ and .agentproto/skill/ surfaces), the
.agentapp package format (a checksummed, portable single file), and
the UI bridge contract (window.McpApp, the tools allowlist, the
three runtime modes). It composes AIP-42 and AIP-15 rather than
replacing either — an app is a cross-linked collection of already-valid
agent and workflow handles, not a new agent or workflow primitive.
Design principles
-
Bundle, don't redefine. An app's agents and workflows are ordinary
defineAgent/defineWorkflowhandles.defineAppadds exactly one new invariant — that the two sides reference each other — and otherwise carries the handles through unchanged. Field-level validation is AIP-42's and AIP-15's job, not this AIP's. -
The attachment invariant is bidirectional. Every agent's
workflows[]ref MUST resolve to a workflow the app bundles, and every bundled workflow MUST be referenced by at least one agent'sworkflows[]. A dangling ref and an orphaned workflow are both errors — "attached" means checkable both ways, not merely "shipped in the same folder." -
An agentproto-owned base, not a shared namespace. Emitted manifests live under
.agentproto/, never under the bare.agents/convention AGENT.md (AIP-42) uses for standalone agents. An app's agents don't squat the shared collection root a workspace's own hand-authored agents live in. -
The UI is a static surface, not a server.
ui.htmlis a single documentemitwrites verbatim to.agentproto/ui/index.html. There is no build step in the contract itself — a hand-written single-file UI is first-class. Aui/source project (Vite, TypeScript) that builds into.agentproto/ui/is a separate, optional convention (see Theui/source-project convention), not a requirement. -
Every UI call is allowlisted, never ambient. A UI surface never gets the reach of the agent that installed the app. Every tool a UI may call is named explicitly in
ui.tools[]at author time; a host MUST reject any call to a tool id absent from that list before dispatch, regardless of what the UI's JavaScript asks for. -
The bridge degrades gracefully, never silently wrong. A UI's client library resolves, in order, to
hostmode (an injectedwindow.McpApp),bridgemode (a same-origin dev-proxy route), orstandalonemode (caller-supplied mock handlers) — and never throws merely because no host is present. It only rejects when a present bridge itself fails, which is a real error rather than an absent one. -
Packaging is verifiable, not just portable. A
.agentappcarries an aggregate SHA-256 over every bundled file's contents, computed in a fixed sorted order. Unpacking recomputes and compares before trusting the contents — a corrupted or tampered bundle is refused, not silently installed.
Specification
File location
An app directory is any directory containing a valid .agentproto/APP.md:
job-application-kit/
.agentproto/
APP.md ← this AIP — root index, always present
agents/
job-scout/AGENT.md ← AIP-42, one per bundled agent
job-tailor/AGENT.md
workflows/
job-hunt/WORKFLOW.md ← AIP-15, one per bundled workflow
ui/
index.html ← optional — the UI surface (this AIP)
base-cv.json ← app-specific data, outside .agentproto/
dossiers/…When the app has a home WORKSPACE (AIP-34), its root
manifest is written as a sibling of .agentproto/:
<dir>/WORKSPACE.md ← AIP-34, only when the app declares `workspace`
<dir>/.agentproto/…Authors do not hand-author this layout directly in the common case — it
is what defineApp({...}).emit(dir) writes (see
Emitted layout). Hand-editing an emitted APP.md (or
its referenced AGENT.md / WORKFLOW.md files) is legal as long as the
result still round-trips through the frontmatter shape below and the
attachment invariant.
The defineApp standard signature
defineApp(definition: AppDefinition): AppHandle
interface AppDefinition {
agents?: (AgentEntry | AgentHandle)[] // REQUIRED (non-empty) UNLESS `ui` is present
workflows?: WorkflowHandle[]
attach?: DoctypeHandle[] // any other AIP handle to carry along
workspace?: WorkspaceHandle | WorkspaceShorthand
id?: string // machine id — absent = anonymous bundle
name?: string
version?: string // default "0.1.0" when `id` is set
description?: string // becomes the APP.md body
requires?: AppRequires // host needs and app dependencies, see "Requirements"
ui?: AppUiDefinition
artifact?: AppArtifactSurface
skill?: AppSkillSurface
artifacts?: AppArtifactDecl[]
dev?: AppDevDefinition
data?: AppDataDefinition // default data-dir hint for the app_data_* plane
category?: string // coarse grouping surfaced in catalogs/trees
setup?: AppSetupStep[] // post-install configuration pipeline — see "Setup steps"
services?: AppService[] // long-running processes the host starts with the app, see "Services"
exposes?: AppExposes // agents, workflows, MCP tools and ui:// views offered outside the app, see "Exposed tools and resources"
}
interface AgentEntry {
agent: AgentHandle // an AIP-42 defineAgent() handle
body?: string // the AGENT.md body / system prompt (composed if absent)
}
/**
* Where the app's durable data lives (the `app_data_*` plane — see
* [The app data plane](#the-app-data-plane-app_data_)). `dir` is a path
* RELATIVE to the app dir — `"data"` means `<appDir>/data`, which is also
* what a host uses when the hint is absent. It is a hint: an explicit
* `dataDir` passed at install time overrides it, and the resolved absolute
* path is persisted on the installed-app record.
*/
interface AppDataDefinition {
dir?: string
}
/**
* One long-running process the host starts with the app (see
* [Services](#services-services)). Exactly one of `command` / `entry`.
*/
interface AppService {
name: string // kebab-case slug, unique within the app
command?: string // structured form: argv[0], no shell
args?: string[] // structured form only: argv after `command`
entry?: string // legacy form: a shell command line, run as `sh -c`
cwd?: string // relative to the installed app dir; default the app dir
port?: number // 1..65535; bookkeeping, or the port the host owns when activation is on-demand
expose?: { auth?: "guard" | "service"; hostname?: string } // a public URL, see "Exposure"
activation?: { // when the host runs the process, see "Activation"
mode: "always" | "on-demand"
idleStopMs?: number
startTimeoutMs?: number
}
}
/**
* What the app offers to callers outside it (see
* [Exposed tools and resources](#exposed-tools-and-resources)).
*/
interface AppExposes {
agents?: string[] // ids of the app's own agents
workflows?: string[] // ids of the app's own workflows
prefix?: string // ^[a-z][a-z0-9]{1,15}$, required when `tools` is non-empty
tools?: AppExposedTool[]
resources?: string[] // distinct ui:// URIs, needs an `imported:` tool
}
interface AppExposedTool {
id: string // a bundled TOOL.md id, or imported:<alias>/<tool>
access: "read" | "write" | "approve"
description: string // non-blank, at most 300 characters
inputSchema?: Record<string, unknown>
mcpName?: string // required for an imported id
approvalArg?: string // only with access: "approve"
}
interface AppUiDefinition {
html: string // the full document — required
title?: string
description?: string
tools?: string[] // the ui_tool_call allowlist
port?: number // preferred local port hint for `app serve`
csp?: {
connectDomains?: string[]
resourceDomains?: string[]
}
}agents MUST be a non-empty array UNLESS ui is present, in which case
it MAY be empty or omitted entirely — a UI-only app ships a ui
block and no agent behaviour, and is a first-class conforming app (this
codifies packages/app/src/define-app.ts:60-64's shipped UI-only
carve-out, pinned by define-app.test.ts's "UI-only apps (zero
agents)" suite, and matches the five daemon builtin panels —
sessions-panel, agents-overview, bureau-sessions, session-story,
live-session — that ship as agents: [] in
packages/apps/src/index.ts:14-20). Each entry is either a bare
AgentHandle (no body — the prompt composes from the agent's structured
fields) or an AgentEntry pairing the handle with the body string that
becomes its AGENT.md's body (its system prompt) — AIP-42
frontmatter is .strict() and carries no systemPrompt field, so the
free-text prompt only ever lives in an AGENT.md body.
workflows, attach, ui, artifact, skill, artifacts, dev,
data, category, setup, services, exposes, requires, and workspace are all optional. An app with agents
and nothing else is still a conforming app, as is a UI-only app with an
empty agents array.
data, when set, is the default data-dir hint for the app_data_*
plane (see The app data plane) — a
string path relative to the app dir; it MUST be non-empty when present.
category is a freeform, non-empty-when-present coarse grouping label
(e.g. "book") surfaced in host catalogs and trees; hosts MUST NOT
validate it against a fixed enum, so new categories can appear without a
schema release. Both are carried verbatim into APP.md frontmatter by
emit and back by loadAppHandle.
Conformance rules
-
Non-empty agents, unless
ui.agentsMUST contain at least one entry UNLESSuiis present. A UI-only app — auiblock with an empty or omittedagentsarray — is conforming. An app with zero agents AND nouiblock is not a conformingAppDefinition—defineAppMUST refuse it. This rule codifies shipped behaviour:packages/app/src/define-app.ts:60-64accepts(agents empty || omitted) && ui === undefinedas the only rejection case, its test suite pins UI-only apps as expected behaviour (packages/app/src/__tests__/define-app.test.ts, "UI-only apps (zero agents)"), and the five daemon builtin panels (packages/apps/src/index.ts:14-20) ship exactly that way. -
Unique agent ids, unique workflow ids. Two bundled agents MUST NOT share an
id; two bundled workflows MUST NOT share anid.defineAppMUST refuse a definition that violates either. -
The attachment invariant, both directions. For every agent in the bundle, every ref in that agent's
workflows[]MUST resolve to theidof a workflow the same app bundles. For every workflow the app bundles, at least one agent'sworkflows[]MUST reference it.defineAppMUST refuse a definition violating either direction — a dangling ref (agent → unbundled workflow) or an orphan (bundled workflow → no referencing agent) are both non-conforming. For a UI-only app (rule 1) the check is trivially satisfied: no agents reference anything and no workflows may be bundled alongside them (a workflow with no referencing agent would be an orphan), so a conforming UI-only app bundles zero workflows. -
idnon-empty when present.idMUST be a non-empty string when set. Settingidis what makes the app installable/discoverable —emitwrites it intoAPP.md's identity block, and a host's install path (app_install) refuses a handle with noid. An app MAY omitidand remain a valid, emittable, runnable-in-process bundle; it simply cannot be installed by id. -
ui.htmlnon-empty whenuiis present.defineAppMUST refuse auiblock whosehtmlis missing or empty. -
dev.launchnon-empty whendevis present. Same shape of rule for the optional dev-launch config. -
artifact.path/skill.pathnon-empty when present, and both MUST be absolute filesystem paths —emitcopies from them at write time and a relative path has no defined base to resolve against. -
Version default. When
idis set andversionis omitted,defineAppMUST defaultversionto"0.1.0". An anonymous bundle (noid) carries no default version. -
No I/O at
defineApptime. Constructing anAppHandleviadefineAppMUST NOT perform filesystem or network I/O. I/O is confined toemit(dir)(write) andloadAppHandle(dir)(read) — the mirror pair every doctype in the AIP series keeps separate from its puredefineXconstructor. -
setupstep ids unique, references backward. Whensetupis present it MUST be non-empty, every stepidMUST be unique within it, and everywhen.stepMUST name a step declared EARLIER in the array.defineAppMUST refuse a definition that violates any of these, and MUST refuse achoicewhosedefaultis not thevalueof one of itsoptions, a step with more than onepersistslot, and apersist.answeron atype: secretprompt. Like rule 9, validatingsetupperforms no I/O: nothing insetupis executed or contacted until a host's install path runs it (see Setup steps). -
servicesnon-empty, names unique, one launch form each. Whenservicesis present it MUST be non-empty and everynameMUST be unique within it. Each entry MUST declare exactly one ofentryandcommand;argsMUST NOT be set alongsideentry. An entry that setsexposeMUST setport, andexposeMUST carry onlyauth(guardorservice) andhostname. An entry that setsactivationMUST give it amodeofalwaysoron-demand;mode: on-demandMUST come with aport, andidleStopMsandstartTimeoutMsMUST NOT be set withmode: always(see Activation for their bounds).defineAppand the loader MUST refuse a definition that violates any of these. Like rules 9 and 10, validatingservicesperforms no I/O: nothing inservicesis executed or contacted until a host's install path starts it (see Services). -
exposesis closed and checked at load. Whenexposesis present it MUST be an object with no key besidesagents,workflows,prefix,toolsandresources. Everyagentsandworkflowsentry MUST name an agent, respectively a workflow, the app declares. A non-emptytoolsMUST come with aprefixmatching^[a-z][a-z0-9]{1,15}$. Each entry oftoolsMUST have a uniqueid, anaccessofread,writeorapprove, a non-blankdescriptionof at most 300 characters, and no key besidesid,access,description,inputSchema,mcpNameandapprovalArg;approvalArgMUST NOT be set unlessaccessisapprove; noidormcpNamemay start withapproval; animported:id MUST have anmcpNameandaccess: read; a bundled id MUST resolve to a TOOL.md the app bundles, which MUST NOT declaremutatesor carry amutatororwritetag when the entry isread; two entries MUST NOT compute the same MCP name, and a computed name MUST NOT exceed 64 characters. A non-emptyresourcesMUST hold distinctui://URIs and MUST come with at least oneimported:entry intools.defineAppand the loader MUST refuse a definition that violates any of these. Nothing is registered or dispatched until a host's gateway does it (see Exposed tools and resources). -
requirestakes one of two forms, andappsentries are closed. Whenrequiresis present it MUST be either an array of non-empty strings or an object with no key besidesbrowser,fs,gpu,secretsandapps, wherebrowser,fsandgpuare booleans andsecretsis an array of non-empty strings. Eachappsentry MUST be a non-empty string or an object with a non-emptyidand no key besidesid,version,workflowsandtools; two entries MUST NOT name the sameid.versionMUST be an exact, caret or tilde range,workflowsan array of non-empty strings, andtoolsan array of MCP names (<prefix>_<n>, at most 64 characters).defineAppand the loader MUST refuse a definition that violates any of these. Checks that need the installed provider (everytoolsname exposed by it) belong to the host and run when it installs or reloads the app (see Requirements).
Emitted layout
emit(dir) (equivalently, a conforming host's install/write path) MUST
write:
<dir>/WORKSPACE.md (only when `workspace` is set)
<dir>/.agentproto/agents/<id>/AGENT.md (one per agent — id with any
`@owner/` prefix stripped)
<dir>/.agentproto/workflows/<wf.id>/WORKFLOW.md (one per workflow — a workflow
MAY be referenced by more
than one agent, so it is
written once and shared)
<dir>/.agentproto/ui/index.html (only when `ui` is set)
<dir>/.agentproto/artifact/index.html (only when `artifact` is set —
copied from `artifact.path`)
<dir>/.agentproto/skill/ (only when `skill` is set —
copied recursively from
`skill.path`, which MUST
contain a SKILL.md)
<dir>/.agentproto/APP.md (root index — ALWAYS written)Every AGENT.md / WORKFLOW.md is the handle's frontmatter serialized
to YAML plus the entry's body (agent) or description (workflow) as the
markdown body. Because a defineWorkflow handle is pure data, its
WORKFLOW.md needs no separate entry: module — the manifest is the
workflow.
APP.md's frontmatter is:
schema: app/v1
id: "@owner/app-id" # only when `id` is set
name: "Human name" # only when `name` is set
version: "0.1.0" # always present — defaulted per rule 8
description: "…" # only when `description` is set
agents:
- id: "@owner/agent-id"
path: .agentproto/agents/agent-id/AGENT.md
workflows:
- id: workflow-id
path: .agentproto/workflows/workflow-id/WORKFLOW.md
workspace: "@owner/workspace-id" # only when `workspace` is set
requires: ["@owner/other-app"] # only when `requires` is set: a list of ids, or
# { browser, fs, gpu, secrets, apps }, see "Requirements"
ui: # only when `ui` is set
path: .agentproto/ui/index.html
title: "…"
description: "…"
tools: [tool_id, ...]
port: 4173
csp: { connectDomains: [...], resourceDomains: [...] }
artifact: { path: .agentproto/artifact/index.html, title: "…", description: "…" }
skill: { path: .agentproto/skill, title: "…", description: "…" }
artifacts: [{ type: "…", description: "…" }]
dev: { launch: [{ name: "…", runtimeExecutable: "…", runtimeArgs: [...], port: 4173, url: "…" }] }
data: { dir: "data" } # only when `data` is set — app_data_* hint, relative to <dir>
category: "book" # only when `category` is set — freeform catalog grouping
setup: [ … ] # only when `setup` is set — see "Setup steps"
services: [ … ] # only when `services` is set, see "Services"agents[] and workflows[] entries are { id, path } refs, path
relative to dir. The body of APP.md is the app's description
(empty string when absent). Every field the definition omitted MUST be
omitted from the written frontmatter — the emitter MUST NOT write
undefined/null placeholders.
Loading (loadAppHandle)
A conforming loader reading <dir>/.agentproto/APP.md back into an
AppHandle MUST:
-
Reject frontmatter whose
schemais not exactly"app/v1". -
Reject
agents/workflowsfrontmatter that is not an array of{ id: string, path: string }. -
Resolve every
{ id, path }ref againstdir(relative paths are joined todir; absolute paths pass through) and load eachAGENT.mdvia the AIP-42 manifest reader and eachWORKFLOW.mdvia the AIP-15 loader. -
When
workspacenames an id, read the sibling<dir>/WORKSPACE.mdand parse it via the AIP-34 manifest reader. -
Re-run the loaded agents/workflows through the same construction path as
defineApp— so the attachment invariant (rule 3, above) re-validates on every load exactly as it did at authoring time. A hand-editedAPP.mdwhose refs drifted from itsAGENT.md/WORKFLOW.mdfiles MUST fail to load, the same way a baddefineApp({...})call fails to construct. -
When
setupis present, validate it against the Setup steps rules (conformance rule 10) and carry it verbatim. A loader MUST NOT execute, prompt for, or contact anything named insetup.
A loader failure MUST name the offending path (which file, which ref) — a bare "invalid app" is not sufficient diagnostic detail.
Implementer's guide
For step-by-step guidance on building an app/v1 conformant host —
bundle validation, emit/load, install/run lifecycle, the UI bridge,
and the data plane — see
./resources/aip-53/draft/ADAPTER.md.
The AIP only defines the contract; the resource doc walks an
implementer through the projection. The APP.md frontmatter shape is
machine-checkable against
./resources/aip-53/draft/APP.schema.json.
Example — minimal, from a shipped app
The following is the reference implementation's own
job-application-kit example app (abridged), rendered per the emitted
layout above:
---
schema: app/v1
id: '@agentproto/job-application-kit'
name: Job Application Kit
version: 0.1.0
description: >-
Search job boards, rank results against a candidate profile, tailor CVs and
cover letters per top match.
agents:
- id: '@agentproto/job-scout'
path: .agentproto/agents/job-scout/AGENT.md
- id: '@agentproto/job-tailor'
path: .agentproto/agents/job-tailor/AGENT.md
workflows:
- id: job-hunt
path: .agentproto/workflows/job-hunt/WORKFLOW.md
ui:
path: .agentproto/ui/index.html
title: Job Application Kit
tools:
- app_run
- app_status
- app_stop
- agent_output
- app_list
- app_data_read
- app_data_write
- app_data_list
- app_data_migrate
---
Search job boards, rank results against a candidate profile, tailor CVs and
cover letters per top match.job-scout's AGENT.md frontmatter carries workflows: [{ ref: job-hunt }];
job-hunt's WORKFLOW.md has one kind: agent step referencing
@agentproto/job-scout and one referencing @agentproto/job-tailor — the
attachment invariant holds in both directions.
Setup steps (setup[])
setup is OPTIONAL. When present it declares an ordered, idempotent
pipeline of post-install configuration steps the host runs after an
app is installed and before the app is considered ready. It is the
app-level counterpart of the AIP-29 setup block
and deliberately reuses its vocabulary — step id, kind, skip_if,
persist, a ledger, --force / --only / --dry-run re-runs — so a
host that already implements AIP-29 setup extends one engine rather than
building a second.
It exists because installing an app (unpacking APP.md, validating its
refs, recording it) does not make it usable. A real app needs values
only the user can supply and one-time bindings that outlive the
install: a chat-bot token and the pairing of a chat identity, a model
subscription (an auth profile), a choice between hosting options. Without
a declared place for them every app ships its own bespoke onboarding
script, and a host cannot tell "installed" from "ready", resume a half
finished setup, or re-run one step.
setup:
- id: cloud-computer
kind: choice
prompt: "Where should agent work run?"
options:
- { value: none, label: "None", description: "Everything stays on this machine." }
- { value: e2b, label: "E2B", description: "Bring your own E2B account." }
- { value: pygmalion-cloud, label: "PygmalionCloud", description: "Managed cloud computer." }
default: pygmalion-cloud
persist: { answer: cloud.provider }
- id: e2b-api-key
kind: prompt
type: secret
prompt: "E2B API key"
when: { step: cloud-computer, equals: e2b }
persist: { secret_slug: pygmalion/e2b-api-key }Step kinds
Two kinds are inherited from AIP-29 with unchanged semantics; the rest are added by this AIP because they need host-mediated behaviour that a shell command cannot express portably.
kind | Origin | Purpose | Required fields |
|---|---|---|---|
cmd | AIP-29 | Run a shell command. | cmd |
prompt | AIP-29 | Ask for one value: type: text | select | boolean | secret. | prompt |
oauth | AIP-29 | Drive an AIP-19 OAuth flow; tokens land in the named secret slug. | secret_slug |
external | AIP-29 | Open an https URL and wait for the user. | url |
choice | new | Pick exactly one of a closed set of options, with a default. | prompt, options, default |
auth-profile | new | Ensure the host holds enough usable model-login profiles. | none |
pairing | new | Bind an external chat identity to this install (a QR, link or code the user acts on elsewhere). | channel |
check | new | A read-only readiness probe. Never prompts, never mutates. | check |
x-* | vendor | Host- or vendor-specific extension (see Schema note). | id, kind |
Common fields
id(REQUIRED) — kebab-case, unique withinsetup[]. It keys the ledger, audit records and--only.title,description(optional) — what a surface shows above the step.optional(optional, defaultfalse) — the user MAY decline the step, or leave it pending, without blockingready. A declined optional step is ledgereddeclinedand is not re-offered by an unattended run, only by an explicitsetupre-run.when(optional) —{ step, equals }or{ step, done }. The step runs only if the earlier stepsteprecorded the answerequals, or is / is not complete (done: true | false). A step whosewhenis false is ledgerednot-applicableand never blocksready.when.stepMUST name an earlier step.skip_if(optional,cmdandprompt) — as in AIP-29:{ cmd, exit_code? }; a matching exit code skips the step.persist(optional) — where a captured value lands. Exactly one slot.env,secret_slugandcmdare exactly AIP-29's. This AIP addsanswer: <dotted.key>for NON-SECRET values: the value is recorded underanswers.<key>in the app's setup record, which the host exposes read-only to the app (reference: the setup record is returned by the host's app status surface).answerMUST NOT be used withtype: secret; a secret MUST land insecret_slugorenv.
Kind semantics
choice. options is a closed list of at least two
{ value, label, description? }; default MUST equal one option's
value. The recorded answer is the chosen value. A non-interactive
run (--yes) applies default. Later steps branch on the answer with
when: { step: <choice-id>, equals: <value> }, which is how one option
(e.g. e2b) can require a further secret that another option does not.
A choice is complete once an answer is recorded; changing it is a
--force --only <id> re-run, which also invalidates every step whose
when depends on it.
auth-profile. Complete when the host's auth-profile store (the
host's own notion of a stored model login — the reference host exposes
auth_profile_* tools) holds at least min (default 1) enabled
profiles, restricted to those usable by harnesses when given. When
incomplete the host offers its discover-and-import flow first, then
manual creation. The step records no secret: the profile store owns
the credential, and the ledger records only that the threshold was met.
pairing. channel is an open string; this AIP defines
telegram, host-defined channels are allowed. For telegram the host
MUST: require a bot token to be present first (a prior prompt step that
persisted one, or one already configured on the host); mint a one-time
pairing code bound to this install; render it per display (qr =
a QR encoding the bot deep link carrying the code, link, or code);
then wait up to timeout_sec (default 300) for the user to message the
bot with it, and record the resulting chat identity as the binding. A
pairing code MUST be single-use and expire at timeout_sec. The
binding is the host's to store; the ledger records persistedTo only
and never the identity token. A channel the host does not implement
fails the step with setup_unsupported_step.
check. Exactly one of check.cmd ({ run, exit_code? }, default
exit 0) or check.tool ({ id, args?, expect? }: call a host tool; pass
when the call succeeds and its result object contains expect as a
subset). severity: required (default) fails the pipeline with
setup_failed; severity: warn reports and continues. A check is
never ledgered as complete: it is re-evaluated on every run, so
ready always reflects the live system.
Idempotence and the ledger
A step is skipped, in order, when: (1) its when is false
(not-applicable); (2) its skip_if matches (skippedViaSkipIf); (3)
the ledger holds a done entry for it whose fingerprint still equals
the step's current fingerprint; (4) its kind's own live probe says it is
already satisfied (a secret slot already populated, the auth-profile
threshold already met, a pairing binding already present, a choice
already answered). Probes (4) make setup converge on a machine whose
ledger was lost; they MUST NOT read or display a secret's value.
The host MUST keep a setup ledger per (app.id, workspace.id, user.id) — the same tuple as AIP-29 — holding, per step id:
status (done | skipped | declined | not-applicable | pending | failed), at, appVersion, fingerprint, skippedViaSkipIf, and
persistedTo (a slot name, never a value), plus the non-secret
answers map. The ledger MUST NOT store a secret value, a token, or a
pairing identity, and no surface may echo one.
fingerprint is a stable hash of the step's definition. It is what
makes upgrades cheap and correct: when an app update adds a step, only
that step is pending; when it changes a step, only that step re-runs;
when it removes a step, the stale ledger entry is ignored. Steps the
user already completed are never re-asked because the version number
moved.
--force ignores skip_if, the ledger and the probes. --dry-run
resolves and prints what would run — including the verbatim text of
every cmd step — without spawning, prompting or writing the ledger.
--only <id> (repeatable) restricts to the named steps, in declared
order.
Lifecycle: what app install runs, and when
unpack/validate → record install → setup (this block) → ready- Install performs everything it does today (validation, tool-id cross-check, the installed-app record). Setup is a phase after the record exists, so a failed or abandoned setup leaves a valid install, not a half-written one.
- If
setupis present and any non-optional, applicable step is unsatisfied, the install result reportssetupState: "required"with the pending step ids, and the app is not ready. The host then runs the pipeline in declared order unless the caller passed--skip-setup(or is headless — see below). - A host MUST refuse
app_runfor an app that is not ready, witherror.code = "setup_required"and the pending step ids.app_applyMAY still bind the app to a scope; readiness gates running it, not applying it. Apps withoutsetuparereadyon install, exactly as before. - Re-run is
agentproto app setup <appId> [--force] [--dry-run] [--only <stepId>].... The existingagentproto setup <slug>verb MUST also accept an installed app id in place of a harness slug; app ids are@scope/name, harness slugs are not scoped, so the two namespaces cannot collide. - Update (
app_resyncand equivalents) re-evaluates the ledger by fingerprint, as above, and reportssetupState: "required"only for new or changed non-optional steps.
Steps run in order. A failure aborts the pipeline with error.code = "setup_failed" and the failing step's id; steps that completed before
it stay ledgered, so a re-run resumes at the failure.
Surfaces and non-interactive hosts
Setup is host-owned UI. An app's own ui surface MUST NOT be able to
answer a setup step, read a secret, or complete a pairing on the user's
behalf: it may only read the answers map and the pending-step list. A
host renders steps natively, as in AIP-29: terminal prompts on a CLI
(pairing prints the QR / link / code and polls), a form on a web
surface.
Setup steps are UI-agnostic. A step definition describes WHAT is
asked or checked, never HOW it is drawn, so the same setup[] renders
on any surface. A host MUST be able to render every step it supports in
a terminal AND in a web UI. The ledger is shared between the two: a
setup started in one surface MUST be resumable in the other, with
completed steps skipped under the same fingerprint rules and no
surface-specific state in the ledger. A host that offers only one of the
two surfaces is not conforming. The renderer MUST NOT change a step's
outcome: the same answers produce the same ledger entries whichever
surface collected them.
A headless or non-interactive host (--yes, no terminal, a remote
control surface) applies every default it can, then stops: steps that
need a human (type: secret, oauth, external, pairing, a choice
with no applicable default) are left pending and the install result
carries setupState: "required" with the pending list. It MUST NOT hang
waiting, and MUST NOT invent a value. The caller finishes setup later
with the re-run verb.
Errors
error.code | When |
|---|---|
setup_required | app_run on an app with unsatisfied non-optional steps. Carries the pending ids. |
setup_failed | A step errored or a required check failed. Carries the step id. |
setup_unsupported_step | The host does not implement a step's kind (or a pairing channel) and the step is not optional. The host MUST NOT silently skip it. |
setup_consent_required | A cmd step is pending and consent was not given (see Security). |
Schema note
Unlike every other field, setup carries per-kind validation, so
APP.schema.json
adds it as an explicit property with one strict (additionalProperties: false) shape per defined kind. The root additionalProperties: false
is unchanged: the manifest stays closed; setup is a new, named
field. The single relaxation is a vendor lane inside setup — a step
whose kind matches x-* MAY carry arbitrary extra keys — so a host or
vendor can experiment with a step kind (for example a pairing for a
channel this AIP does not define) without a schema release. A host that
does not implement the kind fails closed with setup_unsupported_step.
An older host whose schema predates this field rejects an APP.md that
carries setup (strict root). That is the intended fail-safe: an app
that needs setup to be usable must not be installed by a host that
would ignore the setup.
Services (services[])
services is OPTIONAL. When present it declares the long-running
processes an app needs alongside its agents and workflows: a web
server, a bridge, a worker. A service is a process the app declares and
the host starts with the app and keeps running, unless the entry opts
into activation on-demand, in which case the
host runs the process only while it is being used; defineApp, emit and
loadAppHandle only validate and carry the declaration, they never run
it. One entry is one process. There is no dependency graph between
services, no replica count and no scheduler (no cron, no queue) behind
the field; activation only chooses between a process that is kept
running and one that is started on demand.
It is not dev.launch. dev.launch holds dev-only launch recipes and is
never executed by a host that installs the app; services is the
production hosting surface.
services:
- name: web
command: node
args: [dist/server.js]
cwd: server
port: 4321
- name: bridge
entry: pnpm --filter bridge start
- name: miniapp
command: node
args: [dist/miniapp.js]
port: 8788
expose:
auth: service
hostname: session-chat
- name: viewer
command: node
args: [dist/viewer.js]
port: 8789
activation:
mode: on-demand
idleStopMs: 600000Each entry is an object with exactly these keys; any other key is rejected.
| Field | Required | Meaning |
|---|---|---|
name | yes | Service identifier. A kebab-case slug matching ^[a-z][a-z0-9-]*$, unique within the app. Together with the app id it identifies the service for the host's bookkeeping, logs and cleanup. |
command | one of command / entry | Structured form (preferred). A non-empty string: the binary or script to run, passed as argv[0] and never interpreted by a shell. |
args | no | Structured form only. A non-empty array of strings, the argv after command, passed verbatim. Not valid alongside entry. |
entry | one of command / entry | Legacy form. A non-empty shell command line, run by the host as sh -c <entry>. Use command unless you need shell syntax. |
cwd | no | Working directory, a non-empty path relative to the installed app directory. Defaults to the app directory. |
port | no | The TCP port the service listens on, an integer from 1 to 65535. Omitted means a service that does not listen. For a service that is kept running this is bookkeeping only: the host records it, and this AIP does not define passing it to the process (for example as an environment variable), so the service binds its own port. With activation.mode: on-demand the host listens on this port itself and gives the process another one in PORT (see Activation). |
expose | no | Ask the host for a public URL that reaches this service's port. An object, see Exposure. Requires port. Omitted means the host publishes nothing. |
activation | no | When the host runs the process: kept running (always, the default) or started on the first request and stopped when idle (on-demand). An object, see Activation. on-demand requires port. |
Exactly one of command and entry MUST be present on every entry.
Host behaviour
A host that runs an app (its app_install path) is the only party that
starts services. The reference implementation behaves as follows, and the
requirements below codify it:
- Start at install. After the install has recorded the app, a host
MUST attempt to start every declared service before the install
returns. Services are started in declaration order; the host does not
wait for a service to become ready, so a service MUST NOT assume that
an earlier one is listening. For an
on-demandservice, starting means taking the listening side of itsport; the process itself starts later (see Activation). - A service that fails to start does not fail the install. The host MUST report the failure (name and reason) and MUST NOT roll the install back or mark the app uninstalled because of it.
- One live process per service, idempotent. Re-running the install for an app MUST NOT start a second process for a service that is still running. A service whose recorded process has died is replaced. A service the manifest no longer declares MUST be stopped.
- Environment. A service runs with the host's environment. A
relative
cwdis resolved against the installed app directory. The reference host setsAGENTPROTO_SESSION_IDto the id of the session it opened for the process, after merging every other source, so a service cannot override it: a value of that name in the service's own environment file is shadowed (Node's--env-filekeeps a variable that is already set). A service SHOULD NOT use that name for its own configuration. - Restart. On an unexpected exit a host SHOULD restart a service that is kept running with a bounded, increasing delay, and give up after repeated failures so the next install or host boot replaces it. The reference implementation waits 1s doubling up to 60s, and gives up after 5 failures within 10 minutes; those numbers are not normative.
- Boot. When the host itself starts, it SHOULD re-establish the services of every installed app that declares them.
- Uninstall. Uninstalling an app MUST stop every one of its services, including any child processes they spawned, so a reinstall does not leave a second copy running.
A host that does not run services still MUST reject a malformed
services block when it loads an app.
Exposure (expose)
A service is reachable only on the machine it runs on unless it declares
expose. With expose, the host gives it a public URL through an
AIP-73 tunnel. The app states that it needs a public
URL and how requests are authenticated; which tunnel provider carries
it is the host's configuration, never the app's.
| Field | Required | Meaning |
|---|---|---|
auth | no | Who authenticates a request that reaches the URL. guard (default): the host puts its access guard in front of the tunnel, and only an entry link the host hands out opens it. service: no guard, the URL is public and the service authenticates every request itself. |
hostname | no | A hostname request: a DNS label (session-chat) or a full name (app.example.com), lowercase. Passed as the primary entry of the AIP-73 hostnames. The provider decides what it routes and may assign another name, so an app MUST NOT depend on getting it and reads its URL from the environment instead. |
expose is an object with exactly these keys; any other key is
rejected. expose: {} is valid and means a guarded URL on a hostname
the provider assigns.
A host that starts services behaves as follows for an exposed service:
- No
expose, nothing public. A host MUST NOT publish a service that does not declareexpose. Such a service SHOULD bind the loopback interface. - One tunnel per exposed service, stable key. The host creates an
AIP-73 tunnel whose
keyis derived from the app id and the service name (see Tunnel key below), whoseserviceishttp://127.0.0.1:<port>, and whosehostnamesis[hostname]whenhostnameis set. Becausecreateis idempotent on the key, a reinstall or a host boot gets the same tunnel back, and the same URL when the provider hasstableUrl. A host SHOULD use a provider withstableUrl: true; when it falls back to one without, it MUST report the exposure as not stable. - Tunnel before process. The host creates the tunnel before it
starts the process and passes the public origin (
https://<host>, no path and no access token) inAGENTPROTO_PUBLIC_URL. A service that builds links to itself (a Telegram button, an OAuth callback) reads them from there. A restart of the process reuses the tunnel. When the origin a running process was started with is no longer the current one (exposeadded to a running service, or a provider that handed out a new URL), the host restarts the process so it sees the new value. - A failed tunnel does not fail the install. When the tunnel cannot
be created, the host MUST report it (service name and reason), MUST
still start the process, without
AGENTPROTO_PUBLIC_URL, and MUST NOT roll the install back. - Guard. With
auth: guard, a request that does not carry the guard's credential MUST NOT reach the process. The entry link (the URL with its access token) is handed to a caller who asks for it; it is never placed in the service's environment. Withauth: service, the host MUST present the exposure as public wherever it reports it. - Status. For each exposed service the host reports the public
origin,
auth, whether the URL is stable, and the tunnel state. - Boot and removal. On boot the host re-establishes the tunnels of
the services it re-establishes. Uninstalling the app, removing the
service, or removing its
exposestops the connector and deletes the tunnel (AIP-73delete). - Services in a sandbox. When the host runs the service inside an
AIP-36 sandbox, the URL MUST reach the process where it
runs. The party that holds the tunnel provider's credentials creates
the tunnel and gives the sandbox only the connector token, which
AIP-73 scopes to one tunnel; the connector runs inside the sandbox,
next to the service. Provider credentials MUST NOT be copied into the
sandbox. A host MAY use the sandbox provider's own port exposure
(
extraPorts) instead, but only forauth: service, because such a URL carries no guard.
Tunnel key
App ids carry characters a provisioner may refuse in a key (@, /),
so the key is not the raw id. It is app.<a>.<s>.<h>:
<a>: the app id lowercased, every run of characters outside[a-z0-9-]replaced by-, leading and trailing-removed, cut to 24 characters;<s>: the service name cut to 24 characters;<h>: the first 8 hexadecimal digits of the SHA-256 of the UTF-8 string<appId>:<name>, with the original app id.
The result always matches ^[a-z0-9][a-z0-9._-]{0,62}$, the narrowest
key alphabet of the reference provisioner, and <h> keeps apart two
apps whose ids reduce to the same <a>. For @agentik/pygmalion and
telegram-miniapp the key is
app.agentik-pygmalion.telegram-miniapp.f29069fe. A host MUST derive the key exactly this way,
so that another host of the same user finds the same tunnel.
auth: service is for a service that has its own authentication on
every route. A Telegram Mini App is the typical case: Telegram opens a
saved URL without the guard's token (Telegram Desktop drops the query
string), and the service validates the signed initData of each
request instead. A guard with an expiring token would break the saved
button.
Activation (activation)
By default a service is kept running: the host starts its process at
install and at boot, and restarts it when it exits. A service that is only
used now and then, such as a viewer behind a bot button, can ask not to be:
with activation.mode: on-demand the host owns the service's port and runs
the process only while somebody is using it. Nothing runs when it is
unused, so there is nothing to crash-loop at boot and no process left
behind holding the port after a host restart.
| Field | Required | Meaning |
|---|---|---|
mode | yes | always (default when activation is omitted): the process is kept running, as described under Host behaviour. on-demand: the host starts the process on the first inbound connection and stops it when idle. Requires port. |
idleStopMs | no | on-demand only. An integer from 1000 to 86400000, default 300000: how long the service stays up after its last open request or connection ended. |
startTimeoutMs | no | on-demand only. An integer from 1000 to 300000, default 30000: how long a request waits for the process to start listening. |
activation is an object with exactly these keys; any other key is
rejected. { mode: always } is the same as omitting it, and idleStopMs
and startTimeoutMs are rejected under mode: always.
Only a service whose work is driven entirely by inbound requests may be
on-demand. A service that polls, consumes a queue, keeps a connection to
a third party open or runs on a timer does its work while nobody is
calling it: the host would stop it as idle, and it MUST stay always.
A host that starts services behaves as follows for an on-demand service:
- The host owns the port. At install and at boot the host listens on
porton the loopback interface and starts no process. When it cannot bind the port, it reports the failure like a service that failed to start (Host behaviour, rule 2). - The first request starts the process. When an HTTP request or an
upgrade arrives and no process is running, the host starts one, with the
environment of Host behaviour rule 4 plus
PORT, set to a free loopback port the host picked for this start. The process MUST listen onPORT, SHOULD bind the loopback interface only, and cannot bind the declaredport, which the host holds. A service that hardcodes its port cannot beon-demand. - Requests wait for the start, with a bound. A request that arrives
while the process is starting waits for it, and one start serves every
request waiting. The process is ready when it accepts connections on
PORT. When it exits first, or has not done so afterstartTimeoutMs, the host answers every waiting request503 Service Unavailablewith aRetry-Afterheader. The response MUST NOT carry the cause (command, path, error text); that goes to the host's log. - The host is a transparent proxy. It forwards the request as it
received it: method, target and headers other than the hop-by-hop ones,
including
Host, with the body streamed in both directions, and streams the response back. AnUpgraderequest (WebSocket) is forwarded and the connection becomes an opaque byte stream. The process sees what it would have seen listening onportitself. When the process has accepted the connection but fails, the host answers502 Bad Gateway. - Busy, then idle. The service is busy while a forwarded request is
open (until its response has ended) or an upgraded connection is open.
Once it has not been busy for
idleStopMs, the host stops the process and every child it spawned, as it does at uninstall, and the next request starts it again. A request is never cut by the idle timer, however long it runs; an open streaming response or WebSocket keeps the service up until it ends. A quiet keep-alive connection that carries no request does not. - No restart, backoff instead. A process that exits unexpectedly,
before it listens or while it runs, is not restarted by the host: the
service goes back to idle and the next request starts it. So that a
crashing service is not restarted at the rate requests arrive, a host
SHOULD refuse a start with
503andRetry-Afterfor an increasing delay after each unexpected exit, and MUST NOT give up for good: it keeps listening, and a request after the delay starts the process. The reference implementation reuses the numbers of rule 5 (1s doubling up to 60s, failures counted within 10 minutes); they are not normative. An exit an operator caused is not a failure. - Exposure is unchanged. The tunnel of an exposed service still
targets
http://127.0.0.1:<port>, now the host's listener, so the URL works while no process runs and the first request through it starts the process. Withauth: guard, a request the guard refuses never reaches the listener and starts nothing; withauth: servicewhoever holds the URL can start the process.AGENTPROTO_PUBLIC_URLis set at every start, and when the origin changes while the process runs, the host stops it so the next start sees the new value. - Reinstall, boot, mode change, uninstall. Re-running the install
keeps the host and does not start a process. A manifest that changes a
running service between
alwaysandon-demandreplaces it: the process is stopped first, so that the port is free for whichever side holds it. At boot the host takes the port and starts nothing. Uninstall and removal of the service stop the host and its process. - Stopping the host stops its processes. The listener was the only way in, so a process the host started on demand MUST NOT outlive the host.
- Status. The host reports each
on-demandservice's state:idle,starting,runningorstopping.
Errors
A malformed services block is rejected at load and at install with an
error that starts with invalid services declaration, whichever gate
sees it first. The message names the offending entry by index
(services[1].port), and a duplicate name reads two services named 'x'.
An expose without port reads services[1].expose requires a port, and
an on-demand activation without one reads services[1].activation.mode 'on-demand' requires a port.
Schema note
APP.schema.json
declares services as an array of strict objects. "Exactly one of
entry / command" and "args only with command" are expressed with
oneOf. JSON Schema 2020-12 cannot say that name is unique across the
array; uniqueItems only rejects entries that are identical in full, so
a validator that stops at the schema accepts two services with the same
name and different commands. The loader is the authority on that rule
(conformance rule 11). expose requiring port is expressed with
dependentRequired. activation is a closed object; idleStopMs and
startTimeoutMs being refused under mode: always is an if/then
inside it, and mode: on-demand requiring port is an allOf if/then
on the service entry.
The schema is stricter than the reference implementation in one place:
the reference implementation resolves any non-empty cwd, including an
absolute path or one with .. segments, which places a service outside
its app directory. The schema rejects both. A host SHOULD refuse such a
cwd too.
Exposed tools and resources
exposes declares what an app offers to callers outside it. It is a
closed object with five optional keys: agents, workflows, prefix,
tools and resources. The first two name parts of the bundle; the other
three publish tools and ui:// views to MCP clients through the host's MCP
gateway.
exposes:
agents: [job-scout]
workflows: [job-hunt]
prefix: jobkit
tools:
- id: jobkit.list # a TOOL.md the app bundles
access: read
description: List the job leads in the pipeline, newest first.
- id: imported:browser/browser_screenshot
access: read
mcpName: screenshot # required for an imported id
description: Capture the current page of a browser instance.
inputSchema:
type: object
properties: { instance: { type: string } }
resources:
- ui://browser/screenshotagents and workflows
Each is an array of non-empty strings. Every entry MUST be the id of an
agent, respectively a workflow, the same app declares; the loader MUST
refuse an entry that names anything else. workflows is the callable
surface other apps' requires.apps[].workflows entries may name when
they invoke a provider's workflow (see app_call). Neither
key declares an exposed tool.
Prefix and MCP names
prefix MUST match ^[a-z][a-z0-9]{1,15}$: lowercase letters and digits
only, 2 to 16 characters. It contains no _, so the first _ of an
exposed name is always the separator. prefix MUST be present when
tools is non-empty.
The MCP name of an entry is <prefix>_<n>, computed in this order:
- Take
mcpNamewhen set, otherwiseid. - Remove one leading
<prefix>.or<prefix>_. - Replace every character outside
[a-zA-Z0-9_-]with_, merge runs of_, and trim one leading and one trailing_. - Prepend
<prefix>_.
jobkit.leads.upsert under prefix jobkit becomes
jobkit_leads_upsert; bureau_status under bureau becomes
bureau_status. A host MUST compute the name with exactly this rule, so
two hosts publish the same name for the same manifest. The loader MUST
refuse an entry whose step 3 leaves nothing, whose computed name is longer
than 64 characters, or whose computed name equals that of another entry of
the same app (the author sets mcpName on one of them). mcpName MUST
match ^[a-zA-Z0-9][a-zA-Z0-9_-]*$, so it carries no :, / or ..
Entry id values MUST be unique within tools.
A host namespace is shared by every app and by the host's own tools, so a host MUST also:
- refuse a
prefixthat is the first_segment of one of its own tool names (a prefixappwould claim theapp_*family), and refuse anidthat is the name of one of its own tools. Those stay reserved to the UI allowlist (ui.tools); - refuse to install an app whose non-empty
toolsuse aprefixanother installed app already holds. Reinstalling the same app is not a conflict; - never register an exposed tool under a name one of its own tools has, nor under a name an earlier app already holds, and report the entry as skipped instead of letting it shadow the other tool.
Tool entries
An entry carries id, access and description, and MAY carry
inputSchema, mcpName and approvalArg. It is a closed object: any
other key is refused.
idis non-empty. It is the id of a TOOL.md the app bundles, orimported:<alias>/<tool>for a tool of an MCP server the app imports. For a bundled id the loader MUST find the TOOL.md and refuse the manifest when it is missing.accessis one ofread,write,approve(see below).descriptionis required, is not blank, is at most 300 characters, and is written for a model: it is what an MCP client shows when choosing a tool.approvalArgis a non-empty string and MUST NOT be set unlessaccessisapprove.
An exposed id does not have to appear in ui.tools. exposes.tools is
its own allowlist: a call for an id that is not declared there MUST be
refused, and an exposed call never falls through to the host's own
tools.
Access classes and default visibility
access | Meaning | Default visibility |
|---|---|---|
read | Observes, changes nothing | Every caller |
write | Changes data or has side effects | Only a caller that opted in |
approve | Takes part in a human decision, for example a tool that carries an approval reference | Only a caller that opted in |
A host MUST NOT list or run a write or approve entry for a caller that
has not opted in to that exact MCP name, unless the operator has explicitly
widened exposure for every caller. The opt-in is declared by the calling
agent, not by the app: in the reference host an agent lists the names it
wants in its AGENT.md as tools: [{ kind: mcp, server: agentproto, allow: [jobkit_leads_upsert] }], matched exactly with no wildcard. A deny grant,
a deny list or an allow subset that applies to the caller always wins over
every access class and over an opt-in.
A host SHOULD give the operator one setting with three values: expose
read tools only (the default), expose nothing, or expose every declared
tool to every caller. The reference host reads it per request as
defaults.apps.exposedTools (read, off, all), so a change applies to
the next call. The setting is checked on the call path as well as on the
tool list: a tool the list hides is not callable by name.
access: read is a claim the loader checks against the bundle: it MUST
refuse a read entry whose bundled TOOL.md declares a non-empty mutates
or carries a mutator or write tag (compared case-insensitively). The
check is one-way. A tool with no such declaration can still write, so the
author remains responsible for the class, and a host SHOULD NOT treat
read as a safety guarantee on its own.
A host SHOULD publish readOnlyHint on a read tool and destructiveHint
on write and approve tools, using the annotations MCP defines.
Why approval tools are refused
An id or an mcpName that starts with approval MUST be refused at
load. A host MUST also refuse to register any tool whose computed name
starts with approval and MUST NOT add a tool that decides an approval of
its own. Whoever asks for an approval does not decide it: the decision
belongs to a human surface (in the reference host, an approval card), and
the party that requested it is refused when it tries to decide.
exposes.tools publishes tools to agents. If it could name an approval
decision, an agent would have a second path to its own approval and the
rule above would be only as strong as the app author's care. The name
check closes that path wherever the manifest comes from.
access: approve therefore marks a tool that takes part in a decision,
for example by carrying a reference to an approval, and not a tool that
makes one. approvalArg names the input argument that carries that
reference. It is a shape hint for clients and authors, not an enforcement
point: whether a given approval is valid is decided by the host's approval
engine when the tool consumes it.
Imported tools
An imported:<alias>/<tool> id exposes a tool of an MCP server the app
imports. Its spelling has no MCP-safe form, so:
mcpNameis REQUIRED. The loader MUST refuse animported:entry without it;accessMUST beread. The loader MUST refuse any other class for an imported id: nothing in the manifest lets a host check a foreign server's tool against a TOOL.md, so it never offers one as writing or approving;- the host MUST dispatch the call to the named server and to nothing else, and never resolves the id among its own tools.
An exposed imported tool behaves like the original:
- The result passes through unchanged. The host MUST return the
server's
CallToolResultas it received it: every content block (images included),structuredContent,isErrorand_meta. It MUST NOT wrap, re-encode or rewrite them. A value that is not aCallToolResult(it has nocontentarray) MAY be wrapped as a single text block. A bundled tool answers with its output as one JSON text block. _meta.uiis preserved. When the imported tool's own listing carries_meta.ui(the MCP Apps widget link), the host MUST copy that object onto the exposed tool's entry intools/list, with itsresourceUriunchanged. A host that cannot read the import's tool list in time MAY list the tool without it. The host copiesuionly; other_metakeys of the listing are not forwarded.- Undeclared inputs are dropped. See
inputSchemabelow.
inputSchema
inputSchema, when present, is a JSON Schema object (type: object). It
is the schema the host publishes for the tool. Without it the host uses the
inputs of the bundled TOOL.md, and when neither exists it publishes a
single optional args object.
On an imported: entry whose inputSchema declares properties, the
schema is also a filter. Before it calls the imported tool, the host MUST
remove every top-level input key that properties does not declare, and
MUST forward only the rest. The one exception is an inputSchema that
sets additionalProperties: true, which forwards the input as received.
An inputSchema without properties filters nothing. This lets an app
narrow a foreign tool: an exposed screenshot tool that declares
instance and fullPage never passes the import's own path argument,
so a client cannot make the import write a file. For any other entry, a
host SHOULD validate the input against the schema before it runs the tool.
resources
resources is the app's allowlist of views. It is an array of distinct
URIs, each matching ^ui://[^\s]+$. It MAY be non-empty only when
tools holds at least one imported: entry: a view is relayed from an
import, and an app with nothing imported has nothing to relay from. An
empty array is accepted and means no allowlist.
A host MUST:
- register exactly the allowlisted URIs of an app whose tools it exposes,
and answer
resources/readfor each by relaying it to the app's imported servers (the aliases of itsimported:entries, in the order they are declared, the first one that answers wins); - refuse a
resources/readfor any other URI as an unknown resource, even when an imported server would serve it; - NOT relay a full
resources/list. The list a client sees is the allowlisted URIs and nothing else; - register no resource when exposure is turned off.
The allowlist exists because a server's resources/list is the server's
choice, not the app's. Relaying it whole would hand every client whatever
the import chooses to serve, including resources the app author never
reviewed.
Errors and loading
The loader validates exposes when the manifest is loaded, and a host
validates it again when it installs the app and when it registers the
tools, because an installed record can be edited by hand. A malformed
declaration is refused with a message that names the entry by index
(exposes.tools[2].mcpName). A host that finds an installed declaration no
longer valid MUST NOT register any of that app's tools, and MUST NOT fall
back to registering the entries that still look valid.
Schema note
APP.schema.json
declares exposes as a closed object and each tool entry as a closed
object. It expresses the prefix pattern, the required keys of an entry,
the access enumeration, the 300-character bound, approvalArg only with
approve, an imported: id requiring mcpName and access: read, the
approval refusal on id and mcpName, the ui:// URI pattern and its
uniqueness, prefix being required once tools is non-empty, and
resources needing an imported: entry (with if/then and contains).
JSON Schema 2020-12 cannot compute, so a validator that stops at the
schema accepts: an exposes.agents or workflows entry that names no
agent or workflow of the app, a bundled id with no TOOL.md or a read
entry whose TOOL.md is tagged mutator, two entries with the same
computed name, a computed name over 64 characters, a duplicate id, a
prefix or an id that collides with a host's own tool names, and a
description whose length differs between UTF-16 code units and code
points. The loader is the authority on all of them (conformance rule 12).
Requirements (requires)
requires says what an app needs from its host and from other apps. It
takes one of two forms.
A list of app ids. Each entry is a non-empty app id. The list names
dependencies only: no version range, no callable workflow, and nothing
granted. It is equivalent to the object form with every id written as a
bare apps entry.
requires: ["@agentik/bureau"]An object. Every key is optional and the object is closed:
| Key | Type | Meaning |
|---|---|---|
browser | boolean, default false | Needs the user's real browser. |
fs | boolean, default false | Needs the user's local filesystem beyond the app data dir. |
gpu | boolean, default false | Needs a GPU. |
secrets | string[], default [] | Env or secret names the app needs. |
apps | entry[], default [] | Apps this app depends on, see below. |
browser, fs, gpu and secrets are declarations a host MAY show
before install and MAY use to decide where an app can run. This AIP
attaches no enforcement to them.
type AppRequires = string[] | {
browser?: boolean
fs?: boolean
gpu?: boolean
secrets?: string[]
apps?: (string | AppRequirement)[]
}
interface AppRequirement {
id: string // the provider app id
version?: string // exact, caret or tilde range, see below
workflows?: string[] // provider workflows this app may call with app_call
tools?: string[] // provider tool MCP names granted to this app's agents
}requires:
browser: true
secrets: [OPENAI_API_KEY]
apps:
- "@acme/notes" # a dependency only
- id: "@agentik/bureau"
version: "^0.3"
workflows: [capture-page]
tools: [bureau_navigate, bureau_click, bureau_fill, bureau_screenshot]In this section the app that declares requires is the consumer and
the app an apps entry names is the provider.
apps entries
An entry is a bare provider id, which means the same as { id }, or an
object with id and any of version, workflows and tools. The object
is closed: any other key is refused. Two entries of the same apps list
MUST NOT name the same id.
-
idis the provider's APP.mdid, matched exactly. -
versionis a range the provider's installed version MUST satisfy. Three shapes are accepted, and the loader MUST refuse anything else:- an exact version,
1.2.3(a prerelease or build suffix is allowed, as in the APP.mdversionpattern); - a caret,
^1,^1.2or^1.2.3: at least that version, and the same leftmost non-zero component, so^1.2accepts1.9.0but not2.0.0,^0.3accepts0.3.7but not0.4.0, and^0.0.4accepts only0.0.4; - a tilde,
~1,~1.2or~1.2.3: at least that version, the same major, and the same minor when a minor is written, so~1accepts1.9.0and~1.2accepts1.2.9but not1.3.0.
Missing components count as
0. A suffix on the installed version is ignored when comparing, so1.2.3-rc1satisfies^1. Omittingversionaccepts any installed version. A provider with no recorded version satisfies no range. - an exact version,
-
workflowsis the allowlist forapp_call, the call a consumer makes to run one of a provider's workflows. Each entry is a workflow id from the provider'sexposes.workflows. Omitted or empty, the consumer may call no workflow of that provider. -
toolslists provider tools the host grants to the consumer's own agents, see Granted tools. Omitted or empty, nothing is granted.
Granted tools (requires.apps[].tools)
Each tools entry is the MCP name of one of the provider's exposes.tools
entries: the name <prefix>_<n> the provider's manifest computes under
Prefix and MCP names, for example
bureau_navigate. A host matches an entry by computing the MCP name of
every provider exposes.tools entry with that rule and comparing exactly,
case included. The provider's tool id (bureau.navigate,
imported:browser/browser_navigate) is not accepted.
The MCP name is the form because it is the provider's public contract and the id is not:
- it is the name the consumer's agents see and call, and the name an
AGENT.md already uses to opt in to a
writeorapprovetool, so a grant and an opt-in name the same thing; - every host computes it the same way from the provider's manifest, and the loader already refuses two entries of one app that compute the same name, so it is unique;
- the id carries the provider's internals: whether a tool is bundled or imported, and the alias of the server it is imported from. A provider can move a tool from an import to a bundled TOOL.md, or rename an import, without breaking its consumers, as long as the MCP name stays.
A host MUST apply these rules:
- Every name is exposed. When the provider is installed, each
toolsentry MUST equal the computed MCP name of one of itsexposes.toolsentries. Otherwise the host MUST refuse to install or reload the consumer, with an error that names the entry by index and the provider, for examplerequires.apps[0].tools[2]: "bureau_type" is not exposed by "@agentik/bureau" (exposes: bureau_navigate, bureau_click, ...). The loader alone cannot run this check, because it needs the installed provider; a loader MUST still refuse a name that does not have the shape of an MCP name. - Who receives the grant. The grant applies to the consumer's own
agents only: sessions the host runs from an AGENT.md the consumer
bundles, attributed to the consumer by the host when it starts them.
For each such session the host behaves as if the AGENT.md had opted in
to every granted name, exactly, by name. No other caller gains
anything: not the consumer's UI (its reach stays
ui.tools), not an agent of another app, not an external MCP client, not a session that only claims to belong to the consumer. - At the provider's access class. A granted tool keeps the
accessthe provider declares. The consumer cannot raise or lower it, and the entry carries no access of its own. Areadtool is already visible to every caller, so granting it changes nothing; awriteorapprovetool becomes visible and callable for the consumer's agents. - Approvals still apply. A granted
approvetool keeps its approval requirement. The grant never decides, consumes or skips an approval; the host's approval engine checks the reference on every call exactly as for an AGENT.md opt-in. - The operator and deny rules still win. The grant is an opt-in and
nothing more. When the operator has turned exposure
off, nothing is granted. A deny grant, deny list or allow subset that applies to the session wins over a granted name, as it wins over any opt-in. - The version range gates the grant. When the entry sets
versionand the provider's installed version does not satisfy it, the host grants nothing from that entry and reports it (see below). - All or nothing per entry. When any rule above fails for an entry, the host grants none of that entry's tools. It never keeps the names that still look valid.
Missing providers
Installing a consumer whose requires.apps names a provider that is not
installed MUST succeed. The host MUST report every unmet entry, both in
the install result and in its app listing, and MUST grant nothing from
that entry until the provider is installed. The reference shape is a list
on the installed-app record:
{
"unmetRequires": [
{ "id": "@agentik/bureau", "reason": "not-installed" }
]
}reason is one of not-installed, version-mismatch (the installed
version does not satisfy version; the entry also carries installed)
and tool-not-exposed (a later provider change dropped a granted name;
the entry also carries tools, the names no longer exposed). The list is
recomputed whenever a provider is installed, reinstalled or uninstalled.
Installing the provider later makes the grant apply to sessions started
from then on, with no action on the consumer, once rule 1 holds.
When a provider is uninstalled, its grants disappear: the host stops
listing and running its tools for the consumer's agents, and adds the
entry back to unmetRequires as not-installed. The consumer keeps
loading and running. When a provider is reinstalled at a version that no
longer exposes a granted name, or no longer satisfies the range, the
consumer also keeps loading, the entry grants nothing and is reported as
tool-not-exposed or version-mismatch, and the next install or reload
of the consumer applies rule 1.
A host that binds apps to scopes MAY additionally refuse to apply a
consumer to a scope before its providers are applied there, and MUST
refuse when a provider's installed version does not satisfy the declared
range (reference: app_apply).
app_call
app_call runs a provider workflow on behalf of a consumer. The host
MUST refuse the call, with a distinct error for each case, when the
consumer is not installed, when it declares no apps entry for the
provider, when the workflow is not in that entry's workflows, when the
provider is not installed, when the workflow is not in the provider's
exposes.workflows, or when the provider's version does not satisfy the
entry's version. Unlike tools, workflows is checked when a call is
made, not at install: a grant applies to every session the consumer's
agents start, so it is checked before any of them runs, whereas a call
names its workflow and is checked on its own. Like a grant, app_call
checks a declaration: it says what a consumer may ask of a provider, and
does not authenticate which app is calling.
What the schema checks
APP.schema.json
expresses both forms of requires with oneOf, the closed object and the
closed apps entry, the three version shapes, and the shape of an MCP
name in tools (<prefix>_<n>, at most 64 characters). It cannot express
the checks that need the installed provider (every tools name exposed
by it, every workflows id in its exposes.workflows, the version
satisfied) or two apps entries with the same id. The host is the
authority on those (conformance rule 13).
The .agentapp package format (agentapp/v1)
An emitted app directory is the installed form. .agentapp is the
distributable form: one self-contained, checksummed file — packaged and
unpacked by the reference agentproto app pack / agentproto app unpack
CLI verbs.
pack
Given an app directory <appDir> containing a valid
.agentproto/APP.md, pack MUST:
- Parse
APP.md's frontmatter into bundle metadata:id(falling back to aslugfield, then the literal string"app"),version(falling back to"0.1.0"),name,description, theagents[]/workflows[]id lists, and the basenames of anyui/artifact/skillpaths. - Walk the entire
<appDir>tree and collect every regular file as a path relative to<appDir>, skipping any directory namednode_modulesor.gitat any depth — aui/source project ships both, and neither belongs in a shipped app. - Sort the collected file list lexicographically by path.
- Compute one SHA-256 hash over the concatenated bytes of every file's contents, fed in the sorted order — a single aggregate digest, not a per-file manifest of digests.
- Write a
manifest.json(schema below) at the bundle root. - Tar (
tar -czf) the app directory's contents (not the directory itself, so extraction yieldsmanifest.json+.agentproto/+ any loose files at the top level) into the output.agentappfile. Without an explicit output path, the default is<safe-id>-<version>.agentappin the current directory, where<safe-id>strips a leading@and replaces every run of characters outside[A-Za-z0-9._-]with-.
The manifest.json schema:
interface AgentAppManifest {
format: "agentapp/v1"
id: string
name?: string
version: string
description?: string
agents: string[] // agent ids
workflows: string[] // workflow ids
ui?: string[] // basenames of ui-related files, if any
files: string[] // every bundled file's path, sorted
fileCount: number
totalSize: number // bytes, sum of every file's size
sha256: string // the aggregate digest (rule 4 above)
createdAt: string // ISO-8601 timestamp
agentprotoVersion: string // compatibility range, e.g. ">=0.1.0"
}manifest.json itself is excluded from files[] and from the SHA-256
computation — it describes the bundle, it is not part of it.
unpack
Given a .agentapp file, unpack MUST:
- Extract the archive to a fresh temporary directory.
- Require a
manifest.jsonat its root; a bundle without one is not a valid.agentappand MUST be refused. - Require
manifest.format === "agentapp/v1"; any other value MUST be refused with the actual format named in the error. - Recompute the aggregate SHA-256 over the files listed in
manifest.files, in the order listed, and compare againstmanifest.sha256. A mismatch MUST refuse the unpack — the bundle is corrupted or was tampered with, and unpack MUST NOT silently restore it anyway. - Only once the digest verifies, remove
manifest.jsonfrom the extracted contents (a bundle artifact, not part of the app) and move the remaining contents into the destination directory. Without an explicit destination, the default is<safe-id>-<version>in the current directory.
The UI surface contract
Static layout
A UI surface is a static file tree rooted at .agentproto/ui/, with
index.html as its entry point. Conformance rules:
index.htmlis the entry point. A conforming host serving a UI surface MUST treat.agentproto/ui/index.htmlas the document to return for the root path and for any directory-style request.- Asset paths MUST be relative. A UI ships as a portable static
tree — it does not know in advance whether it will be served at
http://127.0.0.1:<port>/, mounted under a host panel's own path scheme, or opened viafile://. Absolute root-relative paths (/app.js) are non-conforming;./app.jsorapp.jsare required. - No server-side routing. A UI surface is static files, not an
application server — there is no route table for a host to consult.
A UI that wants client-side navigation MUST use hash-based routing
(
#/jobs/42) rather than the History API'spushState, since a static file server has no fallback rule to reroute a deep-linked path back toindex.html. - A
ui/source directory is a distinct, optional thing from the emitted.agentproto/ui/— see Theui/source-project convention.
The window.McpApp bridge
A conforming host that renders a UI surface — embedding it in a panel,
or serving it standalone — MUST inject a global window.McpApp object
of this shape before the page's own scripts run:
interface McpAppGlobal {
connect(): Promise<McpAppBridge>
}
interface McpAppBridge {
callTool(name: string, args?: Record<string, unknown>): Promise<unknown>
updateModelContext(ctx: Record<string, unknown>): Promise<unknown>
openLink(url: string): Promise<unknown>
onTeardown(cb: () => void): void
}callTool(name, args)invokes a tool by id and resolves with the raw MCPtools/callresult envelope ({ isError?, structuredContent?, content? }) — unwrapping is the UI client library's job (see Result unwrapping), not the bridge's.updateModelContext(ctx)lets the UI push context back to whatever model/session is driving the host. A host with nothing to persist it to MUST treat this as a no-op, not an error.openLink(url)opens an external URL. A conforming implementation MUST NOT navigate the UI's own frame away from the app — it opens a new context (tab/window).onTeardown(cb)registers a callback fired when the UI's session ends (page unload, or the host tearing down the panel).
A UI author MUST NOT assume window.McpApp is present — it is absent
outside host mode. Either of two conforming access patterns satisfies
this: a client library implementing the resolution order below, or an
explicit presence check with graceful degraded rendering when the bridge
is missing (the hand-written single-file pattern).
Runtime modes
A UI surface's client library resolves a connection through exactly
three modes, in this order, and MUST NOT throw merely because a mode
isn't available — only standalone failing to find a handler for a
called tool, or a present bridge itself failing, are real errors:
| Mode | When | How callTool resolves |
|---|---|---|
host | window.McpApp is already present (an MCP-Apps panel injected it, or a conforming serve verb did) | Passed straight through to the injected bridge. Terminal — host mode MUST NOT downgrade. |
bridge | No window.McpApp, but a same-origin POST /__agentproto/tool-call route exists | The library POSTs { name, args } to the route and unwraps the JSON response as the MCP result envelope. |
standalone | Neither of the above | The library dispatches to a caller-supplied mock handler for the named tool; a tool with no registered handler rejects. |
Resolution from bridge to standalone MUST be lazy and optimistic: a
client library MUST NOT perform an upfront network probe to decide
between them. It constructs a bridge-mode connection immediately and
only discovers whether the route is real on the first callTool —
a network failure, an HTTP 404, or a non-JSON response on that first
call permanently downgrades the connection to standalone and replays
that same call against the standalone handlers. Once a bridge
connection has had one call succeed, a later failure on that same
connection MUST be treated as a real error (the route existed and then
broke) — not a fresh signal to downgrade.
host mode connections are terminal from the start: a present
window.McpApp is authoritative and a rejection from its own
connect() MUST propagate as a real error, not trigger a fallback.
Result unwrapping
A client library's callTool<T>(name, args) MUST unwrap the raw MCP
tools/call envelope by this precedence:
envelope.isError === true→ reject with an error naming the tool and mode, carrying the concatenated text of everycontentblock as detail.envelope.structuredContentpresent → return it asT.- Else, if
envelope.contentis a non-empty array, take the first entry'stext:JSON.parseit and return the parsed value if it parses, else return the raw text. - Else (no content) → return an empty object.
This precedence is a frozen wire contract: structuredContent
always wins over content when both are present, and a single text
block that happens to be JSON is transparently parsed. A caller
supplies the expected result shape via the type parameter; the library
does not runtime-verify it matches.
The dev-bridge route
The reserved route POST /__agentproto/tool-call is the same-origin
(bridge-mode) surface a UI's client library targets by default. A
conforming server exposing this route MUST:
- Accept a JSON body
{ name: string, args?: object }; reject any other shape with HTTP 400. - Forward
{ name, arguments: args ?? {} }as an MCPtools/callthrough its own connection to the daemon (or equivalent tool dispatcher). - Return the raw MCP result envelope with HTTP 200 — including when
isErroris true. AnisErrorresult is a resolved call, not a transport failure; it MUST NOT be mapped to a non-2xx status, so a UI's unwrapping code (rule 1, above) behaves identically whether the error arrived viapostMessage(a host panel) or via this HTTP route. - Return a non-2xx status only for a genuine transport/dispatch
failure (bad request shape → 400; the daemon/tool-dispatcher
unreachable → 502; the tool call itself threw → 502) — never for a
well-formed
isErrorresult.
Tools allowlist enforcement
Every UI-originated tool call MUST be checked against the allowlist the
app declared at author time (ui.tools[]) before dispatch. A
conforming gateway (the reference implementation's app_tool_call
MCP tool, and its HTTP twin) MUST:
- Resolve the installed app by id; refuse with an error if the app
isn't installed or has no
uiblock. - Reject the call — without dispatching it — if the requested tool id
is absent from that app's
ui.tools[], naming the tool id and the full allowlist in the error. - Only once allowlisted, dispatch: a tool id prefixed
imported:<alias>/<toolName>MUST route through the named imported MCP server; every other id dispatches through the host's own registered tools.
This is the enforcement boundary that makes rule 5 of
Design principles real: the UI's reach is
exactly ui.tools[], never the installing agent's full tool surface,
and the check happens on every call — there is no session-level or
one-time grant that widens it.
The ui/ source-project convention
Separate from the emitted .agentproto/ui/ static tree, an app
directory MAY additionally contain a ui/ source project — a Vite +
TypeScript (or equivalent) project that builds into
.agentproto/ui/. This is a convention the reference tooling supports,
not a requirement this AIP imposes on every app:
- A hand-written single-file
.agentproto/ui/index.htmlwith noui/source project and no build step remains fully first-class — the common case for a simple dashboard. - When a
ui/source project exists (<appDir>/ui/package.jsonwith a"scripts.build"), the referenceagentproto app buildverb runs it and the output lands in.agentproto/ui/. Aui/project with no build script, or noui/project at all, is a no-op success forbuild— not an error. - When the
ui/project additionally has a"scripts.dev", the referenceagentproto app devverb runs that dev server directly (Vite HMR, its own port) alongside a bridge-only HTTP server (no static files, just the/__agentproto/tool-callroute with real CORS headers, since the dev server and the bridge are different origins). Aui/project without a dev script has nothing to hot-reload — the static build is served withagentproto app serveinstead.
A ui/ source tree's node_modules/ and .git/ are excluded from
.agentapp packaging (see pack) regardless of whether the
project ships a build step — they are never part of the shipped app.
The app data plane (app_data_*)
An installed app owns a durable, app-scoped data directory — the
plane its UI and agents persist state through (app_data_read,
app_data_write, app_data_list), distinct from the app's source
tree, which is whatever install/unpack wrote and is never
agent-writable by this contract. This section is normative. It codifies
shipped behaviour: packages/runtime/src/app-data.ts (its header
comment states the resolution rule verbatim, and
resolveAppDataPath/locateAppDataPath/atomicWrite implement it),
wired as MCP tools by registerAppDataTools in the same file.
Addressing
Every data-plane tool addresses files with an app-relative path —
never an absolute one. How a relative path p resolves is the contract
app UIs and agents rely on, and a second host MUST reproduce all four
rules (this is app-data.ts's locateAppDataPath, :79-113):
- Primary root is the app's persisted
dataDir. The installed-app record carriesdataDir, defaulted to<dir>/datafor records that predate the field. A custom root is set explicitly at install time (app_install { dataDir },agentproto app install --data-dir) or hinted byAPP.md'sdata: { dir }(relative to the app dir). The resolved absolute path is persisted on the installed-app record. - Legacy
data/spelling collapses under the default layout. WhendataDirIS<dir>/data(the default layout), a leadingdata/segment is redundant and dropped for reads and writes alike:data/trips/x.jsonandtrips/x.jsonname the same file. A customdataDiris a fresh, intentional layout — no collapse. The traversal guard still runs on the collapsed result, sodata/../../xis rejected exactly as../xwould be. - Legacy root fallback. If
p— or its top-level folder — does not exist underdataDirbut does under the app's sourcedir, it resolves underdir: reads find files written by pre-dataDirinstalls, writes update them in place (or land next to their siblings). Move the folder intodataDirand the fallback stops applying. Brand-new paths always land underdataDir. - Listing merges both roots. When the same directory also exists
under the source dir,
app_data_listmerges the two views, with data-dir entries winning on name clashes; listing.yields the data dir only (or the source dir while no data dir exists yet).
A conforming host MUST surface which root a path resolved under in its
diagnostics (legacy: true vs the data root), so an author can tell a
pre-dataDir file from a durable one.
The traversal guard
Both roots get the same defence, and it is the only path-escape defence
that matters. A conforming host MUST reject, with a named
traversal error (reference: AppPathTraversalError, code
APP_PATH_TRAVERSAL), any app-relative path that:
- is absolute (starts with
/or a drive root); - carries a Windows drive-letter prefix (
C:…), so a drive-based host can never misread it as a relative segment; - after
resolvecollapses./..segments, does not land on the root itself or strictly below it — a relative../../secretor a nesteda/../../bclimbs out of the app dir into unrelated host files, and containment-by-prefix comparison againstroot + separatoris the reliable check.
Additionally, for an existing target the host MUST realpath the
resolved path and assert it still lands inside the root — so a symlink
planted inside the data dir cannot point the plane outside it
(assertRealInside). Without that check the string-level guard above is
defeated by a single symlink. Both checks run on every tool call —
read, write, and list alike — there is no once-per-session grant.
The reference implementation rejects the offending call with the original relative path named in the error; a bare "invalid path" is not sufficient diagnostic detail (mirroring the loader rule above).
The atomic-write guarantee
app_data_write MUST write atomically: create parent directories
(mkdir -p), write the payload to a temporary sibling of the target
(<target>.tmp.<pid> in the reference implementation), then rename
it over the target. A reader therefore observes either the previous
contents or the complete new contents — never a partial write, even
under concurrent readers. There is no non-atomic write path to the data
plane. A missing data directory is created lazily by the write path, not
an error.
.json paths are a convention, not a separate store: reads of paths
ending in .json return the parsed value (falling back to raw text when
the bytes do not parse); writes JSON-serialize pretty-printed. Every
other path carries raw string content verbatim.
The state ledger (carve-out)
The reference implementation ships three additional tools rooted in the
same data dir — app_state_append, app_state_get, app_state_list —
implementing an append-only, ULID-ordered event ledger folded to
snapshots (app-state.ts). One access rule is normative here:
app_state_append MUST NOT be granted to spawned agent sessions and
MUST NOT be added to a UI's ui.tools[] allowlist by default — a UI
that needs to append (e.g. recording a human approval) must explicitly
list it. The other two are read-only and follow the normal allowlist
rules.
app_data_migrate (importing legacy ranked-jobs.json + dossiers/*
files into the durable shape) is reference behaviour, informative here —
a conforming host MAY ship its own migration story or none.
A future app_data_query tool over a store.sqlite inside the data dir
is reserved, not specified — one reason the data dir is separable from
the source tree.
Reference tooling (informative)
The reference implementation exposes an app's lifecycle through six CLI
verbs under agentproto app <verb>, none of which is itself normative
(the wire/file contracts above are); they are named here because the
UI-mode table and the dev-bridge route above assume their existence:
| Verb | Role |
|---|---|
pack | Directory → .agentapp (see pack) |
unpack | .agentapp → directory, SHA-256 verified (see unpack) |
serve | Serves .agentproto/ui/ standalone with an injected host-mode bridge to a running daemon's MCP endpoint — port resolution: --port > APP.md's ui.port hint > OS-assigned |
build | Builds a ui/ source project into .agentproto/ui/ (no-op success when there's nothing to build) |
dev | Runs a ui/ source project's own dev server plus a bridge-only server for live window.McpApp calls |
setup | agentproto app setup <appId> — runs / re-runs an installed app's setup[] pipeline (--force, --dry-run, --only) |
The daemon-side MCP tool surface is likewise reference behavior built on
top of the file contract this AIP fixes, not itself part of the
normative surface — a conforming alternative host MAY expose a different
install/run API as long as it honors the allowlist enforcement and
bridge contract above for any UI it renders. For orientation, the
reference daemon currently registers 22 app_* tools (grep
packages/runtime/src/app-tools.ts, app-data.ts, app-external.ts,
app-state.ts for the authoritative set):
| Tool | Role |
|---|---|
app_install | loadAppHandle(dir) → validate → persist an installed-app record |
app_list | List installed apps, each with a summary of its app_run history |
app_list_applied | List apps applied to a scope |
app_uninstall | Remove an installed app (refuses while runs are live) |
app_run | Spawn a session per selected agent |
app_status | Fan out an app_run's sessions plus the app's workflow runs |
app_stop | Kill every session in an app_run and mark the run ended |
app_apply / app_unapply | Bind / unbind an installed app to a scope |
app_tool_call | Allowlist-checked tool dispatch for UI-originated calls |
app_catalog | List catalog apps, including the builtin panels |
app_artifact_get | Fetch an app's artifact surface |
app_skill_get | Fetch an app's skill surface |
app_data_read / app_data_write / app_data_list / app_data_migrate | The data plane (see The app data plane) |
app_state_append / app_state_get / app_state_list | The app state ledger (see the data-plane carve-out) |
app_external_list / app_external_read | Read-only access to declared externalReadRoots outside the app dir |
agent_output (agent sessions' structured output) is part of the agent
toolset, not the app_* family, though app UIs commonly allowlist it.
Rationale
Why compose AIP-42/AIP-15 rather than define a new agent-collection primitive? ASSEMBLY (AIP-24) already names "a collective of agents." An app is a narrower, different concern: not how agents coordinate at runtime, but how a shippable, installable unit packages agents with the workflows they run and (optionally) a UI. An app's agents don't need an ASSEMBLY's voting/council/hierarchy modes — they need to round-trip through disk as one bundle a host can validate and hand to a user. Reusing AIP-42/AIP-15 handles directly, rather than re-declaring agent/workflow shape inside APP.md, keeps the two concerns orthogonal: an app can bundle agents that also participate in an ASSEMBLY elsewhere.
Why the attachment invariant in both directions? A one-directional
check (agent → workflow) would allow orphaned workflows to accumulate
silently in a bundle nobody's agent actually drives — dead weight that
still ships in every .agentapp. Checking the reverse direction too
(every bundled workflow has a referencing agent) keeps a bundle's
contents legible: everything present is reachable from an agent.
Why is .agentapp's checksum an aggregate hash over sorted
concatenated bytes, not a per-file manifest of digests? A per-file
manifest ({path: sha256} for every file) is more granular — it can
name which file changed on a mismatch — but for an app-sized bundle
(dozens of files, not thousands) that granularity isn't worth the
larger manifest and the extra hashing bookkeeping. One aggregate digest
over a fixed sort order is simpler to implement correctly on both
sides and is sufficient to answer the one question unpack needs
answered: is this bundle exactly what pack produced.
Why node_modules/.git exclusion instead of a .agentappignore
file? A ui/ source project's node_modules can be gigabytes and is
always regenerable (npm install); a .git directory is never part of
a shipped app under any circumstance. Both are unconditional excludes
because there is no scenario where either belongs in a .agentapp —
adding a general ignore-file mechanism for a two-item, always-true
exclusion list is unwarranted complexity. A future revision MAY add
general ignore rules if a real second case emerges.
Why does host mode never downgrade but bridge mode does? A
present window.McpApp is an explicit signal from a host that chose to
inject it — if its connect() then fails, that is the host
malfunctioning, not "no bridge here." Silently falling back to
standalone in that case would hide a real host-side bug behind mock
data. bridge mode, by contrast, starts from no signal either way
(no injected global, just an assumption that the well-known route might
exist) — so discovering it doesn't is exactly the "no bridge, use
standalone" case the mode ladder exists to handle gracefully.
Why must isError results return HTTP 200 from the dev-bridge
route? The whole point of the runtime-mode contract is that a UI's
callTool unwrapping code behaves identically across host and
bridge mode. A host panel's postMessage-based tools/call reply
resolves (doesn't reject the transport promise) even when the tool
itself reports isError: true — only Result
unwrapping rule 1 turns that into a rejected
callTool promise, at the library layer, not the transport layer.
Mapping isError to a non-2xx HTTP status in bridge mode would make
the two mode's error-handling diverge exactly where they need to agree.
Why a setup[] field instead of a post-install script or a setup
workflow? A script is opaque: a host cannot tell what it will ask,
whether it already ran, or which part to re-run, and it is arbitrary
code on a third-party app. A workflow (AIP-15) models agent work, not
one-time human bindings, and cannot be resumed per step or fingerprinted
across versions. A declared, typed pipeline gives the host a ledger, a
consent point for the one dangerous kind (cmd), a native UI per kind,
and the ready / setup_required distinction that lets a headless
caller stop cleanly instead of hanging on a prompt.
Why reuse the AIP-29 shape? Because the engine already exists
(skip_if, persist, the per-slug ledger, --force / --only /
--dry-run). An app's setup differs in what it asks for, not in how
steps are ordered, skipped, persisted or resumed, so inventing different
semantics would force hosts to maintain two. The new kinds (choice,
auth-profile, pairing, check) exist only where a shell command or
a bare prompt cannot express the behaviour portably: a closed option set
with branching, a threshold on the host's own credential store, a
one-time code that must be single-use and expiring, and a probe that
must never mutate.
Why fingerprints in the ledger? Without them a host can only choose between re-asking everything when an app updates and never noticing a changed step. Hashing the step definition re-runs exactly what changed.
Why is setup host-owned UI, with the app's ui unable to answer?
The ui surface is third-party JavaScript (see the allowlist
discussion in Security considerations). Letting it complete a pairing or
read a token would hand a compromised page the credentials setup exists
to protect.
Backward compatibility
requires object form and requires.apps[].tools amendment
(2026-11-08). Purely additive: an APP.md whose requires is a list of
app ids is unaffected and keeps its meaning, a dependency only with
nothing granted. The object form, the object apps entry with version
and workflows, and tools are new and OPTIONAL. A host built against
the earlier schema rejects an APP.md whose requires is an object
rather than ignoring it, which is the intended fail-safe: an app whose
agents need granted tools must not be installed by a host that would run
them without those tools. Installing an app whose provider is missing now
succeeds with the dependency reported. The schema: app/v1 string is
unchanged.
exposes amendment (2026-11-08). Purely additive: exposes is a new
OPTIONAL frontmatter field, and an APP.md without it is unaffected. An
app that declares none of prefix, tools and resources registers
nothing on a host's MCP gateway, and no tool of an app becomes visible to an
MCP client by default: a manifest has to name each one with its access
class. A host built against the earlier closed schema rejects an APP.md
that carries exposes rather than ignoring it, which is the intended
fail-safe: an app that publishes tools must not be installed by a host that
would drop the access classes. The schema: app/v1 string is unchanged.
services[].activation amendment (2026-11-03). Purely additive:
activation is a new OPTIONAL key of a service entry, and a service
without it is kept running exactly as before. A host built against the
earlier closed schema rejects a service that carries activation rather
than ignoring it, which is the intended fail-safe: a service that needs
the host to own its port must not be installed by a host that would start
it as a keep-alive process on its own, or the other way round. For an
on-demand service, port stops being bookkeeping only: the host holds
it and passes the process another one in PORT. The schema: app/v1
string is unchanged.
services[].expose amendment (2026-11-02). Purely additive: expose
is a new OPTIONAL key of a service entry, and a service without it is
unaffected. A host built against the earlier closed schema rejects a
service that carries expose rather than ignoring it, which is the
intended fail-safe: an app that needs a public URL must not be installed
by a host that would silently leave it unreachable. The schema: app/v1
string is unchanged.
setup[] amendment (2026-10-18). Purely additive: setup is a new
OPTIONAL frontmatter field, no existing field changes meaning, and an
APP.md without it is unaffected and is ready on install exactly as
before. The one visible effect is deliberate: a host built against the
earlier closed schema rejects an APP.md that carries setup rather
than ignoring it (see Schema note). The schema: app/v1 string is unchanged. agentproto setup <slug> gains an
installed-app-id form; the adapter form is untouched.
The remainder of this section describes the original AIP: not applicable — this AIP introduces a new spec canonizing bundle,
package, and UI-bridge conventions that already shipped as working code
(@agentproto/app's defineApp/emitApp/loadAppHandle, the CLI's
app pack/unpack/serve/build/dev verbs, @agentproto/app-client's
connectMcpApp, and the daemon's app_* tool family). No prior AIP
claimed the app/v1 or agentapp/v1 schema strings or the
.agentproto/ bundle layout, so there is nothing to migrate from or
supersede.
Security considerations
-
An exposed service is on the internet. A tunnel is an outbound connection, so the host's address is never published and nothing listens on a public interface; but anyone who holds the URL reaches the service.
auth: guardkeeps the host's guard in front of it.auth: serviceremoves it: a host SHOULD show that choice to the user at install, and the service is then the only boundary. -
exposes.toolsis a second, separate boundary: the app's reach toward MCP clients. The class on each entry decides who sees the tool, so a host MUST apply the visibility rule on every call path, not only when it lists tools, and a manifest MUST NOT be able to widen it. Animported:entry forwards to a server the app does not control: onlyreadis allowed, the result is returned unchanged, and the input is cut down to the keysinputSchemadeclares, which is how an app keeps a foreign tool's file-writing or otherwise dangerous argument out of reach.exposes.resourcesis an allowlist and not a filter: a host MUST NOT relay a URI that is not in it, and MUST NOT relay a server's fullresources/list. No exposed tool can decide an approval (see Why approval tools are refused). -
The UI tools allowlist is the primary security boundary. A UI surface runs arbitrary, often third-party-authored, JavaScript inside a page the host renders. Without allowlist enforcement (see Tools allowlist enforcement), that JavaScript would inherit the full tool reach of whatever installed the app. Hosts MUST enforce the allowlist on every call, server-side — a client-side-only check is not a boundary, since the page's own script is exactly what a hostile or compromised UI controls.
-
imported:<alias>/<toolName>widens the surface a UI can reach into an external MCP server. A host wiringcallImportedToolMUST apply the same allowlist discipline to imported-tool ids as to native ones —ui.tools[]is the single allowlist for both namespaces, not two separate trust levels. -
A CORS-permissive dev bridge is a local-only surface.
app serve's andapp dev'sAccess-Control-Allow-Origin: *is deliberate for a bare local-loopback tool-call route with no cookies or session state — but implementers reusing this route pattern behind anything other than127.0.0.1MUST NOT keep the wildcard origin, since it would let any page on the internet POST tool calls through a reachable bridge. -
csp.connectDomains/csp.resourceDomainsare declared, not enforced by this AIP.AppUiDefinition.cspnames the domains a UI intends to reach; a conforming host SHOULD translate this into an actual Content-Security-Policy header/meta tag when serving the UI, but this AIP does not itself mandate the enforcement mechanism — only that the declaration exists and is carried throughemit/loadAppHandleunmodified. -
servicesstart host-side processes with no consent step. A service is a command line the app's author chose, run with the host's environment and privileges as soon as the app is installed. Unlike acmdsetup step, this AIP defines no consent gate for it, so installing an app from an untrusted source is installing code to run. A host SHOULD show the declared services of an app before installing it, and SHOULD NOT resolve acwdoutside the app directory. -
An
on-demandservice lets a request start a process. The host's listener is loopback-only and every request that reaches it can start the process, so withauth: serviceanyone who holds the URL can cost the host a process start. The backoff of Activation rule 6 stops a crashing service from being started at the rate requests arrive, and the refusal body carries no internals (rule 3). The processPORTis also reachable on any interface it binds: a service that binds all of them exposes itself without the host in front, which is why rule 2 says SHOULD bind the loopback interface only. -
.agentappintegrity is checksum, not signature. The aggregate SHA-256 (seeunpack) detects corruption and accidental tampering but is not a cryptographic signature — it proves the bundle matches what its ownmanifest.jsonclaims, not that the claimedid/version/agentprotoVersioncame from a trusted publisher. A registry distributing third-party.agentappfiles SHOULD layer a signing scheme on top; this AIP does not define one. -
The data plane's traversal guard is a security boundary, not a convenience.
app_data_*paths resolve strictly inside the app's data dir (or legacy source dir); hosts MUST enforce the resolve-and-realpath containment checks of The traversal guard on every call — the string-level check alone is defeated by a single symlink. -
app_installvalidates workflow tool ids, not agent tool ids. The reference install path cross-checks everyWORKFLOW.mdtoolstep's id against the host's dispatchable tools (surfacing all missing ids at once), but explicitly does NOT validate an agent's own declaredtools[]— those are the chosen agent adapter's business (e.g. workspace tools likeread_fileamastra-agentadapter resolves independently). Implementers relying onapp_installsucceeding MUST NOT read that as a guarantee every agent-declared tool ref is resolvable;unvalidatedAgentToolson the install result names exactly which refs were skipped. -
setup[]cmdsteps are arbitrary code execution at install time. An app from a catalog or a git URL is third-party content, and acmdstep (andskip_if.cmd,persist.cmd,check.cmd) runs with the user's privileges. A host MUST show the verbatim command text of every pendingcmd-bearing step and obtain explicit consent before running any of them;--yesMUST NOT imply that consent (reference: a dedicated--allow-setup-cmdflag, in the same spirit as the--allow-buildgate onui.build). Without consent the step is left pending and the install reportssetup_consent_required. The other kinds do not execute app-supplied code:prompt,choice,auth-profile,pairingandcheck.toolare mediated entirely by the host.check.toolMUST be limited to tools the host would let this app call anyway. -
Secrets in setup never enter the ledger, the answers map, logs or the app's UI.
type: secretinput is masked by the host surface and lands only insecret_slug/env(persist.answeris forbidden for it). Apairingcode is single-use and short-lived, and the bound chat identity is stored by the host, never in the ledger. AnexternalurlMUST behttpsand MUST be shown to the user in full before it is opened. Because the app'suicannot answer a step, a compromised UI cannot complete a pairing or read a token. -
requires.apps[].toolswidens what the consumer's agents can do, and nothing else. Installing a consumer that grants itself a provider'swritetools gives that consumer's agents the provider's side effects, so a host SHOULD show the granted names and their access classes before install, as it shows services. The grant cannot reach past the provider's ownexposes.tools, cannot raise an access class, cannot reach the consumer's UI or any other caller, and cannot skip an approval. Attribution of a session to the consumer is the host's, made when it starts the session from one of the consumer's AGENT.md files; a host MUST NOT accept an app id a caller supplies about itself as the basis of a grant. -
extends-style cross-app trust is out of scope for v1. Unlike AGENT.md'sextends, an app has no inheritance mechanism in this AIP.requiresnames a dependency relationship, and itsworkflowsandtoolslet the consumer use the provider's exposed surface through the host, but it does not pull in or execute the provider's code inside the consumer. There is therefore no parent-SHA-pinning concern analogous to AIP-42's for apps in v1.
Open questions
-
Signing and provenance.
.agentappintegrity today is a checksum, not a signature (see Security considerations). A future revision may define a signing envelope, likely composing with whatever AIP-19 SECRETS-adjacent identity primitive is chosen for publisher keys. -
UI framework conventions beyond Vite. The
ui/source-project convention (package.jsonwithscripts.build/scripts.dev) is deliberately tool-agnostic in principle but the reference tooling'sdetectPackageManagerand dev-proxy env var (AGENTPROTO_BRIDGE_URL) were designed against a Vite-shaped dev server. Whether other bundlers need first-class support, or whether the convention already generalizes, is open. -
Multi-UI apps.
AppDefinition.uiis singular — one UI surface per app. Whether an app should be able to declare multiple named UI entry points (e.g. an admin view and an end-user view) is deferred until real demand appears. -
Version ranges beyond exact, caret and tilde.
requires.apps[].versionaccepts three shapes. Whether compound ranges (>=1.2 <2,||) are worth a larger grammar is open until an app needs one. -
Setup
choiceof a different shape.choiceoptions carry no per-option sub-steps; branching is expressed withwhen. Whether nested options or option-scopedrequiresare worth the extra surface is open, as is a typedpairingpayload for channels other thantelegram(WhatsApp, Discord) once a second implementation exists. -
Declared
setupin a catalog entry. A host could show a catalog entry's pending setup (which secrets, which pairings, anycmd) before install, from the entry alone. Today it is visible only afterAPP.mdis read.
See also
- AIP-14 — TOOL.md — the tool contract
ui.tools[]allowlists against and agents declaretools[]from - AIP-15 — WORKFLOW.md — the workflow primitive an app bundles; the other half of the attachment invariant
- AIP-34 — WORKSPACE.md — the optional home workspace an
app MAY declare via
workspace - AIP-42 — AGENT.md — the agent primitive an app
bundles;
AgentEntry.bodyfills the AGENT.md body this AIP's frontmatter carries no equivalent field for - AIP-24 — ASSEMBLY.md — the multi-agent coordination primitive this AIP deliberately does not duplicate (see Rationale)
- AIP-29 — CLI.md (agentcli/v1) — the
setupblocksetup[]is modelled on (step kinds,skip_if,persist, ledger) - AIP-19 — SECRETS — where a future
.agentappsigning scheme would anchor publisher identity (see Open questions)
Resources
Supporting artifacts for AIP-53. Links open the file on GitHub — markdown and JSON render natively in GitHub's viewer. Browse the full resource tree →
AIP-52: BRIDGE (bridge/v1): outward framework bridge
The outward mirror of AIP-30 DRIVER — the contract for projecting an agentproto handle (TOOL, AGENT, PROCESSOR) into a foreign framework runtime (Mastra, AI SDK, LangChain, a CLI) so it runs as a native citizen there. Names the pattern, fixes conformance rules (frontmatter precedence, schema fidelity, degradation reporting, no credentials), and canonizes the existing resources/ADAPTER.md implementer-guide convention.
AIP-54: REF (ref/v1): typed cross-AIP artifact reference
One typed, cross-AIP reference shape — `{aip, id, version?}`, serialized as an `aip://<aip>/<id>[@version]` URI — that any AIP artifact can use to point at any other AIP artifact, resolved through per-family AIP-43 registries joined by a RefCatalog, plus the `ws://<collection>/<body>` scheme for pointing at resources in the world (files, URLs, identities, transactions) — superseding AIP-27, which owned both jobs separately. Replaces every per-primitive reference mechanism (AIP-18's collection-scoped `refKind`, inline doctype handles, bare id strings) with one discriminated, resolvable, loudly-failing reference.