SDK reference · Arcotheon docs

@arcotheon/sdk is plain TypeScript for Node 22+, with three runtime dependencies (ajv, ajv-formats, semver) and no dependency on Electron or any agent.

The manager#

import { Arcotheon, ARCOTHEON_ROOT_KEYS, DEFAULT_REGISTRY, runTool, runWorkflow, mcpServe } from "@arcotheon/sdk";

const arc = new Arcotheon({
  home: "/path/to/store",                       // installs, state and caches live here
  registries: [{ source: DEFAULT_REGISTRY }],   // URL or directory; several allowed, searched in order
  rootKeys: ARCOTHEON_ROOT_KEYS,                // pinned registry root keys
  host: { platform: "linux-x64", agent: { id: "agentdock", version: "1.4.0" } },
  offline: false,
  authorize: async (subject, url) => null,      // see "Entitled downloads"
});

Method	Purpose
`search(query, { category, tier, publisher })`	Search the catalogue.
`packageDoc(id)`	All versions of one capability, with status.
`plan(requests)`	Resolve without changing anything; returns items with `newPermissions` and a permission report.
`install(requests, { approve, prerelease, pin, dryRun })`	Resolve, download, verify, then commit. `approve(plan)` is called with what will change; throws `PERMISSION_DENIED` if permissions are new and there is no approver.
`installFile(path, { allowUnsigned })`	Sideload a local `.adcap`.
`update(ids?, { major })` / `rollback(id, version?)` / `pin(id, bool)` / `uninstall(id)`	Lifecycle.
`verifyInstalled(id?)` / `doctor()`	Re-hash installed files; compatibility, dependency, revocation and deprecation report.
`exportLock()` / `installLock(lock)`	Reproducible installs from exact versions and hashes.
`cacheInfo()` / `cachePrune()` / `cacheClear()` / `prefetch(requests)`	Offline cache management.
`state()` / `installedManifest(id)` / `installedDir(id)`	Inspect what is installed.

All failures are ArcotheonError with a stable code (HASH_MISMATCH, SIGNATURE_INVALID, PERMISSION_DENIED, NO_SOLUTION, INCOMPATIBLE, REVOKED, OFFLINE, ACCESS_DENIED, …).

Running things#

const result = await runTool(arc, "sarja/example-adcap", "word_count", { text: "one two three\nfour" }, { workspace: "/my/project" });
// { output, sandbox: { name: "bubblewrap", level: "strong" }, durationMs, stderr }
// result.output is { words: 4, characters: 18, lines: 2 }

// For a capability that ships a workflow (the Example does not):
const wf = await runWorkflow(arc, "<publisher>/<capability>", "<workflow>", { /* the workflow's input */ }, { workspace });
// { status: "needs-agent", step, instruction, context, completed } | { status: "done", output, steps }

runTool re-verifies the installed files, checks the registry has not revoked the version (when reachable), requires every permission the tool declares to be among the grants stored at install, validates input and output against the tool's schemas, materialises declared resources and runs the process in the best sandbox available. See security.

Serving agents over MCP#

mcpServe(arc, { input, output }, runOptions) implements an MCP server (JSON-RPC over stdio) exposing granted tools as publisher.name.tool. arcotheon mcp is that function wired to stdin and stdout.

Authoring and registry functions#

buildPackage(dir, { sign }), verifyPackage(archive, { trust, requireSignature, expectManifestSha256 }), openArchive, extractPackage, validateManifest, inspectPermissions, diffPermissions, generateKeyPair, publishLocal(registryRoot, dir, key), buildRegistry(root, { registryId, key }), verifyRegistry(root, rootKeys), RegistryClient, ResourceStore, resolve. They are the same functions the CLI uses.

Entitled downloads#

authorize: async ({ kind, id, version, entitlement }, url) => {
  if (!(await user.hasEntitlement(entitlement))) return null;       // -> ACCESS_DENIED
  return { url: await signedUrlFor(url), headers: { authorization: `Bearer ${token}` } };
}

Return null to deny; return a replacement url and/or headers to allow. The archive is still checked against the registry hash and the publisher signature whatever the authoriser returns.

Environment and files#

The store layout under home is an implementation detail but stable within 0.x: state.json, store/<pub>/<name>/<version>/, cache/archives/<sha256>.adcap, cache/resources/<aa>/<sha256>, cache/registry/…. Writes are atomic (temp file and rename) and changes take an exclusive lock.

Storage, signing and entitlement helpers#

S3Store, FileStore, pushBlob, blobKey, signV4: content-addressed blob storage (R2/S3-compatible).
commandSigner(keyId, command, args): a Signer that signs through an external process; accepted anywhere a key is.
gatewayAuthorizer({ gateway, userToken }): a DownloadAuthorizer for the entitlement gateway.
startEgressProxy, hostAllowed, parseHostRule: the network allowlist used by the sandbox.
runTool options: secrets(name) supplies secrets to tools that hold them; results include enforcement and egress.
RegistryClient exposes warnings (for example, offline use of an expired catalogue).
ERROR_HINTS: an action to suggest for each error code.