This repository is the client. The hosted service (API, billing, recall selection, storage, operator tooling) lives in a separate private repository and consumes this one as a pinned release.
crosshead (this repo) hosted service repo
src/protocol ──── @crosshead/protocol ──▶ API shapes, validators, schemas
src/runtime ──── @crosshead/runtime ──▶ embedded runtime (hosted Pi
controller) and operator builds
release/ ──── install tarball ─────▶ served unchanged at /install
Rules, enforced by npm run check:boundary and scripts/verify-release.mjs:
src/protocolimports only other protocol modules and Node built-ins.src/runtimeimports only runtime/protocol modules, Node built-ins and the dependencies inpackage.json.- The install tarball contains only
package.json,package-lock.jsonand compiled JavaScript underdist/runtimeanddist/protocol. Verification scans it for hosted-service imports and credential patterns and checks the runtime dependency allowlist.
Code that only the hosted service needs, such as recall heuristics, does not belong here. Code both sides need lives here; the hosted service imports it.
The Claude Code and Codex plugins (plugins/, .claude-plugin/,
.agents/plugins/) are generated from src/runtime/host-hook-spec.ts and are
installed from this repository by the hosts, not from the release tarball. They
only run the installed runtime's hook entrypoints; see
HOST-PLUGINS.md.
FriendMachine's local operator runs a superset build from the hosted repository. The client exposes two seams for it:
runOnlyBotsDaemonCli(argv, { composeOrganizationalWorker })insrc/runtime/daemon-host.ts. The public daemon has no composer and rejects--organizational-worker-config.runOnlyBotsCtlCli(argv, { commands, cliScriptPath, daemonScriptPath })insrc/runtime/cli.ts. Operator builds add commands (for examplecontinuity benchmark) and point managed restarts at their own entries.
The organizational-worker daemon API types and the federation-status wire contract stay in this repository because the daemon serves them; the implementations (Baseplate clients, worker controller and store) do not.
- Shared definitions compile on both sides. The hosted service imports
protocol types, validators and constants from
@crosshead/runtime(dist/protocol/*) instead of keeping its own copies. A change here that breaks the server fails the server's typecheck when it updates the pin. - Contract tests run against the exact artifact. The hosted repository's adapter, CLI, update and recall suites start the real server in-process and drive this runtime from the vendored package, not from source.
- The served tarball is the released tarball. The hosted service serves the vendored install tarball byte-for-byte; its digest must match the release manifest. It does not rebuild the client.
- Schemas have one owner.
schemas/is canonical. The hosted repository's documentation copies are checked against the vendored package.
Updating the hosted service to a new release:
# in the hosted repository
node scripts/ops/xhd-vendor-runtime.mjs --from <release-dir-or-tag>
npm install
npm run typecheck && npm testpackage.jsonversionfollows semver for@crosshead/runtimeand@crosshead/protocol, which are released together.- The release ID is
<version>-<first 12 hex of the install tarball SHA-256>. Installed runtimes store each release inlib/runtime/<releaseId>and skip the download when that directory exists, so the ID changes whenever the tarball changes. ONLYBOTS_RUNTIME_CORE_VERSIONinsrc/runtime/runtime-persistence.tsis the runtime-home compatibility version. Change it only with a migration path for existing homes.
Compatibility constraints from already-installed clients:
- The installer and
crosshead updatereadRELEASE_ID,RELEASE_URLandRELEASE_SHA256from/install. The updater accepts only the official hosted origin or the matching GitHub release asset. Inautomode, the updater verifies GitHub's signed build attestation, release workflow identity, tag and archive digest before installing on an idle host launch. Inmanualmode, the operator supplies the trusted digest independently. - The tarball must contain
package.json,package-lock.jsonanddist/runtime/{cli,daemon,local-runtime,codex-adapter,claude-code-adapter,pi-adapter,codex-bridge,codex-hook,claude-code-bridge,claude-code-hook}.js. Older clientsrequire()some of these modules directly during updates. - Entries must be regular files or directories, without absolute paths or
... - Installation runs
npm ci --omit=dev --ignore-scripts.
Wire-protocol changes must stay readable by the oldest runtime still in use, or the hosted service must keep serving the older shape until those runtimes update.
The client fails closed at the hosted boundary. Server releases paired with this runtime must observe these rules:
/v1/auth/challengereturns a base64url-encoded JSON object withversion=crosshead_auth_v1,purpose=crosshead_hosted_auth, the exact service audience and requestingnpub, a random nonce, and boundedissued_at/expires_attimestamps. Opaque 32-byte signing challenges are rejected because they can be Nostr event IDs.- Handoff capsules are signed and verified locally. The client never sends an
nsecheader and does not trust hostedvalidationorinspectionfields. Cross-machine exchange uses the signed capsule bytes. - Hot-memory
contentis acrosshead_signed_memory_v1envelope. The server stores it opaquely. Reads with a missing, altered, foreign, or wrong-scope signature are discarded locally. - Hosted context text, manifests, warnings, lifecycle actions, inbox items, dream-review items, obligations, and status details are not injected into an agent prompt. A future context aggregation protocol must return client- verifiable source envelopes rather than server-authored free-form instructions.
- Public-discovery consumers request
include_raw=trueand derive identity, payload, and routing fields only from a locally verified Nostr event.