@meistrari/agent-core

Shared contracts and runtime modules for Tela coding-agent sandboxes.

| Subpath | What it is | | --- | --- | | @meistrari/agent-core/protocol | Provider-neutral agent commands, events, content, tools, usage, work items (Claude and Codex share it). | | @meistrari/agent-core/supervisor-protocol/* | Strict wire contracts between a worker runtime and the resident sandbox supervisor: bootstrap, commands, events, reverse RPC, control authority. | | @meistrari/agent-core/errors, /logger, /provenance | Shared primitives. | | @meistrari/agent-core/supervisor | Sandbox-resident supervisor runtime (Bun, WebSocket, SQLite), provider factory, and product-facing ports. | | @meistrari/agent-core/worker-runtime-client | Control-plane WSS client: leases, generation fencing, command pump, durable event ACKs, reverse RPC dispatch, ES256 authority, token crypto, and PG notifications. | | @meistrari/agent-core/testing | In-memory control-plane, scripted provider, loopback connection, and ES256 test fixtures. | | @meistrari/agent-core/template-onboarding | Validated service-owned E2B template registration and immutable provenance contract. | | @meistrari/agent-core/agents | Provider-neutral agent, run, tool, event-stream, and instruction-composer contracts. | | @meistrari/agent-core/claude | Claude Agent SDK provider with normalized lifecycle, message, tool, work, usage, and user-input events. | | @meistrari/agent-core/codex | Codex app-server provider, JSON-RPC transport, normalized event mapping, and pluggable authentication. |

The supervisor accepts the Claude and Codex adapters through createAgentSupervisorProviderFactory, preserving the same durable wire protocol for either harness.

The package ships TypeScript source and targets Bun >=1.3.10. There is no wire protocol version: a sandbox keeps the exact agent-core build it was created with for its lifetime (immutable sandbox invariant). Incompatible wire changes require reprovisioning sandboxes, never in-place upgrades.

agent-core does not own a universal E2B template. Each consuming service builds and onboards its own template against the shared contracts and records that template's agent-core provenance. agent-api and Remy may therefore use different base images, harness versions, system packages, and startup hooks without forking the control protocol.

Development

bun install
bun run lint
bun run typecheck
bun run test        # unit tests (src/**/*.test.ts)
bun run test:e2e    # loopback worker <-> supervisor e2e
bun run build:supervisor # cross-compile the Linux x64 resident executable

Resident supervisor entry

agent-core-supervisor loads a product-owned extensions module so credentials, tools, workspace preparation, hooks, payload storage, and provider construction remain outside the shared runtime:

bunx agent-core-supervisor \
  --extensions ./supervisor-extensions.ts \
  --authority-jwks-path ./control-authority.json

Use --loopback-tcp for local and image-build probes. Production images default to the protected Unix socket. The extension module exports default, extensions, or createSupervisorExtensions() matching SupervisorExtensions.

Publishing runs from main through .github/workflows/publish.yml (conventional commits decide the bump).