@agentproto/app-kit 1.3.0 → 1.4.0

package/README.md

@@ -91,6 +91,37 @@ An app may also declare `requires: ["@acme/shared", ...]` — app ids that must
 applied to the same scope before this one can run. The runtime validates the
 graph when mounting apps via `app_apply`.
 
+### Placement, requirements, and A2A exposure
+
+Four optional `APP.md` keys describe where an app can run and what it exposes.
+They are **semantics only** — nothing schedules or serves on them yet. All are
+validated by `defineApp` (`AppDefinitionError`) and `loadAppHandle`
+(`AppLoadError`), surfaced on `AppHandle`, and written by `emit` only when they
+differ from the default.
+
+```yaml
+placement: any            # "local" | "box" | "any" | "split"   (default "any")
+requires:
+  browser: false          # needs the user's real browser (Bureau / local-browser)
+  fs: false               # needs the user's local filesystem beyond app data
+  gpu: false
+  secrets: []             # env/secret names the app needs
+  apps: []                # other app ids this app depends on
+exposes:                  # A2A-visible surfaces (default: none exposed)
+  agents: []              # ids from `agents:`
+  workflows: []           # ids from `workflows:`
+accepts:
+  tasks: false            # accept A2A tasks (default false)
+```
+
+- An unknown `placement`, or an `exposes.*` id that isn't one of the app's own
+  agents/workflows, is a validation error.
+- `requires` also still accepts the legacy flat array (`requires: ["@acme/shared"]`,
+  equivalent to `requires: { apps: [...] }`).
+- On the handle: `placement`, `exposes`, `accepts` and `requirements` (every key
+  resolved to its default) are always present. `handle.requires` stays the flat
+  list of app ids (absent when none) so existing dependency checks keep working.
+
 ## UI surfaces, artifacts, dev-launch, and the artifact surface
 
 Beyond agents and workflows, an app can declare four optional surfaces that
@@ -99,7 +130,20 @@ runtime app registry:
 
 - **`ui`** — an HTML dashboard/panel. `html` is written to
   `.agentproto/ui/index.html`; `APP.md` frontmatter carries the relative path
-  plus optional `title`, `description`, `tools`, and `csp`.
+  plus optional `title`, `description`, `tools`, `csp`, and `build`.
+- **`ui.build`** — how to (re)build `ui.path` when it's missing or stale,
+  so the bundle doesn't have to be committed. `{ command, cwd?, sources? }`:
+  `command` is a shell command line run with cwd `cwd` (default: the app
+  dir); `sources` is a list of globs (relative to `cwd`, default
+  `["src/**"]`) whose newest mtime is compared against `ui.path`'s to decide
+  staleness. The daemon/CLI run it — `app_install`, the first `GET
+  /apps/:appId/ui`, the MCP panel cache, and `agentproto app serve` all call
+  the same `ensureAppUiBuilt` (`@agentproto/runtime/app-ui-build`) before
+  serving, single-flight per bundle path so concurrent first requests only
+  build once. Output is captured to `<appDir>/.agentproto/ui-build.log`; a
+  failing build surfaces that log's tail as the tool/route error instead of
+  a bare 404. No `ui.build` declared ⇒ today's behavior: the bundle must
+  already exist on disk.
 - **`artifact`** — a persistent HTML dashboard (Cowork artifact). The app
   provides a path to an HTML file on disk; `emit` copies it to
   `.agentproto/artifact/index.html`. The daemon never writes the host manifest
