agentproto-apps

Agentproto apps (AIP-53)

A packaged app is a directory that ships one or more AIP-42 agents, the AIP-15 workflows they run, and (optionally) a single-file web UI, emitted under <dir>/.agentproto/ by defineApp().emit(dir). The daemon installs, applies, runs, and persists them. This skill is the app plane on top of the base agentproto skill (sessions/drivers live there).

Anatomy — what an app dir contains

<appDir>/
  .agentproto/
    APP.md                            # frontmatter: id, agents[], workflows[], ui{path,tools}
    agents/<id>/AGENT.md              # AIP-42 agent manifests
    workflows/<id>/WORKFLOW.md        # AIP-15 workflow manifests
    ui/index.html                     # single-file dashboard (CSS+JS inline)
  data/                               # default data dir (app_data_* writes here)
<dataDir>/                            # …or wherever `app_install {dataDir}` /
                                      # `app install --data-dir` pointed it

APP.md frontmatter (schema: app/v1, id, agents: [{id,path}], workflows: [{id,path}], ui: {path, title, tools: [...]}, optional data: {dir} — the default data dir, relative to the app dir). The ui.tools array is an allowlist — app_tool_call REFUSES any tool id not in it, so when the UI calls a new daemon tool (e.g. app_data_read), add it there.

Gotcha: this repo's root .gitignore ignores .agentproto/ by default (it targets agent-scoped scratch). For a first-class app bundle the .agentproto/ dir IS the deliverable — git add -f <appDir>/.agentproto to commit it.

The app lifecycle (daemon verbs)

• app_install {dir} — validates the app (loadAppHandle), cross-checks every WORKFLOW.md tool step id against the daemon's registered tools (reports ALL missing at once), and checks the agent adapter resolves. Upserts by appId. Re-installing refreshes the record.
• app_apply {appId, scopeId?, dir?} — makes the app's capabilities available in a scope; installs first if dir given and not already installed; validates requires deps are applied. Idempotent.
• app_run {appId, agents?, sequence?, prompt?, cwd?, model?, harness?, adapter?} — spawns one live session per agent under a fresh appRunId. agents runs them CONCURRENTLY. sequence: [id, ...] runs them ONE-AT-A-TIME in order (each awaited to a terminal session state before the next), for scout→tailor-style dependency chains — both under one appRunId. Pass model/harness (or adapter) to select the runner for every spawn.
• app_status {appRunId} — returns the run's session descriptors + its workflow runs. As of the sequential-run work, app_status LAZILY reconciles: if the stored run status is running but every session is terminal, it reports ended (with a synthesized endedAt) — so concurrent runs are also observed to conclude instead of hanging forever at running.
• app_stop {appRunId} — kills the run's sessions and marks it terminal.
• app_list — installed apps with a run-history summary (includes adapter/harness/model when set on the run).
• app_uninstall / app_unapply / app_list_applied / app_catalog / app_skill_get / app_artifact_get — installation/uninstall and catalog.