@athenaintel/agent-runtime

The Athena deep-agent runtime: what a chat surface needs to attach to an athena_deep_agent thread over statewire and drive it. The transport recipe (createDeepAgentAttachTransport, wakeDeepAgentThread, statewireTransport), the React hooks (useDeepAgentRuntime, useDeepAgentThread, useDeepAgentConfig, useConversationList, useDeepAgentVoice, …), the client-tool bridge (useStatewireClientToolBridge, executeClientToolBatch), the message and tool-result conversion helpers, and the generated runconfig-contract the backend and every client agree on.

Every Athena surface mounts this package — Olympus, the Chrome extension, the Office add-in, the React Native app, the terminal agent, and the @athenaintel/react SDK, which bundles its own copy (an app built on the SDK does not install this package). It is published for hosts that mount the runtime directly.

Installation

bun add @athenaintel/agent-runtime

The package ships TypeScript source, not compiled JavaScript: main, types and every exports entry point at .ts files. Your toolchain has to compile TypeScript out of node_modules — Vite, bun, Metro, esbuild, tsx and Next.js (transpilePackages) all do; plain Node import/require does not. Type-check with "moduleResolution": "bundler" (or node16/nodenext, which read the exports conditions). The sources are part of your program, so they are checked under your compiler options — they are written for strict: true — and they expect queueMicrotask in your lib (dom or @types/node).

Entry points

| Import | What it is | | --- | --- | | @athenaintel/agent-runtime | The runtime: hooks, transport recipe, client-tool bridge, message and tool-result conversion, thread status, voice, handoff | | @athenaintel/agent-runtime/errors | Statewire rejection and refusal classifiers (readRetryableRunRefusal, isStatewireExpiredVerdict, …) | | @athenaintel/agent-runtime/conversation-list | The shared, cache-patching session list model | | @athenaintel/agent-runtime/thread-handoff | Thread handoff (mobile QR / Office launch) types, schemas and transport helpers | | @athenaintel/agent-runtime/use-thread-handoff-flow | The handoff flow controller hook | | @athenaintel/agent-runtime/runconfig-contract | Generated wire contract: runConfig.custom keys, protocol version, statewire command names |

Peer dependencies

The host owns the versions of the assistant-ui runtime, statewire, React Query, React and zod. This package declares them as peers with the floor each release is written against; the right-hand column is what the monorepo's surfaces (Olympus, the Office add-in, the React SDK) pin today.

| Peer | Floor | Monorepo pin | | --- | --- | --- | | statewire | >=0.19.1 | 0.19.1 | | @assistant-ui/react-statewire | >=0.29.1 | 0.29.1 | | @assistant-ui/react-langgraph | >=0.14.26 | 0.14.26 | | @assistant-ui/core | >=0.3.17 | 0.3.19 | | @assistant-ui/store | >=0.3.12 | 0.3.13 | | @assistant-ui/tap | >=0.9.16 | 0.9.17 | | @tanstack/react-query | >=5.90.0 | 5.99.2 | | react | ^18 \|\| ^19 | 19.2.0 | | zod | >=4.1.13 | 4.4.3 |

The statewire and @assistant-ui/react-statewire floors are where the message-window code (documents, invoke, connection on the thread extras, statewire's protocol option) first exists upstream; the sources do not compile against anything older. Every release is compiled against exactly the "Monorepo pin" column, installed unpatched from npm, before it is published (the Compile the packed sources against unpatched peers step of publish-agent-runtime.yml).

@assistant-ui/react is not a peer of the runtime, but the UI layer a host mounts around it; the same surfaces run it at 0.15.20 beside these. Resolve exactly one copy of each @assistant-ui/* package, statewire and react (Vite: resolve.dedupe) — they carry React contexts and module singletons, and two copies mount two AssistantTapContexts.

The monorepo's patches

The monorepo installs three of these peers through bun patch (patchedDependencies in the root package.json, patch files under patches/). A host that installs this package from npm gets the unpatched upstream packages. The sources type-check against the unpatched upstream versions — the members below are typed structurally, not as StatewireThread.Extras[...], and each release is compiled that way in a scratch consumer before it ships — but the behaviour differs:

• @assistant-ui/[email protected] — adds the message-metadata preparation surface on StatewireThread.Extras (prepareMessageMetadata, discardPreparedMessageMetadata, sendPreparedEdit, isPreparingSubmission), the getMessageMetadata thread option, and carries a queue item's metadata through a queue edit. Without it, useDeepAgentThread's getMessageMetadata is ignored by the library and the edit path's optional preparation calls never run, so message metadata is simply not captured.
• [email protected] — failed-command retention and settlement in the client session; the send-recovery suites under src/__tests__ run against this behaviour.
• @assistant-ui/[email protected] — the edit composer re-lifts a user message's non-text parts as attachments.

To match the monorepo's behaviour, copy those three files from patches/ and declare them in your own patchedDependencies (bun); landing the patches upstream is the follow-up that removes the difference.

Wire contract

src/generated/runconfig-contract.ts is exported from agora (agora/scripts/export_runconfig_contract.py); CI fails when it is stale. The statewire fixture corpus (src/__fixtures__/statewire-corpus/, not shipped) is replayed on both ends of the wire on every CI run. A change to what the backend puts on the wire is a version bump of this package.

Releasing

Versions are cut from staging:

1. Bump version in packages/agent-runtime/package.json in the PR that changes the runtime, and merge it.
2. On that staging push, .github/workflows/auto-release-agent-runtime.yml creates the agent-runtime/v<version> tag (when it does not exist yet).
3. The tag runs .github/workflows/publish-agent-runtime.yml: it verifies the packed file list (every exports target and this README in; tests, fixtures and tsconfig out), checks the tag against the manifest, refuses a prerelease under latest, skips a version already on npm, and publishes with npm trusted publishing (OIDC, provenance attached) through the shared .github/actions/publish-npm-package lane — the same lane @athenaintel/react releases through.

Manual paths: push the tag yourself, or dispatch the workflow (gh workflow run publish-agent-runtime.yml --ref agent-runtime/v<version>; -f dry_run=true rehearses, -f dist_tag=next publishes a prerelease). Trusted publishing needs the package's Trusted Publisher configured in its npmjs.com settings (GitHub Actions · Athena-Intel/demo-app-monorepo · publish-agent-runtime.yml), and those settings exist only once the package does: the first version is published with -f bootstrap_with_token=true (the NPM_TOKEN repository secret), after which the trusted publisher is configured and the input stays off.

Tests: bun test src from this directory (bun run --filter @athenaintel/agent-runtime test from the repo root); typecheck with bun run typecheck. npm pack --dry-run lists exactly what a release ships.