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.

FieldValue
AIP53
TitleAPP (app/v1): agent app bundle + UI surface
StatusReview
TypeSchema
Domainapps.sh
RequiresAIP-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:

  1. Agents and workflows composed only by convention. AGENT.md (AIP-42) declares a workflows[] ref list and WORKFLOW.md (AIP-15) declares kind: agent steps 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.

  2. 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 install at and get a validated, runnable whole.

  3. UI surfaces had no bridge contract. Several daemon-side app UIs shipped ad hoc (packages/runtime/src/*-app.ts in 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 reinvented window.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.

  4. 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

  1. Bundle, don't redefine. An app's agents and workflows are ordinary defineAgent / defineWorkflow handles. defineApp adds 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.

  2. 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's workflows[]. A dangling ref and an orphaned workflow are both errors — "attached" means checkable both ways, not merely "shipped in the same folder."

  3. 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.

  4. The UI is a static surface, not a server. ui.html is a single document emit writes verbatim to .agentproto/ui/index.html. There is no build step in the contract itself — a hand-written single-file UI is first-class. A ui/ source project (Vite, TypeScript) that builds into .agentproto/ui/ is a separate, optional convention (see The ui/ source-project convention), not a requirement.

  5. 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.

  6. The bridge degrades gracefully, never silently wrong. A UI's client library resolves, in order, to host mode (an injected window.McpApp), bridge mode (a same-origin dev-proxy route), or standalone mode (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.

  7. Packaging is verifiable, not just portable. A .agentapp carries 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

  1. Non-empty agents, unless ui. agents MUST contain at least one entry UNLESS ui is present. A UI-only app — a ui block with an empty or omitted agents array — is conforming. An app with zero agents AND no ui block is not a conforming AppDefinition — defineApp MUST refuse it. This rule codifies shipped behaviour: packages/app/src/define-app.ts:60-64 accepts (agents empty || omitted) && ui === undefined as 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.

  2. Unique agent ids, unique workflow ids. Two bundled agents MUST NOT share an id; two bundled workflows MUST NOT share an id. defineApp MUST refuse a definition that violates either.

  3. The attachment invariant, both directions. For every agent in the bundle, every ref in that agent's workflows[] MUST resolve to the id of a workflow the same app bundles. For every workflow the app bundles, at least one agent's workflows[] MUST reference it. defineApp MUST 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.

  4. id non-empty when present. id MUST be a non-empty string when set. Setting id is what makes the app installable/discoverable — emit writes it into APP.md's identity block, and a host's install path (app_install) refuses a handle with no id. An app MAY omit id and remain a valid, emittable, runnable-in-process bundle; it simply cannot be installed by id.

  5. ui.html non-empty when ui is present. defineApp MUST refuse a ui block whose html is missing or empty.

  6. dev.launch non-empty when dev is present. Same shape of rule for the optional dev-launch config.

  7. artifact.path / skill.path non-empty when present, and both MUST be absolute filesystem paths — emit copies from them at write time and a relative path has no defined base to resolve against.

  8. Version default. When id is set and version is omitted, defineApp MUST default version to "0.1.0". An anonymous bundle (no id) carries no default version.

  9. No I/O at defineApp time. Constructing an AppHandle via defineApp MUST NOT perform filesystem or network I/O. I/O is confined to emit(dir) (write) and loadAppHandle(dir) (read) — the mirror pair every doctype in the AIP series keeps separate from its pure defineX constructor.

  10. setup step ids unique, references backward. When setup is present it MUST be non-empty, every step id MUST be unique within it, and every when.step MUST name a step declared EARLIER in the array. defineApp MUST refuse a definition that violates any of these, and MUST refuse a choice whose default is not the value of one of its options, a step with more than one persist slot, and a persist.answer on a type: secret prompt. Like rule 9, validating setup performs no I/O: nothing in setup is executed or contacted until a host's install path runs it (see Setup steps).

  11. services non-empty, names unique, one launch form each. When services is present it MUST be non-empty and every name MUST be unique within it. Each entry MUST declare exactly one of entry and command; args MUST NOT be set alongside entry. An entry that sets expose MUST set port, and expose MUST carry only auth (guard or service) and hostname. An entry that sets activation MUST give it a mode of always or on-demand; mode: on-demand MUST come with a port, and idleStopMs and startTimeoutMs MUST NOT be set with mode: always (see Activation for their bounds). defineApp and the loader MUST refuse a definition that violates any of these. Like rules 9 and 10, validating services performs no I/O: nothing in services is executed or contacted until a host's install path starts it (see Services).

  12. exposes is closed and checked at load. When exposes is present it MUST be an object with no key besides agents, workflows, prefix, tools and resources. Every agents and workflows entry MUST name an agent, respectively a workflow, the app declares. A non-empty tools MUST come with a prefix matching ^[a-z][a-z0-9]{1,15}$. Each entry of tools MUST have a unique id, an access of read, write or approve, a non-blank description of at most 300 characters, and no key besides id, access, description, inputSchema, mcpName and approvalArg; approvalArg MUST NOT be set unless access is approve; no id or mcpName may start with approval; an imported: id MUST have an mcpName and access: read; a bundled id MUST resolve to a TOOL.md the app bundles, which MUST NOT declare mutates or carry a mutator or write tag when the entry is read; two entries MUST NOT compute the same MCP name, and a computed name MUST NOT exceed 64 characters. A non-empty resources MUST hold distinct ui:// URIs and MUST come with at least one imported: entry in tools. defineApp and 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).

  13. requires takes one of two forms, and apps entries are closed. When requires is present it MUST be either an array of non-empty strings or an object with no key besides browser, fs, gpu, secrets and apps, where browser, fs and gpu are booleans and secrets is an array of non-empty strings. Each apps entry MUST be a non-empty string or an object with a non-empty id and no key besides id, version, workflows and tools; two entries MUST NOT name the same id. version MUST be an exact, caret or tilde range, workflows an array of non-empty strings, and tools an array of MCP names (<prefix>_<n>, at most 64 characters). defineApp and the loader MUST refuse a definition that violates any of these. Checks that need the installed provider (every tools name 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:

  1. Reject frontmatter whose schema is not exactly "app/v1".

  2. Reject agents/workflows frontmatter that is not an array of { id: string, path: string }.

  3. Resolve every { id, path } ref against dir (relative paths are joined to dir; absolute paths pass through) and load each AGENT.md via the AIP-42 manifest reader and each WORKFLOW.md via the AIP-15 loader.

  4. When workspace names an id, read the sibling <dir>/WORKSPACE.md and parse it via the AIP-34 manifest reader.

  5. 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-edited APP.md whose refs drifted from its AGENT.md / WORKFLOW.md files MUST fail to load, the same way a bad defineApp({...}) call fails to construct.

  6. When setup is 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 in setup.

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.

kindOriginPurposeRequired fields
cmdAIP-29Run a shell command.cmd
promptAIP-29Ask for one value: type: text | select | boolean | secret.prompt
oauthAIP-29Drive an AIP-19 OAuth flow; tokens land in the named secret slug.secret_slug
externalAIP-29Open an https URL and wait for the user.url
choicenewPick exactly one of a closed set of options, with a default.prompt, options, default
auth-profilenewEnsure the host holds enough usable model-login profiles.none
pairingnewBind an external chat identity to this install (a QR, link or code the user acts on elsewhere).channel
checknewA read-only readiness probe. Never prompts, never mutates.check
x-*vendorHost- or vendor-specific extension (see Schema note).id, kind

Common fields

  • id (REQUIRED) — kebab-case, unique within setup[]. It keys the ledger, audit records and --only.
  • title, description (optional) — what a surface shows above the step.
  • optional (optional, default false) — the user MAY decline the step, or leave it pending, without blocking ready. A declined optional step is ledgered declined and is not re-offered by an unattended run, only by an explicit setup re-run.
  • when (optional) — { step, equals } or { step, done }. The step runs only if the earlier step step recorded the answer equals, or is / is not complete (done: true | false). A step whose when is false is ledgered not-applicable and never blocks ready. when.step MUST name an earlier step.
  • skip_if (optional, cmd and prompt) — 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_slug and cmd are exactly AIP-29's. This AIP adds answer: <dotted.key> for NON-SECRET values: the value is recorded under answers.<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). answer MUST NOT be used with type: secret; a secret MUST land in secret_slug or env.

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
  1. 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.
  2. If setup is present and any non-optional, applicable step is unsatisfied, the install result reports setupState: "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).
  3. A host MUST refuse app_run for an app that is not ready, with error.code = "setup_required" and the pending step ids. app_apply MAY still bind the app to a scope; readiness gates running it, not applying it. Apps without setup are ready on install, exactly as before.
  4. Re-run is agentproto app setup <appId> [--force] [--dry-run] [--only <stepId>].... The existing agentproto 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.
  5. Update (app_resync and equivalents) re-evaluates the ledger by fingerprint, as above, and reports setupState: "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.codeWhen
setup_requiredapp_run on an app with unsatisfied non-optional steps. Carries the pending ids.
setup_failedA step errored or a required check failed. Carries the step id.
setup_unsupported_stepThe 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_requiredA 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: 600000

Each entry is an object with exactly these keys; any other key is rejected.

FieldRequiredMeaning
nameyesService 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.
commandone of command / entryStructured form (preferred). A non-empty string: the binary or script to run, passed as argv[0] and never interpreted by a shell.
argsnoStructured form only. A non-empty array of strings, the argv after command, passed verbatim. Not valid alongside entry.
entryone of command / entryLegacy form. A non-empty shell command line, run by the host as sh -c <entry>. Use command unless you need shell syntax.
cwdnoWorking directory, a non-empty path relative to the installed app directory. Defaults to the app directory.
portnoThe 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).
exposenoAsk the host for a public URL that reaches this service's port. An object, see Exposure. Requires port. Omitted means the host publishes nothing.
activationnoWhen 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:

  1. 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-demand service, starting means taking the listening side of its port; the process itself starts later (see Activation).
  2. 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.
  3. 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.
  4. Environment. A service runs with the host's environment. A relative cwd is resolved against the installed app directory. The reference host sets AGENTPROTO_SESSION_ID to 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-file keeps a variable that is already set). A service SHOULD NOT use that name for its own configuration.
  5. 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.
  6. Boot. When the host itself starts, it SHOULD re-establish the services of every installed app that declares them.
  7. 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.

FieldRequiredMeaning
authnoWho 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.
hostnamenoA 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:

  1. No expose, nothing public. A host MUST NOT publish a service that does not declare expose. Such a service SHOULD bind the loopback interface.
  2. One tunnel per exposed service, stable key. The host creates an AIP-73 tunnel whose key is derived from the app id and the service name (see Tunnel key below), whose service is http://127.0.0.1:<port>, and whose hostnames is [hostname] when hostname is set. Because create is idempotent on the key, a reinstall or a host boot gets the same tunnel back, and the same URL when the provider has stableUrl. A host SHOULD use a provider with stableUrl: true; when it falls back to one without, it MUST report the exposure as not stable.
  3. 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) in AGENTPROTO_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 (expose added to a running service, or a provider that handed out a new URL), the host restarts the process so it sees the new value.
  4. 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.
  5. 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. With auth: service, the host MUST present the exposure as public wherever it reports it.
  6. Status. For each exposed service the host reports the public origin, auth, whether the URL is stable, and the tunnel state.
  7. 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 expose stops the connector and deletes the tunnel (AIP-73 delete).
  8. 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 for auth: 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.

FieldRequiredMeaning
modeyesalways (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.
idleStopMsnoon-demand only. An integer from 1000 to 86400000, default 300000: how long the service stays up after its last open request or connection ended.
startTimeoutMsnoon-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:

  1. The host owns the port. At install and at boot the host listens on port on 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).
  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 on PORT, SHOULD bind the loopback interface only, and cannot bind the declared port, which the host holds. A service that hardcodes its port cannot be on-demand.
  3. 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 after startTimeoutMs, the host answers every waiting request 503 Service Unavailable with a Retry-After header. The response MUST NOT carry the cause (command, path, error text); that goes to the host's log.
  4. 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. An Upgrade request (WebSocket) is forwarded and the connection becomes an opaque byte stream. The process sees what it would have seen listening on port itself. When the process has accepted the connection but fails, the host answers 502 Bad Gateway.
  5. 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.
  6. 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 503 and Retry-After for 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.
  7. 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. With auth: guard, a request the guard refuses never reaches the listener and starts nothing; with auth: service whoever holds the URL can start the process. AGENTPROTO_PUBLIC_URL is 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.
  8. 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 always and on-demand replaces 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.
  9. 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.
  10. Status. The host reports each on-demand service's state: idle, starting, running or stopping.

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/screenshot

agents 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:

  1. Take mcpName when set, otherwise id.
  2. Remove one leading <prefix>. or <prefix>_.
  3. Replace every character outside [a-zA-Z0-9_-] with _, merge runs of _, and trim one leading and one trailing _.
  4. 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 prefix that is the first _ segment of one of its own tool names (a prefix app would claim the app_* family), and refuse an id that 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 tools use a prefix another 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.

  • id is non-empty. It is the id of a TOOL.md the app bundles, or imported:<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.
  • access is one of read, write, approve (see below).
  • description is 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.
  • approvalArg is a non-empty string and MUST NOT be set unless access is approve.

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

accessMeaningDefault visibility
readObserves, changes nothingEvery caller
writeChanges data or has side effectsOnly a caller that opted in
approveTakes part in a human decision, for example a tool that carries an approval referenceOnly 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:

  • mcpName is REQUIRED. The loader MUST refuse an imported: entry without it;
  • access MUST be read. 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 CallToolResult as it received it: every content block (images included), structuredContent, isError and _meta. It MUST NOT wrap, re-encode or rewrite them. A value that is not a CallToolResult (it has no content array) MAY be wrapped as a single text block. A bundled tool answers with its output as one JSON text block.
  • _meta.ui is 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 in tools/list, with its resourceUri unchanged. A host that cannot read the import's tool list in time MAY list the tool without it. The host copies ui only; other _meta keys of the listing are not forwarded.
  • Undeclared inputs are dropped. See inputSchema below.

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/read for each by relaying it to the app's imported servers (the aliases of its imported: entries, in the order they are declared, the first one that answers wins);
  • refuse a resources/read for 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:

KeyTypeMeaning
browserboolean, default falseNeeds the user's real browser.
fsboolean, default falseNeeds the user's local filesystem beyond the app data dir.
gpuboolean, default falseNeeds a GPU.
secretsstring[], default []Env or secret names the app needs.
appsentry[], 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.

  • id is the provider's APP.md id, matched exactly.

  • version is 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.md version pattern);
    • a caret, ^1, ^1.2 or ^1.2.3: at least that version, and the same leftmost non-zero component, so ^1.2 accepts 1.9.0 but not 2.0.0, ^0.3 accepts 0.3.7 but not 0.4.0, and ^0.0.4 accepts only 0.0.4;
    • a tilde, ~1, ~1.2 or ~1.2.3: at least that version, the same major, and the same minor when a minor is written, so ~1 accepts 1.9.0 and ~1.2 accepts 1.2.9 but not 1.3.0.

    Missing components count as 0. A suffix on the installed version is ignored when comparing, so 1.2.3-rc1 satisfies ^1. Omitting version accepts any installed version. A provider with no recorded version satisfies no range.

  • workflows is the allowlist for app_call, the call a consumer makes to run one of a provider's workflows. Each entry is a workflow id from the provider's exposes.workflows. Omitted or empty, the consumer may call no workflow of that provider.

  • tools lists 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 write or approve tool, 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:

  1. Every name is exposed. When the provider is installed, each tools entry MUST equal the computed MCP name of one of its exposes.tools entries. Otherwise the host MUST refuse to install or reload the consumer, with an error that names the entry by index and the provider, for example requires.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.
  2. 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.
  3. At the provider's access class. A granted tool keeps the access the provider declares. The consumer cannot raise or lower it, and the entry carries no access of its own. A read tool is already visible to every caller, so granting it changes nothing; a write or approve tool becomes visible and callable for the consumer's agents.
  4. Approvals still apply. A granted approve tool 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.
  5. 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.
  6. The version range gates the grant. When the entry sets version and the provider's installed version does not satisfy it, the host grants nothing from that entry and reports it (see below).
  7. 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:

  1. Parse APP.md's frontmatter into bundle metadata: id (falling back to a slug field, then the literal string "app"), version (falling back to "0.1.0"), name, description, the agents[] / workflows[] id lists, and the basenames of any ui / artifact / skill paths.
  2. Walk the entire <appDir> tree and collect every regular file as a path relative to <appDir>, skipping any directory named node_modules or .git at any depth — a ui/ source project ships both, and neither belongs in a shipped app.
  3. Sort the collected file list lexicographically by path.
  4. 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.
  5. Write a manifest.json (schema below) at the bundle root.
  6. Tar (tar -czf) the app directory's contents (not the directory itself, so extraction yields manifest.json + .agentproto/ + any loose files at the top level) into the output .agentapp file. Without an explicit output path, the default is <safe-id>-<version>.agentapp in 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:

  1. Extract the archive to a fresh temporary directory.
  2. Require a manifest.json at its root; a bundle without one is not a valid .agentapp and MUST be refused.
  3. Require manifest.format === "agentapp/v1"; any other value MUST be refused with the actual format named in the error.
  4. Recompute the aggregate SHA-256 over the files listed in manifest.files, in the order listed, and compare against manifest.sha256. A mismatch MUST refuse the unpack — the bundle is corrupted or was tampered with, and unpack MUST NOT silently restore it anyway.
  5. Only once the digest verifies, remove manifest.json from 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:

  1. index.html is the entry point. A conforming host serving a UI surface MUST treat .agentproto/ui/index.html as the document to return for the root path and for any directory-style request.
  2. 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 via file://. Absolute root-relative paths (/app.js) are non-conforming; ./app.js or app.js are required.
  3. 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's pushState, since a static file server has no fallback rule to reroute a deep-linked path back to index.html.
  4. A ui/ source directory is a distinct, optional thing from the emitted .agentproto/ui/ — see The ui/ 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 MCP tools/call result 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:

ModeWhenHow callTool resolves
hostwindow.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.
bridgeNo window.McpApp, but a same-origin POST /__agentproto/tool-call route existsThe library POSTs { name, args } to the route and unwraps the JSON response as the MCP result envelope.
standaloneNeither of the aboveThe 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:

  1. envelope.isError === true → reject with an error naming the tool and mode, carrying the concatenated text of every content block as detail.
  2. envelope.structuredContent present → return it as T.
  3. Else, if envelope.content is a non-empty array, take the first entry's text: JSON.parse it and return the parsed value if it parses, else return the raw text.
  4. 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:

  1. Accept a JSON body { name: string, args?: object }; reject any other shape with HTTP 400.
  2. Forward { name, arguments: args ?? {} } as an MCP tools/call through its own connection to the daemon (or equivalent tool dispatcher).
  3. Return the raw MCP result envelope with HTTP 200 — including when isError is true. An isError result 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 via postMessage (a host panel) or via this HTTP route.
  4. 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 isError result.

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:

  1. Resolve the installed app by id; refuse with an error if the app isn't installed or has no ui block.
  2. 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.
  3. 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.html with no ui/ 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.json with a "scripts.build"), the reference agentproto app build verb runs it and the output lands in .agentproto/ui/. A ui/ project with no build script, or no ui/ project at all, is a no-op success for build — not an error.
  • When the ui/ project additionally has a "scripts.dev", the reference agentproto app dev verb runs that dev server directly (Vite HMR, its own port) alongside a bridge-only HTTP server (no static files, just the /__agentproto/tool-call route with real CORS headers, since the dev server and the bridge are different origins). A ui/ project without a dev script has nothing to hot-reload — the static build is served with agentproto app serve instead.

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):

  1. Primary root is the app's persisted dataDir. The installed-app record carries dataDir, defaulted to <dir>/data for records that predate the field. A custom root is set explicitly at install time (app_install { dataDir }, agentproto app install --data-dir) or hinted by APP.md's data: { dir } (relative to the app dir). The resolved absolute path is persisted on the installed-app record.
  2. Legacy data/ spelling collapses under the default layout. When dataDir IS <dir>/data (the default layout), a leading data/ segment is redundant and dropped for reads and writes alike: data/trips/x.json and trips/x.json name the same file. A custom dataDir is a fresh, intentional layout — no collapse. The traversal guard still runs on the collapsed result, so data/../../x is rejected exactly as ../x would be.
  3. Legacy root fallback. If p — or its top-level folder — does not exist under dataDir but does under the app's source dir, it resolves under dir: reads find files written by pre-dataDir installs, writes update them in place (or land next to their siblings). Move the folder into dataDir and the fallback stops applying. Brand-new paths always land under dataDir.
  4. Listing merges both roots. When the same directory also exists under the source dir, app_data_list merges 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 resolve collapses ./.. segments, does not land on the root itself or strictly below it — a relative ../../secret or a nested a/../../b climbs out of the app dir into unrelated host files, and containment-by-prefix comparison against root + separator is 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:

VerbRole
packDirectory → .agentapp (see pack)
unpack.agentapp → directory, SHA-256 verified (see unpack)
serveServes .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
buildBuilds a ui/ source project into .agentproto/ui/ (no-op success when there's nothing to build)
devRuns a ui/ source project's own dev server plus a bridge-only server for live window.McpApp calls
setupagentproto 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):

ToolRole
app_installloadAppHandle(dir) → validate → persist an installed-app record
app_listList installed apps, each with a summary of its app_run history
app_list_appliedList apps applied to a scope
app_uninstallRemove an installed app (refuses while runs are live)
app_runSpawn a session per selected agent
app_statusFan out an app_run's sessions plus the app's workflow runs
app_stopKill every session in an app_run and mark the run ended
app_apply / app_unapplyBind / unbind an installed app to a scope
app_tool_callAllowlist-checked tool dispatch for UI-originated calls
app_catalogList catalog apps, including the builtin panels
app_artifact_getFetch an app's artifact surface
app_skill_getFetch an app's skill surface
app_data_read / app_data_write / app_data_list / app_data_migrateThe data plane (see The app data plane)
app_state_append / app_state_get / app_state_listThe app state ledger (see the data-plane carve-out)
app_external_list / app_external_readRead-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: guard keeps the host's guard in front of it. auth: service removes it: a host SHOULD show that choice to the user at install, and the service is then the only boundary.

  • exposes.tools is 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. An imported: entry forwards to a server the app does not control: only read is allowed, the result is returned unchanged, and the input is cut down to the keys inputSchema declares, which is how an app keeps a foreign tool's file-writing or otherwise dangerous argument out of reach. exposes.resources is 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 full resources/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 wiring callImportedTool MUST 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 and app dev's Access-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 than 127.0.0.1 MUST NOT keep the wildcard origin, since it would let any page on the internet POST tool calls through a reachable bridge.

  • csp.connectDomains / csp.resourceDomains are declared, not enforced by this AIP. AppUiDefinition.csp names 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 through emit / loadAppHandle unmodified.

  • services start 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 a cmd setup 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 a cwd outside the app directory.

  • An on-demand service lets a request start a process. The host's listener is loopback-only and every request that reaches it can start the process, so with auth: service anyone 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 process PORT is 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.

  • .agentapp integrity is checksum, not signature. The aggregate SHA-256 (see unpack) detects corruption and accidental tampering but is not a cryptographic signature — it proves the bundle matches what its own manifest.json claims, not that the claimed id/version/agentprotoVersion came from a trusted publisher. A registry distributing third-party .agentapp files 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_install validates workflow tool ids, not agent tool ids. The reference install path cross-checks every WORKFLOW.md tool step's id against the host's dispatchable tools (surfacing all missing ids at once), but explicitly does NOT validate an agent's own declared tools[] — those are the chosen agent adapter's business (e.g. workspace tools like read_file a mastra-agent adapter resolves independently). Implementers relying on app_install succeeding MUST NOT read that as a guarantee every agent-declared tool ref is resolvable; unvalidatedAgentTools on the install result names exactly which refs were skipped.

  • setup[] cmd steps are arbitrary code execution at install time. An app from a catalog or a git URL is third-party content, and a cmd step (and skip_if.cmd, persist.cmd, check.cmd) runs with the user's privileges. A host MUST show the verbatim command text of every pending cmd-bearing step and obtain explicit consent before running any of them; --yes MUST NOT imply that consent (reference: a dedicated --allow-setup-cmd flag, in the same spirit as the --allow-build gate on ui.build). Without consent the step is left pending and the install reports setup_consent_required. The other kinds do not execute app-supplied code: prompt, choice, auth-profile, pairing and check.tool are mediated entirely by the host. check.tool MUST 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: secret input is masked by the host surface and lands only in secret_slug / env (persist.answer is forbidden for it). A pairing code is single-use and short-lived, and the bound chat identity is stored by the host, never in the ledger. An external url MUST be https and MUST be shown to the user in full before it is opened. Because the app's ui cannot answer a step, a compromised UI cannot complete a pairing or read a token.

  • requires.apps[].tools widens what the consumer's agents can do, and nothing else. Installing a consumer that grants itself a provider's write tools 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 own exposes.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's extends, an app has no inheritance mechanism in this AIP. requires names a dependency relationship, and its workflows and tools let 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

  1. Signing and provenance. .agentapp integrity 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.

  2. UI framework conventions beyond Vite. The ui/ source-project convention (package.json with scripts.build/scripts.dev) is deliberately tool-agnostic in principle but the reference tooling's detectPackageManager and 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.

  3. Multi-UI apps. AppDefinition.ui is 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.

  4. Version ranges beyond exact, caret and tilde. requires.apps[].version accepts three shapes. Whether compound ranges (>=1.2 <2, ||) are worth a larger grammar is open until an app needs one.

  5. Setup choice of a different shape. choice options carry no per-option sub-steps; branching is expressed with when. Whether nested options or option-scoped requires are worth the extra surface is open, as is a typed pairing payload for channels other than telegram (WhatsApp, Discord) once a second implementation exists.

  6. Declared setup in a catalog entry. A host could show a catalog entry's pending setup (which secrets, which pairings, any cmd) before install, from the entry alone. Today it is visible only after APP.md is read.

See also

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 →