@@ -225,6 +269,14 @@ export const dashboardApp = defineApp({
     html: "<!doctype html><html>…</html>",
     title: "Ops Dashboard",
     tools: ["terminal_start", "agent_start"],
+    // Only needed when `ui.path`'s bundle isn't committed to the repo —
+    // the daemon/CLI build it on demand before serving. See the APP.md
+    // frontmatter equivalent below.
+    build: {
+      command: "pnpm run build",
+      cwd: "ui",
+      sources: ["ui/src/**", "ui/index.html", "ui/vite.config.ts"],
+    },
   },
   artifact: {
     path: "/path/to/dashboard.html",
@@ -321,6 +373,86 @@ const app = await loadAppHandle("/path/to/emitted/app")
 app.agents.map((e) => e.agent.id) // ["@agentik/reviewer", "fixer"]
 ```
 
+### `ui.build` — don't commit the generated bundle
+
+Add a `build` block under `ui` in `APP.md`'s frontmatter and gitignore
+`.agentproto/ui/index.html` — the daemon builds it on demand instead:
+
+```yaml
+ui:
+  path: .agentproto/ui/index.html
+  build:
+    command: pnpm run build
+    cwd: ui
+    sources:
+      - ui/src/**
+      - ui/index.html
+      - ui/vite.config.ts
+```
+
+`app_install`, the first `GET /apps/:appId/ui`, the MCP panel, and
+`agentproto app serve` all resolve this the same way (`peekAppUi` +
+`ensureAppUiBuilt` from `@agentproto/runtime/app-ui-build`): missing or
+older than the newest matching source → run `command` once (single-flight
+per bundle path, output captured to `.agentproto/ui-build.log`) → serve.
+Omit `build` to keep committing the bundle, unchanged from before this
+existed.
+
+## Boundaries — fs zones for app-spawned sessions
+
+Set `boundaries: { enforce: "required" | "best-effort" }` on `defineApp` (or
+`boundaries:` in `APP.md`'s frontmatter) to declare how strictly the daemon
+must confine sessions the app spawns — `app_run`, and workflow agent steps
+whose workflow carries this app's `appId`:
+
+```ts
+defineApp({
+  id: "@acme/transcriber",
+  boundaries: { enforce: "required" },
+  // ...
+})
+```
+
+For every such session the daemon builds one **boundary** with three zones:
+
+| Zone | Contents | Access |
+| --- | --- | --- |
+| read-only | the installed app dir (source, `.agentproto/`, `scripts/`) | read |
+| writable | the app's `data/` dir, and the workflow run's `$run.workspace` (`app_run` has no run workspace: writable is `data/` only) | read + write |
+| everything else | including the daemon's own workspace and any host monorepo the app happens to be installed inside | denied |
+
+The boundary is enforced on two independent surfaces:
+
+1. **Daemon file/command tools** (`file_read`, `file_write`, `directory_*`,
+   `command_execute`, …) — always enforced, identity-based: the daemon
+   recovers the caller's boundary from its own session record, resolves
+   relative paths against the app dir, and rejects reads/writes outside the
+   zones (including through symlinks). This does not depend on the harness.
+2. **The harness's own native tools** (a claude-code session's Bash, Write,
+   Edit, …) — enforced by wrapping the harness in an OS sandbox
+   (`@agentproto/command-sandbox`: macOS Seatbelt or Linux bubblewrap) built
+   from the same zones, plus, on adapters that support it, excluding the host
+   repository's `CLAUDE.md`/`AGENTS.md` from context so an app session never
+   inherits instructions from the monorepo it's installed inside.
+
+Surface 2 needs an adapter that supports fs zones and an available OS sandbox
+backend. When it can't be enforced:
+
+- `boundaries.enforce: "best-effort"` (the default) still spawns the session
+  — daemon tools remain confined — and emits a `session:harness-warning`
+  naming the reason (no sandbox backend on this platform, the adapter doesn't
+  support `fsZones`, or `commandSandbox: "off"` was requested explicitly).
+- `boundaries.enforce: "required"` refuses the spawn instead of downgrading
+  silently (`app_boundary_unenforceable`).
+
+**Deferred:** the `AGENT.md` `tools:` allowlist becoming an *enforced*
+allowlist on adapters that support it (today it's advisory — an agent can
+still reach native Bash next to an allowlisted `command_execute`). Also out
+of scope for this phase: a network-capable sandboxed process reaching the
+daemon's HTTP API directly (bypasses the identity-based check the MCP path
+uses), and boundary enforcement on daemon-wide MCP tools other than
+file/command/terminal.
+
 ## Runtime note
 
 `toMastraAgents` is the path where a `body` becomes a **true** model

package/dist/define-app.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"define-app.d.ts","sourceRoot":"","sources":["../src/define-app.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAQH,OAAO,KAAK,EAEV,aAAa,EACb,SAAS,EACT,aAAa,EAGd,MAAM,YAAY,CAAA;AAInB,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,OAAO,EAAE,MAAM;CAI5B;AAED,wBAAgB,SAAS,CAAC,GAAG,EAAE,aAAa,GAAG,SAAS,CA8IvD;AAiID,YAAY,EAAE,aAAa,EAAE,CAAA"}
+{"version":3,"file":"define-app.d.ts","sourceRoot":"","sources":["../src/define-app.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAQH,OAAO,KAAK,EAEV,aAAa,EACb,SAAS,EACT,aAAa,EAGd,MAAM,YAAY,CAAA;AAKnB,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,OAAO,EAAE,MAAM;CAI5B;AAED,wBAAgB,SAAS,CAAC,GAAG,EAAE,aAAa,GAAG,SAAS,CAyKvD;AAiID,YAAY,EAAE,aAAa,EAAE,CAAA"}

package/dist/emit.d.ts

@@ -32,7 +32,7 @@
  */
 import type { WorkflowHandle } from "@agentproto/workflow";
 import type { WorkspaceHandle } from "@agentproto/workspace";
-import type { AgentEntry, AppArtifactDecl, AppArtifactSurface, AppDataDefinition, AppDevDefinition, AppSkillSurface, AppUiDefinition, EmittedApp } from "./types.js";
+import type { AgentEntry, AppAccepts, AppArtifactDecl, AppArtifactSurface, AppBoundariesDefinition, AppDataDefinition, AppDevDefinition, AppExposes, AppPlacement, AppRequirements, AppSkillSurface, AppUiDefinition, EmittedApp } from "./types.js";
 interface EmitInput {
     readonly agents: readonly AgentEntry[];
     readonly workflows: readonly WorkflowHandle[];
@@ -42,6 +42,10 @@ interface EmitInput {
     readonly version?: string;
     readonly description?: string;
     readonly requires?: readonly string[];
+    readonly requirements?: AppRequirements;
+    readonly placement?: AppPlacement;
+    readonly exposes?: AppExposes;
+    readonly accepts?: AppAccepts;
     readonly ui?: AppUiDefinition;
     readonly artifact?: AppArtifactSurface;
     readonly skill?: AppSkillSurface;
@@ -49,6 +53,7 @@ interface EmitInput {
     readonly dev?: AppDevDefinition;
     readonly data?: AppDataDefinition;
     readonly externalReadRoots?: readonly string[];
+    readonly boundaries?: AppBoundariesDefinition;
     readonly category?: string;
 }
 export declare function emitApp(app: EmitInput, dir: string): Promise<EmittedApp>;

package/dist/emit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"emit.d.ts","sourceRoot":"","sources":["../src/emit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAKH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAC1D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAC5D,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,eAAe,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAGpK,UAAU,SAAS;IACjB,QAAQ,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,CAAA;IACtC,QAAQ,CAAC,SAAS,EAAE,SAAS,cAAc,EAAE,CAAA;IAC7C,QAAQ,CAAC,SAAS,CAAC,EAAE,eAAe,CAAA;IACpC,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACrC,QAAQ,CAAC,EAAE,CAAC,EAAE,eAAe,CAAA;IAC7B,QAAQ,CAAC,QAAQ,CAAC,EAAE,kBAAkB,CAAA;IACtC,QAAQ,CAAC,KAAK,CAAC,EAAE,eAAe,CAAA;IAChC,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,eAAe,EAAE,CAAA;IAC/C,QAAQ,CAAC,GAAG,CAAC,EAAE,gBAAgB,CAAA;IAC/B,QAAQ,CAAC,IAAI,CAAC,EAAE,iBAAiB,CAAA;IACjC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC9C,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAC3B;AAED,wBAAsB,OAAO,CAAC,GAAG,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAgH9E"}
+{"version":3,"file":"emit.d.ts","sourceRoot":"","sources":["../src/emit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAKH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAC1D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAC5D,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,eAAe,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,UAAU,EAAE,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAGpP,UAAU,SAAS;IACjB,QAAQ,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,CAAA;IACtC,QAAQ,CAAC,SAAS,EAAE,SAAS,cAAc,EAAE,CAAA;IAC7C,QAAQ,CAAC,SAAS,CAAC,EAAE,eAAe,CAAA;IACpC,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACrC,QAAQ,CAAC,YAAY,CAAC,EAAE,eAAe,CAAA;IACvC,QAAQ,CAAC,SAAS,CAAC,EAAE,YAAY,CAAA;IACjC,QAAQ,CAAC,OAAO,CAAC,EAAE,UAAU,CAAA;IAC7B,QAAQ,CAAC,OAAO,CAAC,EAAE,UAAU,CAAA;IAC7B,QAAQ,CAAC,EAAE,CAAC,EAAE,eAAe,CAAA;IAC7B,QAAQ,CAAC,QAAQ,CAAC,EAAE,kBAAkB,CAAA;IACtC,QAAQ,CAAC,KAAK,CAAC,EAAE,eAAe,CAAA;IAChC,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,eAAe,EAAE,CAAA;IAC/C,QAAQ,CAAC,GAAG,CAAC,EAAE,gBAAgB,CAAA;IAC/B,QAAQ,CAAC,IAAI,CAAC,EAAE,iBAAiB,CAAA;IACjC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC9C,QAAQ,CAAC,UAAU,CAAC,EAAE,uBAAuB,CAAA;IAC7C,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAC3B;AAED,wBAAsB,OAAO,CAAC,GAAG,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAuH9E"}

package/dist/index.d.ts

@@ -38,8 +38,11 @@
  */
 export { defineApp, AppDefinitionError } from "./define-app.js";
 export { emitApp } from "./emit.js";
-export { loadAppHandle, AppLoadError, resolveAppUIRoot } from "./load-app.js";
+export { loadAppHandle, AppLoadError, resolveAppUIRoot, peekAppUi } from "./load-app.js";
+export type { AppUiPeek } from "./load-app.js";
 export { loadAppBundledTools } from "./load-app-tools.js";
+export { packApp, unpackApp, aggregateSha256, collectFiles, isManifest, safeId, AGENTAPP_FORMAT, AgentAppPackError, } from "./pack.js";
+export type { AgentAppManifest, BundleFile, AgentAppPackErrorCode } from "./pack.js";
 export { refKey, stripOwner } from "./refs.js";
-export type { AppDefinition, AppHandle, AgentEntry, DoctypeHandle, WorkspaceShorthand, WorkspaceInput, AppUiDefinition, AppArtifactSurface, AppSkillSurface, AppArtifactDecl, AppDevLaunchConfig, AppDataDefinition, AppDevDefinition, ToMastraAgentOptions, EmittedApp, } from "./types.js";
+export type { AppDefinition, AppHandle, AgentEntry, DoctypeHandle, WorkspaceShorthand, WorkspaceInput, AppUiDefinition, AppUiBuildConfig, AppArtifactSurface, AppSkillSurface, AppArtifactDecl, AppDevLaunchConfig, AppBoundariesDefinition, AppDataDefinition, AppDevDefinition, AppPlacement, AppRequirements, AppExposes, AppAccepts, ToMastraAgentOptions, EmittedApp, } from "./types.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,EAAE,SAAS,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAA;AAC/D,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACnC,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AAC7E,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AACzD,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AAC9C,YAAY,EACV,aAAa,EACb,SAAS,EACT,UAAU,EACV,aAAa,EACb,kBAAkB,EAClB,cAAc,EACd,eAAe,EACf,kBAAkB,EAClB,eAAe,EACf,eAAe,EACf,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EAChB,oBAAoB,EACpB,UAAU,GACX,MAAM,YAAY,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,EAAE,SAAS,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAA;AAC/D,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACnC,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AACxF,YAAY,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAC9C,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AACzD,OAAO,EACL,OAAO,EACP,SAAS,EACT,eAAe,EACf,YAAY,EACZ,UAAU,EACV,MAAM,EACN,eAAe,EACf,iBAAiB,GAClB,MAAM,WAAW,CAAA;AAClB,YAAY,EAAE,gBAAgB,EAAE,UAAU,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAA;AACpF,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AAC9C,YAAY,EACV,aAAa,EACb,SAAS,EACT,UAAU,EACV,aAAa,EACb,kBAAkB,EAClB,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,EACf,eAAe,EACf,kBAAkB,EAClB,uBAAuB,EACvB,iBAAiB,EACjB,gBAAgB,EAChB,YAAY,EACZ,eAAe,EACf,UAAU,EACV,UAAU,EACV,oBAAoB,EACpB,UAAU,GACX,MAAM,YAAY,CAAA"}