AgentDock integration contract

Arcotheon is deliberately independent of AgentDock. This page is the contract any host follows. A first implementation for AgentDock Pro exists as an isolated draft pull request (feature/arcotheon-integration, based on origin/main, PR #87 in the AgentDock Pro repository). It is not merged, not released, does not touch the release-stabilisation work or PR #76, and has been verified only by typecheck and targeted tests (see its docs/arcotheon-integration.md).

Responsibilities#

Embedding#

1. Add @arcotheon/sdk to the host's main process (Node 22.12+; check the Node version embedded in the host's Electron release, or run the SDK in a utility process on a Node 22 binary). Do the work in the main process or a utility process, never in a renderer.
2. Create one Arcotheon instance with home inside the app's data directory, rootKeys: ARCOTHEON_ROOT_KEYS and host: { platform, agent: { id: "agentdock", version } }. The host.agent makes the resolver refuse capabilities whose compat.agents excludes the app version.
3. Discover: search and packageDoc for catalogue UI. Both are metadata only.
4. Install: plan to show a dialog (items, versions, newPermissions, report.lines), then install(…, { approve }). Reject unless the user confirms. Do not pass a blanket approve: () => true except for capabilities the host itself ships.
5. Skills: for each installed capability, installedManifest(id).skills[*].path joined to installedDir(id) is a standard Agent Skills directory. Register it with whichever agents the host drives.
6. Tools: either call runTool(arc, id, tool, input, { workspace }) from the host's tool layer, or run mcpServe in a child process and register it as an MCP server for the agents. In both cases only granted tools exist.
7. Workflows: runWorkflow executes tool steps and returns at the first agent step with an instruction and the data so far; the host feeds that to its agent and decides how to continue.
8. Keep current: update() for user-initiated or scheduled updates (it asks again if permissions grew), doctor() on start-up to surface revoked or broken installs, rollback() as the undo.

Free and Pro#

The registry records distribution.tier and access per version and exposes it in the catalogue. It never gates by itself. The host must:

• Hide, label or block tier: "pro" capabilities for Free users before calling install, using its own entitlement state. Check again before runTool: the SDK trusts the host here.
• For access: "entitled" downloads, pass an authorize callback. It receives { kind: "package" | "resource", id, version?, entitlement? } and the URL; return null to deny, or { url?, headers? } to allow, typically a short-lived signed URL minted by a Sarja entitlement service. Archives are still verified against the registry hash and the publisher signature.

The Sarja entitlement endpoint does not exist yet; the callback is the seam. Designing the endpoint is future work.

Data the host should persist#

Nothing beyond what the SDK stores under home. Grants live in state.json per installed package, as id[:scope] strings. Do not edit that file; use the API.

Sandbox expectations by platform#

A host that opts out is responsible for the risk and should do so only for capabilities it ships itself. Native sandboxes for macOS and Windows are future work; the SDK's Sandbox interface (wrap(spec) → command) is where they go.

Versioning of this contract#

The SDK follows semver for the exports named above. The .adcap format has its own version (adcap: "1.0"); a host must refuse manifests whose major version it does not support (the SDK does).