@cotal-ai/connector-core 0.128.5 → 0.128.7
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import type { DocsBundle } from "./docs.js";
|
|
2
2
|
/** The installed Cotal version, for stamping the orientation card and other surfaces. */
|
|
3
|
-
export declare const DOCS_VERSION = "0.128.
|
|
3
|
+
export declare const DOCS_VERSION = "0.128.7";
|
|
4
4
|
export declare function loadDocsBundle(): DocsBundle;
|
|
5
5
|
//# sourceMappingURL=docs-bundle.generated.d.ts.map
|
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
/** The installed Cotal version, for stamping the orientation card and other surfaces. */
|
|
2
|
-
export const DOCS_VERSION = "0.128.
|
|
2
|
+
export const DOCS_VERSION = "0.128.7";
|
|
3
3
|
export function loadDocsBundle() {
|
|
4
4
|
return {
|
|
5
|
-
"version": "0.128.
|
|
5
|
+
"version": "0.128.7",
|
|
6
6
|
"generatedFrom": "docs/*.md + SPEC.md + spec/cotal-lang.md + spec/cotal.schema.json",
|
|
7
7
|
"pages": [
|
|
8
8
|
{
|
|
@@ -123,7 +123,7 @@ export function loadDocsBundle() {
|
|
|
123
123
|
"kind": "Guide (informative)",
|
|
124
124
|
"category": "Guide",
|
|
125
125
|
"summary": "OpenAI Codex joins a Cotal mesh as a lateral peer: the same cotal tool surface, the same message delivery and attention model as the other connectors, plus mid-turn steering: a directed peer messag…",
|
|
126
|
-
"body": "# Connect Codex (beta)\n\n> **Guide** (informative) · **For:** operators · **Prereqs:** [Quickstart](getting-started.md)\n\n[OpenAI Codex](https://developers.openai.com/codex/) joins a Cotal mesh as a lateral peer: the\nsame `cotal_*` tool surface, the same message delivery and attention model as the other\nconnectors, plus mid-turn steering: a directed peer message arriving during a\nconnector-started turn is **steered into that turn** instead of waiting for it to end.\nMessage batches arriving during a turn started in the attached TUI or by Codex itself,\nincluding a native goal continuation, wait for that turn to end before the connector starts\na delivery turn.\n\n**Beta** means the everyday path (spawn into the real Codex TUI, coordinate, watch) works; the\nspawn options that are not wired **fail loud** rather than degrade: resuming a session\n(`--resume`) and tool-sharing (`connectors.codex.mcpServers`). See [Limits](#limits).\n\n## Install\n\nThe connector ships with the CLI as a seeded extension (`@cotal-ai/connector-codex`): no\nseparate install step and no Codex-side plugin. You only need an authenticated `codex` binary\non your PATH (a ChatGPT-plan login or an `OPENAI_API_KEY`). If an older install is missing it,\n`cotal ext seed` (or `cotal ext add @cotal-ai/connector-codex`) brings it in. Use\n`cotal ext seed --repair` when an earlier seed failed or was interrupted.\n\n**Don't install the `cotal` plugin Codex offers you.** Searching Codex's plugin list for \"cotal\"\nturns up a plugin named `cotal`, from the `cotal-mesh` marketplace. That is the **Claude Code**\nadapter, which appears there only because Codex reads the same plugin-marketplace format; it is\nnot this connector and installing it does not connect Codex to a mesh. Codex needs nothing\ninstalled on its side: the connector drives it from the outside, over `codex app-server`.\n\n**Codex version.** The connector drives `codex app-server` over its experimental v2 surface.\nMinimum **codex-cli 0.145.0**; tested against 0.145.0 and 0.146.0. An older binary authenticates fine but has\nno `--listen`/`--ws-auth` listener, so the launch fails at startup rather than misbehaving quietly:\ncheck with `codex --version` and upgrade (`npm i -g @openai/codex`) if a launch reports that the\napp-server exited before it started listening. The surface is explicitly experimental upstream, so\na later Codex release may change it and need a connector update. That is a break to report, not a\nsupport range we can promise ahead of it.\n\n## Spawn it\n\nSame launch grammar as any agent (see [run-a-mesh.md](run-a-mesh.md)):\n\n```bash\ncotal spawn --agent codex # foreground in this terminal\ncotal spawn reviewer --agent codex -d # detached via the manager; watch with `cotal attach`\nCOTAL_DEFAULT_AGENT=codex cotal spawn # make codex the default harness\n```\n\nOr set `agent: codex` in a team [manifest](manifest.md). Persona, role, and model come from the\nagent file as for any connector ([agent-files.md](agent-files.md)).\n\n## Choose a model\n\n```bash\ncotal models --harness codex # ids + reasoning-effort variants, via app-server model/list\ncotal spawn --agent codex --model gpt-5.6-sol --variant high\n```\n\nThe **variant** is Codex's reasoning effort (`minimal` | `low` | `medium` | `high` | `xhigh`).\nLike the `codex` CLI itself, the connector does not validate model ids or efforts locally. An\nunknown value fails at request time, server-side.\n\nThe catalog comes from a short-lived `codex app-server`, the binary a launch runs:\n`COTAL_CODEX_BIN` when you set it, otherwise the absolute path the manager resolved at boot.\nIf it exits, closes its input, or does\nnot answer `model/list` within 10 seconds, `cotal models` reports that as the Codex error and the\nmanager keeps serving the other connectors.\n\nModel and variant are published on presence, which is where the web dashboard's `model · variant`\nbadge reads them from. The variant appears only when you asked for one (via\n`--variant` or `variant:` in the agent file): there is no way to read the effort back off a running\nthread, so an unset variant is shown as absent rather than guessed at.\n\n## How it binds\n\nCodex has no in-process plugin runtime and its MCP client cannot wake an idle session, so the\nconnector runs Codex's own client/server split: a small **host process** embeds the mesh\nendpoint and drives a `codex app-server` thread over JSON-RPC (the same protocol the Codex TUI\nruns on). The app-server runs as an authenticated loopback **listener** rather than a private\npipe, which is what lets Codex's own TUI attach to the very thread the mesh is driving.\n\n- **Wake and steer.** An inbound batch starts a real turn (`turn/start`). A DIRECTED message\n (DM, anycast, @mention) arriving during a connector-started turn is injected into that turn\n (`turn/steer`). During an externally started turn, the connector buffers the message and starts\n a delivery turn after the external turn ends. The external turn's completion cannot acknowledge\n a connector batch it did not carry. In focus mode, an @mention's pull hint can still steer an\n external turn; the message body stays on the inbox recall path. Ambient channel chatter waits\n for the turn boundary so it can't derail work in flight.\n- **Native tools, one endpoint.** The host serves the shared `cotal_*` tools itself, on a\n bearer-authenticated loopback MCP endpoint (the token is passed by env name, so it never appears\n in the process table; see [Limits](#limits) for what that token does and does not protect). The model calls them like any tool and they\n execute against the host's single mesh endpoint: no sidecar process, no second identity. The\n app-server is the MCP client, so the tools work the same on a turn a peer message started and\n on one **you** typed into the TUI.\n- **One managed conversation.** Only the thread the host drives can use its Cotal tools. Codex's\n native MCP request metadata identifies that thread, including turns typed in the attached TUI.\n Cotal tool calls from a second root thread are refused, rather than speaking with the managed\n conversation's identity. Native filesystem tools are not serialized across threads by Cotal.\n An app-server restart binds the replacement thread without creating a second mesh lifecycle.\n- **Ready means on the mesh.** The host announces `ready` and hands the terminal to Codex only\n after the app-server, MCP surface, and mesh endpoint are all live (including the initial\n presence publish). If the broker cannot be reached, startup fails within 15 seconds with the\n broker address and latest connection error; it never opens an offline-looking TUI.\n- **At-least-once delivery.** A turn's surfaced messages are acked (by exact id) when the turn\n completes, and also when the operator interrupts it (Escape in the attached TUI): that dismisses\n the batch rather than redelivering it. A failed turn retries with backoff, and an unknown terminal\n outcome (a missing or unrecognized status) leaves the batch un-acked with no retry of its own. If\n the Codex app-server itself dies, the host restarts it in place (same mesh identity, credential,\n and durable) and re-drives the un-acked batch into the new thread; a crash *loop* (more than 3 in\n 2 minutes) is fatal rather than an endless respawn. A retirement (the host shutting itself down)\n interrupts any live turn too, but that batch stays un-acked and redelivery to it is not promised:\n a later same-name spawn is a successor with its own delivery frontier. (The shared bounded-inbox\n overflow rule applies: under extreme bursts an evicted in-flight id cannot redeliver.)\n- **Isolated, never written.** Each agent gets a private `CODEX_HOME` (one hashed directory\n per space+name under `.cotal/codex/`, rooted at the manager's workspace): your `~/.codex`\n config.toml, hooks, and MCP servers never load into a managed agent, and Codex's per-project\n trust records never touch your real config. Your `auth.json` is symlinked in (re-linked each\n launch), so ChatGPT-plan token refreshes never fork. Without an `auth.json` (or an\n `OPENAI_API_KEY`) the launch fails loud at thread start. Keyring-stored credentials are not\n wired through the isolated home; use the file store or the env key for managed agents. That\n symlink is why managed Codex agents are **POSIX-only** today: on Windows without Developer\n Mode the link fails, and the launch fails loud rather than copying `auth.json` (a copy would\n fork the token and break plan refreshes).\n- **Autonomy defaults.** Spawned agents run `approval_policy=never`,\n `sandbox_mode=workspace-write`, and `sandbox_workspace_write={network_access=true}`.\n See [Sandbox autonomy](#sandbox-autonomy) for what each one means and how to\n change it.\n- **It really is Codex.** `cotal spawn --agent codex` drops you into the actual Codex TUI,\n attached to the thread the mesh drives (`codex resume --remote`). Mesh turns render as they\n happen, and anything you type is a real user turn on that same thread with the `cotal_*` tools\n still available. In the foreground that is your terminal; detached it is the manager's pty,\n which is what `cotal attach` streams and drives. With no terminal at all (piped output,\n CI, a smoke) the host stays headless and prints an activity feed instead: the same peer either\n way, only the UI differs.\n **Which mode you get** is decided by whether *stdout* is a terminal, and `COTAL_CODEX_TUI=1|0`\n overrides that check when it would guess wrong (a wrapper that redirects output, a CI run that\n wants deterministic text). The host refuses any value outside the on/off spellings in\n [Configuration](config.md#environment-variables) when it starts. It is read from the environment\n of **whichever process builds the launch**, so set it in the right place:\n - foreground `cotal spawn`: your own shell, per spawn;\n - detached (`-d`): the **manager's** environment, because the manager builds the launch. Set it\n where you start the manager (`COTAL_CODEX_TUI=0 cotal up`) and it applies to every codex agent\n that manager supervises. Exporting it in the shell that runs `cotal spawn -d` does nothing.\n\n A detached agent gets the manager's pty, which *is* a terminal, so the default there is the TUI,\n which is what `cotal attach` streams.\n Once the TUI paints, the terminal belongs to Codex, so the host's own diagnostics move to\n `host.log` inside the agent's private home\n (`<workspace>/.cotal/codex/<space>-<name>-<hash>/host.log`; the handoff line prints the exact\n path, and `ls -t .cotal/codex/*/host.log` finds it after the fact). Attached, a failure is also\n reported on the terminal; detached, that report goes to the pty, so the file is the durable copy.\n- **Presence from events.** working/idle/waiting are derived from the app-server event stream;\n approval requests relay an `approval` condition. A failed turn maps its native\n `codexErrorInfo` into the closed condition vocabulary and preserves that value in\n `condition.source`. Presence writes leave the host in the order the events arrived, so a\n turn that fails or asks for approval in the tick it started keeps its condition until the\n next turn starts. The model id is reported from the started thread.\n\n `contextWindowExceeded` maps to `context`; `sessionBudgetExceeded` to `budget`;\n `usageLimitExceeded` to `billing`; `rateLimitExceeded` to `rate_limit`;\n `serverOverloaded` to `overloaded`; `internalServerError` and `httpConnectionFailed` to\n `server`; `unauthorized` to `auth`; `badRequest`, `cyberPolicy`, and\n `misalignmentPolicyViolation` to `request`; and rollback, sandbox, `other`, or an unrecognized\n value to `failed`. An error marked `willRetry` maps to `retrying` while keeping its native source.\n\n`--opt k=v` launch options render as codex `-c k=v` config overrides on the app-server child\n(top-level keys, scalar values; write TOML inline-table text yourself for nested values). The\nconnector's own defaults and selectors ride the same rail and yield to yours, except\n`mcp_servers`, which is how the agent reaches the mesh: the whole namespace is refused loud (at\nspawn, not at launch) rather than silently overridden.\n\n## Event plane\n\nA spawned seat publishes a structured account of what it did: run\nboundaries per turn, assistant text, reasoning, and the tool calls the model makes through Codex's\nfunction-call and custom-tool interfaces, each with its start and its end. Tool arguments and\ntool results are not republished onto this channel. That covers the tools you watch a seat use,\n`shell` and `apply_patch` among them. The channel is\n`events.<owner>.<actor>`, named after the seat's principal, and the rules for it are the same on\nevery connector: see [connect-claude.md](connect-claude.md#event-plane) for the channel, the grant,\nand how to read it. The launcher sets `COTAL_EVENTS` by default; pass `--no-events` to opt out on an\nunrestricted space. A registration that requires events refuses `--no-events`, and its launch\nalways carries the flag and the workspace root the event log lives under. A hand-driven user-mode\nlaunch with `COTAL_EVENTS_REQUIRED=1` arms the plane without that flag.\nYour own `codex` publishes nothing unless its environment arms the plane.\n\n```bash\ncotal spawn watcher --agent codex -d # event plane armed; read it with `cotal console`\n```\n\nEight things are specific to Codex and worth knowing before you read a stream:\n\n- **The thread's rollout file is the durable record.** The seat's\n rollout lives inside its own isolated `CODEX_HOME`, under\n `<workspace>/.cotal/codex/<space>-<name>-<hash>/sessions/<yyyy>/<mm>/<dd>/rollout-<stamp>-<thread>.jsonl`.\n Reading the file rather than the stream is what lets the seat resume a thread's stream where it\n stopped after its own process restarts, rather than reopening it from the top.\n- **A restarted app-server is a NEW thread, and its stream is a new one.** When the child dies and\n the seat brings up a replacement, Codex starts a fresh thread with a fresh rollout. The seat\n finishes the old one first, publishing what it had and closing any run left open, then begins\n publishing the new thread under its own write-ahead log. A reader sees one stream end and another\n begin, never one stream silently continuing under a different thread. If the new thread's file is\n slow to appear the order is the other way round: the seat spends its whole bounded look for the new\n file first, and the old stream ends when that look gives up, not at the moment of the restart. From\n the give-up on it publishes nothing until the new thread binds at a later turn boundary; it does not\n keep reporting the dead thread's activity in the meantime.\n- **The stream starts where the seat binds to the file.** `thread/start` writes nothing to disk; the\n file appears when the thread is primed. The seat binds to it then, and publishes from that point\n forward. If the file is slow to appear the seat says so in its log and looks again at each turn\n boundary, and whatever the thread wrote before the bind is not republished. A seat stopped before\n it binds leaves without binding.\n- **Codex's built-in tools remain private to the host.** Web search, tool search and image generation\n record an end with no start, and nothing joins the two halves: the start-shaped record carries no\n call id and the end carries one. Rather than guess a pairing, the seat drops them, so those tool\n uses are absent from the stream while everything on the function-call path is present.\n- **Failed turns publish run errors.** Codex records a failure on\n the turn's own completion record, so a turn that hit a usage limit or an upstream error ends its\n run with `RUN_ERROR` carrying the fixed message `run failed` and no code. Neither Codex's error\n text nor its `codex_error_info` is published there: both are upstream values that can echo your\n prompt or tool output, and the events channel has a different read ACL.\n- **No user-authored text is published, ever.** Your prompts, the peer messages injected into the\n thread, and the developer instructions the persona supplies are all withheld. The events channel\n carries a different read ACL from the channel you typed into, so republishing your own words there\n would widen who can read them. Assistant text, reasoning and tool activity are unaffected.\n- **A broker outage can stop the plane.** Initial mesh absence still\n fails the host's readiness gate within 15 seconds, so it never opens an offline-looking TUI. Once\n ready, the plane publishes through the seat's reconnecting mesh endpoint, and an outage can stop\n its emitter. The seat keeps running on every space, its log records `AG-UI emitter stopped` with\n the delay before the plane is re-established, and the thread publishes again from its stored\n cursor once that succeeds.\n Tool arguments and tool results are not published. The stream also does not carry the\n session's own record of the user's words and the developer instructions. A bind announces\n where the stream starts and the emitter's setup then runs before its first read; what the\n thread appends inside that window is published rather than left behind the cursor, and a whole\n turn can sit in there. Nothing is sent twice. The boundary itself is written to the log as soon\n as the bind succeeds, so a host that dies before its first read still resumes from that boundary\n rather than from wherever the file ends by the time it comes back.\n\n The grant still does not decide who may READ a plane. A spawn through the manager gives a seat\n publish rights on its own event channel and nothing else, and a spawn whose grant names a\n different agent's event channel is refused at the door. That fence is the manager's, it reads\n the concrete form and leaves a pattern such as `events.<owner>.>` to ordinary ACL authority,\n and a foreground `cotal spawn` on your own machine grants whatever you name because it mints\n from your own signing material. [connect-claude.md](connect-claude.md#event-plane) spells all\n three out. Who may READ a plane is minted separately and out of band either way, with\n `cotal actor grant` on a user-auth mesh and `cotal auth mint --profile agent --allow-subscribe` on a\n static one. Who may read the plane is still that mint, not the spawn grant.\n- **Reasoning is published as its summary only.** Codex also stores an encrypted reasoning blob on\n every reasoning record; it is opaque, no reader can display it, and it is never put on the wire.\n\n## Sandbox autonomy\n\nA spawned Codex agent is woken by peer messages, which arrive when nobody is watching the\nterminal. The defaults follow from that, and all three are overridable per spawn with `--opt`.\n\n| Default | What it means |\n| --- | --- |\n| `approval_policy=\"never\"` | Never **ask** before running a command. Not \"refuse\": the agent runs its commands, it just does not stop to prompt. An interactive policy is refused loud rather than honored dishonestly, because a mesh-driven turn would block forever on a prompt nobody sees, and the alternative (auto-answering for you) nullifies the policy you asked for. |\n| `sandbox_mode=\"workspace-write\"` | Commands may read anywhere but write only inside the agent's workspace. This, not the prompt, is the part that is actually enforced; see below for the (real) exposure it leaves. |\n| `sandbox_workspace_write={network_access=true}` | Network **on** inside that sandbox. Codex's own default is off, which breaks installing a dependency, pushing a branch, or calling an API, with an error that reads like the task is impossible rather than the sandbox saying no. Applied only when the sandbox is actually `workspace-write`: tighten the mode and no network grant is emitted at all. |\n\nWhat the sandbox guarantees, stated literally: it **blocks out-of-workspace local filesystem\nwrites**. It does **not** block reads, exfiltration, or networked side effects.\n\nAll three of those are live with the defaults above, because a peer's message is a **remote input**\nthat can cause this agent to run commands. A confused or hostile peer can in principle get it to\nread a file elsewhere on your machine and send it; reach loopback or link-local services; or act\nthrough any credential it can read, which includes irreversible actions: a force-push, an API\ndelete, a deploy. Containing filesystem writes is therefore not the same as containing damage, and\nit should not be read that way. It is still worth keeping, because it is the one class this sandbox\ncan actually enforce.\n\nIf that exposure is wrong for a given agent, turn the network back off (below), tighten the mode,\nor run it under a separate OS user; the same point is repeated under [Limits](#limits) so it\nsurvives a skim. The spawn capability is the trust boundary for *who* may create an agent; the\nsandbox bounds one class of what it can then be talked into doing, not all of it.\n\nTune it per spawn:\n\n```bash\ncotal spawn --agent codex --opt sandbox_mode=read-only # tightest: no writes\ncotal spawn --agent codex --opt 'sandbox_workspace_write={network_access=false}' # contained, offline\ncotal spawn --agent codex --opt sandbox_mode=danger-full-access # no sandbox at all\n```\n\n`danger-full-access` is Codex's own name for it and means what it says: the agent may write\nanywhere your user account can. Codex documents that mode as intended only for environments that\nare already externally sandboxed (a container, a VM), not a workstation. On a laptop, prefer\ntightening the workspace over removing the sandbox.\n\n## Limits\n\n- **The sandbox blocks out-of-workspace filesystem writes, and only that.** It does not block\n reads, exfiltration, or networked side effects. With the default `workspace-write` + network on,\n a peer-driven turn can read anything your user account can (`~/.ssh`, `~/.aws`, `.env` files, the\n agent's own `auth.json`) and send it; reach loopback and link-local services; and act through any\n credential it can read, including irreversibly (a force-push, an API delete, a deploy). Only\n local writes outside the workspace are stopped, so this is not \"everything risky is reversible\"\n and not \"the only exposure is disclosure\". If that is wrong for a given agent, spawn it with\n `--opt 'sandbox_workspace_write={network_access=false}'` or `--opt sandbox_mode=read-only`, or\n run it as a separate OS user. See [Sandbox autonomy](#sandbox-autonomy).\n- **Not a boundary between agents on one machine.** The app-server listener and the tool\n endpoint are both loopback-bound and token-authenticated, which keeps out other OS users and\n anything off-box. It is not isolation between *managed agents*, which run as the same user and\n can therefore reach each other's tokens; a hostile agent on your workstation could drive\n another's Codex or speak as it on the mesh. Run mutually distrusted agents under separate OS\n users or separate machines.\n- **The TUI is local-only.** The app-server listener binds loopback and nothing else, so\n attaching Codex's UI to an agent on another machine needs your own SSH port-forward; there is\n no built-in remote attach. `cotal attach` (which streams the manager's pty) is the supported\n way to reach a detached agent.\n- **`/new` does not replace the managed conversation.** The attached TUI can open a different\n thread, but the host keeps driving its original thread. Cotal tool calls from the other thread\n fail with an explanation naming the managed thread. Return to that thread in Codex, or spawn\n a separate Cotal seat for another conversation. There is no thread migration or hook recovery.\n- **No session resume.** `cotal spawn --resume <id>` throws: a resumed codex thread comes up\n without its configured MCP servers, so the agent would be mute on the mesh.\n- **No tool-sharing.** `connectors.codex.mcpServers` is not implemented and throws if set.\n- **Experimental upstream surface.** `codex app-server` is labeled experimental by OpenAI (it\n is also what the Codex TUI itself runs on). The connector pins every protocol shape in one\n driver file and re-proves the contract with a gated live smoke (`COTAL_E2E_CODEX=1`).\n\n## See also\n\n- [Connectors](connectors.md): the feature matrix across all connectors\n- [Run a mesh](run-a-mesh.md) · [Define a team](define-a-team.md) · [Watch a mesh](watch-a-mesh.md)\n- [MCP tools](mcp-tools.md) · [Connect Claude Code](connect-claude.md) · [Connect OpenCode](connect-opencode.md)\n"
|
|
126
|
+
"body": "# Connect Codex (beta)\n\n> **Guide** (informative) · **For:** operators · **Prereqs:** [Quickstart](getting-started.md)\n\n[OpenAI Codex](https://developers.openai.com/codex/) joins a Cotal mesh as a lateral peer: the\nsame `cotal_*` tool surface, the same message delivery and attention model as the other\nconnectors, plus mid-turn steering: a directed peer message arriving during a\nconnector-started turn is **steered into that turn** instead of waiting for it to end.\nMessage batches arriving during a turn started in the attached TUI or by Codex itself,\nincluding a native goal continuation, wait for that turn to end before the connector starts\na delivery turn.\n\n**Beta** means the everyday path (spawn into the real Codex TUI, coordinate, watch) works; the\nspawn options that are not wired **fail loud** rather than degrade: resuming a session\n(`--resume`) and tool-sharing (`connectors.codex.mcpServers`). See [Limits](#limits).\n\n## Install\n\nThe connector ships with the CLI as a seeded extension (`@cotal-ai/connector-codex`): no\nseparate install step and no Codex-side plugin. You only need an authenticated `codex` binary\non your PATH (a ChatGPT-plan login or an `OPENAI_API_KEY`). If an older install is missing it,\n`cotal ext seed` (or `cotal ext add @cotal-ai/connector-codex`) brings it in. Use\n`cotal ext seed --repair` when an earlier seed failed or was interrupted.\n\n**Don't install the `cotal` plugin Codex offers you.** Searching Codex's plugin list for \"cotal\"\nturns up a plugin named `cotal`, from the `cotal-mesh` marketplace. That is the **Claude Code**\nadapter, which appears there only because Codex reads the same plugin-marketplace format; it is\nnot this connector and installing it does not connect Codex to a mesh. Codex needs nothing\ninstalled on its side: the connector drives it from the outside, over `codex app-server`.\n\n**Codex version.** The connector drives `codex app-server` over its experimental v2 surface.\nMinimum **codex-cli 0.145.0**; tested against 0.145.0 and 0.146.0. An older binary authenticates fine but has\nno `--listen`/`--ws-auth` listener, so the launch fails at startup rather than misbehaving quietly:\ncheck with `codex --version` and upgrade (`npm i -g @openai/codex`) if a launch reports that the\napp-server exited before it started listening. The surface is explicitly experimental upstream, so\na later Codex release may change it and need a connector update. That is a break to report, not a\nsupport range we can promise ahead of it.\n\n## Spawn it\n\nSame launch grammar as any agent (see [run-a-mesh.md](run-a-mesh.md)):\n\n```bash\ncotal spawn --agent codex # foreground in this terminal\ncotal spawn reviewer --agent codex -d # detached via the manager; watch with `cotal attach`\nCOTAL_DEFAULT_AGENT=codex cotal spawn # make codex the default harness\n```\n\nOr set `agent: codex` in a team [manifest](manifest.md). Persona, role, and model come from the\nagent file as for any connector ([agent-files.md](agent-files.md)).\n\n## Choose a model\n\n```bash\ncotal models --harness codex # ids + reasoning-effort variants, via app-server model/list\ncotal spawn --agent codex --model gpt-5.6-sol --variant high\n```\n\nThe **variant** is Codex's reasoning effort (`minimal` | `low` | `medium` | `high` | `xhigh`).\nLike the `codex` CLI itself, the connector does not validate model ids or efforts locally. An\nunknown value fails at request time, server-side.\n\nThe catalog comes from a short-lived `codex app-server`, the binary a launch runs:\n`COTAL_CODEX_BIN` when you set it, otherwise the absolute path the manager resolved at boot.\nIf it exits, closes its input, or does\nnot answer `model/list` within 10 seconds, `cotal models` reports that as the Codex error and the\nmanager keeps serving the other connectors.\n\nModel and variant are published on presence, which is where the web dashboard's `model · variant`\nbadge reads them from. The variant appears only when you asked for one (via\n`--variant` or `variant:` in the agent file): there is no way to read the effort back off a running\nthread, so an unset variant is shown as absent rather than guessed at.\n\n## How it binds\n\nCodex has no in-process plugin runtime and its MCP client cannot wake an idle session, so the\nconnector runs Codex's own client/server split: a small **host process** embeds the mesh\nendpoint and drives a `codex app-server` thread over JSON-RPC (the same protocol the Codex TUI\nruns on). The app-server runs as an authenticated loopback **listener** rather than a private\npipe, which is what lets Codex's own TUI attach to the very thread the mesh is driving.\n\n- **Wake and steer.** An inbound batch starts a real turn (`turn/start`). A DIRECTED message\n (DM, anycast, @mention) arriving during a connector-started turn is injected into that turn\n (`turn/steer`). During an externally started turn, the connector buffers the message and starts\n a delivery turn after the external turn ends. The external turn's completion cannot acknowledge\n a connector batch it did not carry. In focus mode, an @mention's pull hint can still steer an\n external turn; the message body stays on the inbox recall path. Ambient channel chatter waits\n for the turn boundary so it can't derail work in flight.\n- **Native tools, one endpoint.** The host serves the shared `cotal_*` tools itself, on a\n bearer-authenticated loopback MCP endpoint (the token is passed by env name, so it never appears\n in the process table; see [Limits](#limits) for what that token does and does not protect). The model calls them like any tool and they\n execute against the host's single mesh endpoint: no sidecar process, no second identity. The\n app-server is the MCP client, so the tools work the same on a turn a peer message started and\n on one **you** typed into the TUI.\n- **One managed conversation.** Only the thread the host drives can use its Cotal tools. Codex's\n native MCP request metadata identifies that thread, including turns typed in the attached TUI.\n Cotal tool calls from a second root thread are refused, rather than speaking with the managed\n conversation's identity. Native filesystem tools are not serialized across threads by Cotal.\n An app-server restart binds the replacement thread without creating a second mesh lifecycle.\n- **Ready means on the mesh.** The host announces `ready` and hands the terminal to Codex only\n after the app-server, MCP surface, and mesh endpoint are all live (including the initial\n presence publish). If the broker cannot be reached, startup fails within 15 seconds with the\n broker address and latest connection error; it never opens an offline-looking TUI.\n- **At-least-once delivery.** A turn's surfaced messages are acked (by exact id) when the turn\n completes, and also when the operator interrupts it (Escape in the attached TUI): that dismisses\n the batch rather than redelivering it. A failed turn retries with backoff, and an unknown terminal\n outcome (a missing or unrecognized status) leaves the batch un-acked with no retry of its own. If\n the Codex app-server itself dies, the host restarts it in place (same mesh identity, credential,\n and durable) and re-drives the un-acked batch into the new thread; a crash *loop* (more than 3 in\n 2 minutes) is fatal rather than an endless respawn. A retirement (the host shutting itself down)\n interrupts any live turn too, but that batch stays un-acked and redelivery to it is not promised:\n a later same-name spawn is a successor with its own delivery frontier. (The shared bounded-inbox\n overflow rule applies: under extreme bursts an evicted in-flight id cannot redeliver.)\n- **Isolated, never written.** Each agent gets a private `CODEX_HOME` (one hashed directory\n per space+name under `.cotal/codex/`, rooted at the manager's workspace): your `~/.codex`\n config.toml, hooks, and MCP servers never load into a managed agent, and Codex's per-project\n trust records never touch your real config. Your `auth.json` is symlinked in (re-linked each\n launch), so ChatGPT-plan token refreshes never fork. Without an `auth.json` (or an\n `OPENAI_API_KEY`) the launch fails loud at thread start. Keyring-stored credentials are not\n wired through the isolated home; use the file store or the env key for managed agents. That\n symlink is why managed Codex agents are **POSIX-only** today: on Windows without Developer\n Mode the link fails, and the launch fails loud rather than copying `auth.json` (a copy would\n fork the token and break plan refreshes).\n- **Autonomy defaults.** Spawned agents run `approval_policy=never`,\n `sandbox_mode=workspace-write`, and `sandbox_workspace_write={network_access=true}`.\n See [Sandbox autonomy](#sandbox-autonomy) for what each one means and how to\n change it.\n- **It really is Codex.** `cotal spawn --agent codex` drops you into the actual Codex TUI,\n attached to the thread the mesh drives (`codex resume --remote`). Mesh turns render as they\n happen, and anything you type is a real user turn on that same thread with the `cotal_*` tools\n still available. In the foreground that is your terminal; detached it is the manager's pty,\n which is what `cotal attach` streams and drives. With no terminal at all (piped output,\n CI, a smoke) the host stays headless and prints an activity feed instead: the same peer either\n way, only the UI differs.\n **Which mode you get** is decided by whether *stdout* is a terminal, and `COTAL_CODEX_TUI=1|0`\n overrides that check when it would guess wrong (a wrapper that redirects output, a CI run that\n wants deterministic text). The host refuses any value outside the on/off spellings in\n [Configuration](config.md#environment-variables) when it starts. It is read from the environment\n of **whichever process builds the launch**, so set it in the right place:\n - foreground `cotal spawn`: your own shell, per spawn;\n - detached (`-d`): the **manager's** environment, because the manager builds the launch. Set it\n where you start the manager (`COTAL_CODEX_TUI=0 cotal up`) and it applies to every codex agent\n that manager supervises. Exporting it in the shell that runs `cotal spawn -d` does nothing.\n\n A detached agent gets the manager's pty, which *is* a terminal, so the default there is the TUI,\n which is what `cotal attach` streams.\n Once the TUI paints, the terminal belongs to Codex, so the host's own diagnostics move to\n `host.log` inside the agent's private home\n (`<workspace>/.cotal/codex/<space>-<name>-<hash>/host.log`; the handoff line prints the exact\n path, and `ls -t .cotal/codex/*/host.log` finds it after the fact). Attached, a failure is also\n reported on the terminal; detached, that report goes to the pty, so the file is the durable copy.\n- **Presence from events.** working/idle/waiting are derived from the app-server event stream;\n a user-input request's temporary waiting presence does not end the host turn. A completed\n native turn still yields `done` for its surfaced workflow turn after the host answers a\n user-input request, even if no later command or MCP item runs. Explicit `blocked` and\n `handoff` yields remain unchanged.\n Approval requests relay an `approval` condition. A failed turn maps its native\n `codexErrorInfo` into the closed condition vocabulary and preserves that value in\n `condition.source`. Presence writes leave the host in the order the events arrived, so a\n turn that fails or asks for approval in the tick it started keeps its condition until the\n next turn starts. The model id is reported from the started thread.\n\n `contextWindowExceeded` maps to `context`; `sessionBudgetExceeded` to `budget`;\n `usageLimitExceeded` to `billing`; `rateLimitExceeded` to `rate_limit`;\n `serverOverloaded` to `overloaded`; `internalServerError` and `httpConnectionFailed` to\n `server`; `unauthorized` to `auth`; `badRequest`, `cyberPolicy`, and\n `misalignmentPolicyViolation` to `request`; and rollback, sandbox, `other`, or an unrecognized\n value to `failed`. An error marked `willRetry` maps to `retrying` while keeping its native source.\n\n`--opt k=v` launch options render as codex `-c k=v` config overrides on the app-server child\n(top-level keys, scalar values; write TOML inline-table text yourself for nested values). The\nconnector's own defaults and selectors ride the same rail and yield to yours, except\n`mcp_servers`, which is how the agent reaches the mesh: the whole namespace is refused loud (at\nspawn, not at launch) rather than silently overridden.\n\n## Event plane\n\nA spawned seat publishes a structured account of what it did: run\nboundaries per turn, assistant text, reasoning, and the tool calls the model makes through Codex's\nfunction-call and custom-tool interfaces, each with its start and its end. Tool arguments and\ntool results are not republished onto this channel. That covers the tools you watch a seat use,\n`shell` and `apply_patch` among them. The channel is\n`events.<owner>.<actor>`, named after the seat's principal, and the rules for it are the same on\nevery connector: see [connect-claude.md](connect-claude.md#event-plane) for the channel, the grant,\nand how to read it. The launcher sets `COTAL_EVENTS` by default; pass `--no-events` to opt out on an\nunrestricted space. A registration that requires events refuses `--no-events`, and its launch\nalways carries the flag and the workspace root the event log lives under. A hand-driven user-mode\nlaunch with `COTAL_EVENTS_REQUIRED=1` arms the plane without that flag.\nYour own `codex` publishes nothing unless its environment arms the plane.\n\n```bash\ncotal spawn watcher --agent codex -d # event plane armed; read it with `cotal console`\n```\n\nEight things are specific to Codex and worth knowing before you read a stream:\n\n- **The thread's rollout file is the durable record.** The seat's\n rollout lives inside its own isolated `CODEX_HOME`, under\n `<workspace>/.cotal/codex/<space>-<name>-<hash>/sessions/<yyyy>/<mm>/<dd>/rollout-<stamp>-<thread>.jsonl`.\n Reading the file rather than the stream is what lets the seat resume a thread's stream where it\n stopped after its own process restarts, rather than reopening it from the top.\n- **A restarted app-server is a NEW thread, and its stream is a new one.** When the child dies and\n the seat brings up a replacement, Codex starts a fresh thread with a fresh rollout. The seat\n finishes the old one first, publishing what it had and closing any run left open, then begins\n publishing the new thread under its own write-ahead log. A reader sees one stream end and another\n begin, never one stream silently continuing under a different thread. If the new thread's file is\n slow to appear the order is the other way round: the seat spends its whole bounded look for the new\n file first, and the old stream ends when that look gives up, not at the moment of the restart. From\n the give-up on it publishes nothing until the new thread binds at a later turn boundary; it does not\n keep reporting the dead thread's activity in the meantime.\n- **The stream starts where the seat binds to the file.** `thread/start` writes nothing to disk; the\n file appears when the thread is primed. The seat binds to it then, and publishes from that point\n forward. If the file is slow to appear the seat says so in its log and looks again at each turn\n boundary, and whatever the thread wrote before the bind is not republished. A seat stopped before\n it binds leaves without binding.\n- **Codex's built-in tools remain private to the host.** Web search, tool search and image generation\n record an end with no start, and nothing joins the two halves: the start-shaped record carries no\n call id and the end carries one. Rather than guess a pairing, the seat drops them, so those tool\n uses are absent from the stream while everything on the function-call path is present.\n- **Failed turns publish run errors.** Codex records a failure on\n the turn's own completion record, so a turn that hit a usage limit or an upstream error ends its\n run with `RUN_ERROR` carrying the fixed message `run failed` and no code. Neither Codex's error\n text nor its `codex_error_info` is published there: both are upstream values that can echo your\n prompt or tool output, and the events channel has a different read ACL.\n- **No user-authored text is published, ever.** Your prompts, the peer messages injected into the\n thread, and the developer instructions the persona supplies are all withheld. The events channel\n carries a different read ACL from the channel you typed into, so republishing your own words there\n would widen who can read them. Assistant text, reasoning and tool activity are unaffected.\n- **A broker outage can stop the plane.** Initial mesh absence still\n fails the host's readiness gate within 15 seconds, so it never opens an offline-looking TUI. Once\n ready, the plane publishes through the seat's reconnecting mesh endpoint, and an outage can stop\n its emitter. The seat keeps running on every space, its log records `AG-UI emitter stopped` with\n the delay before the plane is re-established, and the thread publishes again from its stored\n cursor once that succeeds.\n Tool arguments and tool results are not published. The stream also does not carry the\n session's own record of the user's words and the developer instructions. A bind announces\n where the stream starts and the emitter's setup then runs before its first read; what the\n thread appends inside that window is published rather than left behind the cursor, and a whole\n turn can sit in there. Nothing is sent twice. The boundary itself is written to the log as soon\n as the bind succeeds, so a host that dies before its first read still resumes from that boundary\n rather than from wherever the file ends by the time it comes back.\n\n The grant still does not decide who may READ a plane. A spawn through the manager gives a seat\n publish rights on its own event channel and nothing else, and a spawn whose grant names a\n different agent's event channel is refused at the door. That fence is the manager's, it reads\n the concrete form and leaves a pattern such as `events.<owner>.>` to ordinary ACL authority,\n and a foreground `cotal spawn` on your own machine grants whatever you name because it mints\n from your own signing material. [connect-claude.md](connect-claude.md#event-plane) spells all\n three out. Who may READ a plane is minted separately and out of band either way, with\n `cotal actor grant` on a user-auth mesh and `cotal auth mint --profile agent --allow-subscribe` on a\n static one. Who may read the plane is still that mint, not the spawn grant.\n- **Reasoning is published as its summary only.** Codex also stores an encrypted reasoning blob on\n every reasoning record; it is opaque, no reader can display it, and it is never put on the wire.\n\n## Sandbox autonomy\n\nA spawned Codex agent is woken by peer messages, which arrive when nobody is watching the\nterminal. The defaults follow from that, and all three are overridable per spawn with `--opt`.\n\n| Default | What it means |\n| --- | --- |\n| `approval_policy=\"never\"` | Never **ask** before running a command. Not \"refuse\": the agent runs its commands, it just does not stop to prompt. An interactive policy is refused loud rather than honored dishonestly, because a mesh-driven turn would block forever on a prompt nobody sees, and the alternative (auto-answering for you) nullifies the policy you asked for. |\n| `sandbox_mode=\"workspace-write\"` | Commands may read anywhere but write only inside the agent's workspace. This, not the prompt, is the part that is actually enforced; see below for the (real) exposure it leaves. |\n| `sandbox_workspace_write={network_access=true}` | Network **on** inside that sandbox. Codex's own default is off, which breaks installing a dependency, pushing a branch, or calling an API, with an error that reads like the task is impossible rather than the sandbox saying no. Applied only when the sandbox is actually `workspace-write`: tighten the mode and no network grant is emitted at all. |\n\nWhat the sandbox guarantees, stated literally: it **blocks out-of-workspace local filesystem\nwrites**. It does **not** block reads, exfiltration, or networked side effects.\n\nAll three of those are live with the defaults above, because a peer's message is a **remote input**\nthat can cause this agent to run commands. A confused or hostile peer can in principle get it to\nread a file elsewhere on your machine and send it; reach loopback or link-local services; or act\nthrough any credential it can read, which includes irreversible actions: a force-push, an API\ndelete, a deploy. Containing filesystem writes is therefore not the same as containing damage, and\nit should not be read that way. It is still worth keeping, because it is the one class this sandbox\ncan actually enforce.\n\nIf that exposure is wrong for a given agent, turn the network back off (below), tighten the mode,\nor run it under a separate OS user; the same point is repeated under [Limits](#limits) so it\nsurvives a skim. The spawn capability is the trust boundary for *who* may create an agent; the\nsandbox bounds one class of what it can then be talked into doing, not all of it.\n\nTune it per spawn:\n\n```bash\ncotal spawn --agent codex --opt sandbox_mode=read-only # tightest: no writes\ncotal spawn --agent codex --opt 'sandbox_workspace_write={network_access=false}' # contained, offline\ncotal spawn --agent codex --opt sandbox_mode=danger-full-access # no sandbox at all\n```\n\n`danger-full-access` is Codex's own name for it and means what it says: the agent may write\nanywhere your user account can. Codex documents that mode as intended only for environments that\nare already externally sandboxed (a container, a VM), not a workstation. On a laptop, prefer\ntightening the workspace over removing the sandbox.\n\n## Limits\n\n- **The sandbox blocks out-of-workspace filesystem writes, and only that.** It does not block\n reads, exfiltration, or networked side effects. With the default `workspace-write` + network on,\n a peer-driven turn can read anything your user account can (`~/.ssh`, `~/.aws`, `.env` files, the\n agent's own `auth.json`) and send it; reach loopback and link-local services; and act through any\n credential it can read, including irreversibly (a force-push, an API delete, a deploy). Only\n local writes outside the workspace are stopped, so this is not \"everything risky is reversible\"\n and not \"the only exposure is disclosure\". If that is wrong for a given agent, spawn it with\n `--opt 'sandbox_workspace_write={network_access=false}'` or `--opt sandbox_mode=read-only`, or\n run it as a separate OS user. See [Sandbox autonomy](#sandbox-autonomy).\n- **Not a boundary between agents on one machine.** The app-server listener and the tool\n endpoint are both loopback-bound and token-authenticated, which keeps out other OS users and\n anything off-box. It is not isolation between *managed agents*, which run as the same user and\n can therefore reach each other's tokens; a hostile agent on your workstation could drive\n another's Codex or speak as it on the mesh. Run mutually distrusted agents under separate OS\n users or separate machines.\n- **The TUI is local-only.** The app-server listener binds loopback and nothing else, so\n attaching Codex's UI to an agent on another machine needs your own SSH port-forward; there is\n no built-in remote attach. `cotal attach` (which streams the manager's pty) is the supported\n way to reach a detached agent.\n- **`/new` does not replace the managed conversation.** The attached TUI can open a different\n thread, but the host keeps driving its original thread. Cotal tool calls from the other thread\n fail with an explanation naming the managed thread. Return to that thread in Codex, or spawn\n a separate Cotal seat for another conversation. There is no thread migration or hook recovery.\n- **No session resume.** `cotal spawn --resume <id>` throws: a resumed codex thread comes up\n without its configured MCP servers, so the agent would be mute on the mesh.\n- **No tool-sharing.** `connectors.codex.mcpServers` is not implemented and throws if set.\n- **Experimental upstream surface.** `codex app-server` is labeled experimental by OpenAI (it\n is also what the Codex TUI itself runs on). The connector pins every protocol shape in one\n driver file and re-proves the contract with a gated live smoke (`COTAL_E2E_CODEX=1`).\n\n## See also\n\n- [Connectors](connectors.md): the feature matrix across all connectors\n- [Run a mesh](run-a-mesh.md) · [Define a team](define-a-team.md) · [Watch a mesh](watch-a-mesh.md)\n- [MCP tools](mcp-tools.md) · [Connect Claude Code](connect-claude.md) · [Connect OpenCode](connect-opencode.md)\n"
|
|
127
127
|
},
|
|
128
128
|
{
|
|
129
129
|
"slug": "connect-hermes",
|
|
@@ -163,7 +163,7 @@ export function loadDocsBundle() {
|
|
|
163
163
|
"kind": "Guide (informative)",
|
|
164
164
|
"category": "Guide",
|
|
165
165
|
"summary": "Every connector puts a real agent session on the mesh with the same cotal tools, presence, and delivery model (MCP tools).",
|
|
166
|
-
"body": "# Connectors\n\n> **Guide** (informative) · **For:** operators picking a harness · **Prereqs:** none\n\nEvery connector puts a real agent session on the mesh with the same `cotal_*` tools, presence,\nand delivery model ([MCP tools](mcp-tools.md)). They differ in how they bind to their harness\nand which spawn features are wired. Anything unwired **fails loud**: a flag a connector does\nnot support throws; nothing silently degrades.\n\nConnectors track raw NATS transport liveness separately from endpoint readiness. A short broker\ndisconnect marks the transport down until nats.js reconnects, without claiming that the connector's\nfull Cotal bind was torn down and rebuilt. A clean connector stop clears both states locally.\nIf a post-connect bind fails, the endpoint closes that partial connection and reports both\ntransport and connection down before retrying.\nThe endpoint `transport` event reports edges and is not replayed to listeners attached later. A\nconnector that needs current state reads its `MeshAgent.transportConnected` value, then listens for\nlater edges.\n`MeshAgent.connectionIssue` records the latest failure before a successful bind. A later bind clears\nit; stopping preserves it so an operator can inspect why the session never connected or last dropped.\n\n| | [Claude Code](connect-claude.md) | [OpenCode](connect-opencode.md) | [Codex](connect-codex.md) | [Hermes](connect-hermes.md) | [Jcode](connect-jcode.md) | [pi](connect-pi.md) |\n|---|---|---|---|---|---|---|\n| Maturity | stable | beta | beta | alpha | beta | alpha |\n| Binds via | installed plugin + MCP server | in-process plugin (native runtime) | host-mode peer driving `codex app-server` | native Python plugin, socket-bridged | host-mode peer driving Jcode Harness API | native pi extension, in-process |\n| Install | `cotal setup` | none, just `opencode` on PATH (1.x or 2.x) | seeded with the CLI; needs an authenticated `codex` on PATH | BYO `uv` + `hermes-agent` `>=0.18,<0.22`; Unix only | seeded with the CLI; needs `jcode` 0.78.1+ on PATH | pi 0.79.10 (one copied file for interactive/SDK) |\n| Watch the real TUI | ✓ | ✓ | ✓ (attached to the mesh-driven thread) | ✗ (headless gateway) | ✓ (attached to the managed Jcode session) | ✓ |\n| Inbound delivery | managed hook drain + idle nudge; personal native inline delivery | injected as a turn | wakes a turn; directed messages steer connector-started turns; external turns defer delivery | fresh agent per message | injected as a Harness API turn; directed messages steer the live session | steered into the live turn |\n| Mid-turn steering | personal native sessions at supported boundaries | ✗ | ✓ (directed messages during connector-started turns) | none | ✓ (directed messages) | ✓ |\n| Session resume (`--resume`) | ✓ (forks) | ✗ ([#154](https://github.com/Cotal-AI/Cotal/issues/154)) | ✗ (a resumed thread has no MCP tools upstream) | ✓ (forks) | ✓ (forks) | ✓ (forks) |\n| Tool-sharing (`--share-tools`) | ✓ (setup shares your servers; narrow per spawn) | ✗ (inherits your servers wholesale) | ✗ (isolated per-agent `CODEX_HOME`) | ✗ | ✗ (private MCP configuration) | ✗ |\n| Models | `--model` | `--model` + catalog (`cotal models`) (1.x) + `--variant` | `--model` + catalog (`cotal models`) + `--variant` (reasoning effort) | any provider, via env | `--model` + `--variant` (reasoning effort) | `--model` |\n| Event plane (default on; `--no-events` opts out) | ✓ | ✓ (1.x); 2.x needs `--no-events` | ✓ | ✗ (requires `--no-events`) | ✓ | ✓ (completed messages) |\n| `cotal_*` tool transport | stdio MCP, no listener | loopback, per-launch Basic secret | loopback MCP, per-host bearer | Unix socket, control token on the first frame | stdio MCP bridge relayed over a Unix socket, per-instance token | in-process, no listener |\n| Containers ([deploy](deploy.md)) | ✓ | ✓ | ✗ | ✗ | ✗ | ✗ |\n\nThe Manager reports the same support fact as `status.connectors[].eventPlane`. Clients use that\ntyped field instead of copying this table. On a space whose policy requires events, a false value\nmeans the connector cannot launch there. Spawn remains the authority and keeps the policy refusal.\n\nThe tool transport row covers only how the `cotal_*` tools reach the mesh endpoint. A managed seat\non every connector also has connector-core's authenticated local control socket, which carries\nlifecycle hooks and stop requests ([authoring a connector](authoring-a-connector.md#local-listeners)).\n\n**Resume provenance.** The manager records the session a `--resume` seat forked on the seat's resume\ndocument, and `cotal ps --wide` and `--json` show it. Hermes and Jcode seats fork after they launch,\nso they also record the source title and a SHA-256 of the transcript they read, which the manager\npicks up once the fork exists. Each of those seats also prints the three facts in its own output\nwhen it forks.\n\n**Native vs. bridged.** OpenCode and pi expose real plugin runtimes, so the connector runs\ninside the host process; pi most directly: peer messages steer the live turn instead of\nwaiting for it to end. Managed Claude Code sessions compose an MCP tool server, lifecycle hooks\nand an idle-wake channel. Personally opened Code sessions use the installed native hooks module\nfor idle and busy-boundary delivery. Complete short messages need no extra inbox call; larger\nmessages retain a preview and the inbox path. The other connectors already inject full message\ncontent through their existing native paths. Native admission or completion accounting remains\nspecific to each host; queue acceptance does not prove the model consumed a message. Presence\nwrites issued by one agent land in the order they were made, and departure is published after\nevery write already in flight; a write admitted after departure began is refused rather than\nreordered behind it. Codex has\nno plugin runtime either and its MCP client cannot wake an idle session, so the connector runs\na host-mode peer over Codex's own app-server protocol (the one the Codex TUI runs on): real\nwake, mid-turn steer, and the `cotal_*` tools served from the host over a loopback MCP endpoint.\nThis also keeps them working on a turn typed into the attached Codex TUI. Hermes runs a\nnative plugin inside its Python gateway, bridged to the connector over a local socket; the\ngateway model starts a fresh agent per inbound message, so there is no live turn to steer. Jcode's\nstable Harness API is a Unix-socket NDJSON bridge: the connector starts one private instance,\ncreates one session, and calls its documented stdio MCP configuration from a private `JCODE_HOME`.\nDirected peer messages that arrive while that session is busy enter Jcode's session-owned\nsoft-interrupt queue.\n\nEach guide covers spawn forms, model selection, and the limits: [Claude\nCode](connect-claude.md) · [OpenCode](connect-opencode.md) · [Codex](connect-codex.md) ·\n[Hermes](connect-hermes.md) · [Jcode](connect-jcode.md) · [pi](connect-pi.md).\n\n**Picking the harness at spawn.** Which connector runs a persona resolves once, everywhere:\nexplicit `--agent` flag > the persona file's `agent:` frontmatter > `COTAL_DEFAULT_AGENT` > the\nsaved [`harness` preference](config.md#preferences) > the product default (Claude). The\nenvironment variable and the preference are *defaults*, never overrides: a persona that pins its\nharness runs on it even when the operator's environment or preferences name another. A pin naming an\nunregistered connector fails the spawn loudly rather than silently falling back (see\n[agent files](agent-files.md)).\n"
|
|
166
|
+
"body": "# Connectors\n\n> **Guide** (informative) · **For:** operators picking a harness · **Prereqs:** none\n\nEvery connector puts a real agent session on the mesh with the same `cotal_*` tools, presence,\nand delivery model ([MCP tools](mcp-tools.md)). They differ in how they bind to their harness\nand which spawn features are wired. Anything unwired **fails loud**: a flag a connector does\nnot support throws; nothing silently degrades.\n\n**Running version.** An MCP server's standard `serverInfo.version` names the Cotal release\nthat server loaded, not the MCP protocol version or a newer CLI installed on disk.\n`cotal_orientation` reports the release loaded by the host answering the tool. Some clients\nhide MCP server metadata; the orientation card remains available through the tool list.\nJcode's stdio bridge and tool host are separate processes, so their versions can differ if\nonly one has reloaded after an upgrade. Updating files alone does not upgrade a running process.\n\nConnectors track raw NATS transport liveness separately from endpoint readiness. A short broker\ndisconnect marks the transport down until nats.js reconnects, without claiming that the connector's\nfull Cotal bind was torn down and rebuilt. A clean connector stop clears both states locally.\nIf a post-connect bind fails, the endpoint closes that partial connection and reports both\ntransport and connection down before retrying.\nThe endpoint `transport` event reports edges and is not replayed to listeners attached later. A\nconnector that needs current state reads its `MeshAgent.transportConnected` value, then listens for\nlater edges.\n`MeshAgent.connectionIssue` records the latest failure before a successful bind. A later bind clears\nit; stopping preserves it so an operator can inspect why the session never connected or last dropped.\n\n| | [Claude Code](connect-claude.md) | [OpenCode](connect-opencode.md) | [Codex](connect-codex.md) | [Hermes](connect-hermes.md) | [Jcode](connect-jcode.md) | [pi](connect-pi.md) |\n|---|---|---|---|---|---|---|\n| Maturity | stable | beta | beta | alpha | beta | alpha |\n| Binds via | installed plugin + MCP server | in-process plugin (native runtime) | host-mode peer driving `codex app-server` | native Python plugin, socket-bridged | host-mode peer driving Jcode Harness API | native pi extension, in-process |\n| Install | `cotal setup` | none, just `opencode` on PATH (1.x or 2.x) | seeded with the CLI; needs an authenticated `codex` on PATH | BYO `uv` + `hermes-agent` `>=0.18,<0.22`; Unix only | seeded with the CLI; needs `jcode` 0.78.1+ on PATH | pi 0.79.10 (one copied file for interactive/SDK) |\n| Watch the real TUI | ✓ | ✓ | ✓ (attached to the mesh-driven thread) | ✗ (headless gateway) | ✓ (attached to the managed Jcode session) | ✓ |\n| Inbound delivery | managed hook drain + idle nudge; personal native inline delivery | injected as a turn | wakes a turn; directed messages steer connector-started turns; external turns defer delivery | fresh agent per message | injected as a Harness API turn; directed messages steer the live session | steered into the live turn |\n| Mid-turn steering | personal native sessions at supported boundaries | ✗ | ✓ (directed messages during connector-started turns) | none | ✓ (directed messages) | ✓ |\n| Session resume (`--resume`) | ✓ (forks) | ✗ ([#154](https://github.com/Cotal-AI/Cotal/issues/154)) | ✗ (a resumed thread has no MCP tools upstream) | ✓ (forks) | ✓ (forks) | ✓ (forks) |\n| Tool-sharing (`--share-tools`) | ✓ (setup shares your servers; narrow per spawn) | ✗ (inherits your servers wholesale) | ✗ (isolated per-agent `CODEX_HOME`) | ✗ | ✗ (private MCP configuration) | ✗ |\n| Models | `--model` | `--model` + catalog (`cotal models`) (1.x) + `--variant` | `--model` + catalog (`cotal models`) + `--variant` (reasoning effort) | any provider, via env | `--model` + `--variant` (reasoning effort) | `--model` |\n| Event plane (default on; `--no-events` opts out) | ✓ | ✓ (1.x); 2.x needs `--no-events` | ✓ | ✗ (requires `--no-events`) | ✓ | ✓ (completed messages) |\n| `cotal_*` tool transport | stdio MCP, no listener | loopback, per-launch Basic secret | loopback MCP, per-host bearer | Unix socket, control token on the first frame | stdio MCP bridge relayed over a Unix socket, per-instance token | in-process, no listener |\n| Containers ([deploy](deploy.md)) | ✓ | ✓ | ✗ | ✗ | ✗ | ✗ |\n\nThe Manager reports the same support fact as `status.connectors[].eventPlane`. Clients use that\ntyped field instead of copying this table. On a space whose policy requires events, a false value\nmeans the connector cannot launch there. Spawn remains the authority and keeps the policy refusal.\n\nThe tool transport row covers only how the `cotal_*` tools reach the mesh endpoint. A managed seat\non every connector also has connector-core's authenticated local control socket, which carries\nlifecycle hooks and stop requests ([authoring a connector](authoring-a-connector.md#local-listeners)).\n\n**Resume provenance.** The manager records the session a `--resume` seat forked on the seat's resume\ndocument, and `cotal ps --wide` and `--json` show it. Hermes and Jcode seats fork after they launch,\nso they also record the source title and a SHA-256 of the transcript they read, which the manager\npicks up once the fork exists. Each of those seats also prints the three facts in its own output\nwhen it forks.\n\n**Native vs. bridged.** OpenCode and pi expose real plugin runtimes, so the connector runs\ninside the host process; pi most directly: peer messages steer the live turn instead of\nwaiting for it to end. Managed Claude Code sessions compose an MCP tool server, lifecycle hooks\nand an idle-wake channel. Personally opened Code sessions use the installed native hooks module\nfor idle and busy-boundary delivery. Complete short messages need no extra inbox call; larger\nmessages retain a preview and the inbox path. The other connectors already inject full message\ncontent through their existing native paths. Native admission or completion accounting remains\nspecific to each host; queue acceptance does not prove the model consumed a message. Presence\nwrites issued by one agent land in the order they were made, and departure is published after\nevery write already in flight; a write admitted after departure began is refused rather than\nreordered behind it. Codex has\nno plugin runtime either and its MCP client cannot wake an idle session, so the connector runs\na host-mode peer over Codex's own app-server protocol (the one the Codex TUI runs on): real\nwake, mid-turn steer, and the `cotal_*` tools served from the host over a loopback MCP endpoint.\nThis also keeps them working on a turn typed into the attached Codex TUI. Hermes runs a\nnative plugin inside its Python gateway, bridged to the connector over a local socket; the\ngateway model starts a fresh agent per inbound message, so there is no live turn to steer. Jcode's\nstable Harness API is a Unix-socket NDJSON bridge: the connector starts one private instance,\ncreates one session, and calls its documented stdio MCP configuration from a private `JCODE_HOME`.\nDirected peer messages that arrive while that session is busy enter Jcode's session-owned\nsoft-interrupt queue.\n\nEach guide covers spawn forms, model selection, and the limits: [Claude\nCode](connect-claude.md) · [OpenCode](connect-opencode.md) · [Codex](connect-codex.md) ·\n[Hermes](connect-hermes.md) · [Jcode](connect-jcode.md) · [pi](connect-pi.md).\n\n**Picking the harness at spawn.** Which connector runs a persona resolves once, everywhere:\nexplicit `--agent` flag > the persona file's `agent:` frontmatter > `COTAL_DEFAULT_AGENT` > the\nsaved [`harness` preference](config.md#preferences) > the product default (Claude). The\nenvironment variable and the preference are *defaults*, never overrides: a persona that pins its\nharness runs on it even when the operator's environment or preferences name another. A pin naming an\nunregistered connector fails the spawn loudly rather than silently falling back (see\n[agent files](agent-files.md)).\n"
|
|
167
167
|
},
|
|
168
168
|
{
|
|
169
169
|
"slug": "control-surface",
|
|
@@ -195,7 +195,7 @@ export function loadDocsBundle() {
|
|
|
195
195
|
"kind": "Concept (informative)",
|
|
196
196
|
"category": "Concept",
|
|
197
197
|
"summary": "Live channel delivery is at-most-once: a message reaches only the peers subscribed at the moment it is published (SPEC §4).",
|
|
198
|
-
"body": "# The delivery daemon (Plane-3)\n\n> **Concept** (informative) · **For:** operators and implementers · **Normative:** [SPEC §4](../SPEC.md#4-delivery-modes), [§7](../SPEC.md#7-channels), [§8](../SPEC.md#8-nats--jetstream-binding)\n\nLive channel delivery is **at-most-once**: a message reaches only the peers subscribed at the\nmoment it is published ([SPEC §4](../SPEC.md#4-delivery-modes)). Agents are busy, mid-turn, or\noffline, so a channel marked **`durable`** needs a per-member backstop that holds each post until\nthat member has actually seen it. The delivery daemon is the server-side component that provides\nit. In the reference implementation this backstop is nicknamed **Plane-3** (the durable plane,\nalongside the live subject fabric and the presence/registry state).\n\nThe backstop defines a **delivery contract** while leaving the storage layout open: [SPEC §8](../SPEC.md#8-nats--jetstream-binding)\nmakes the daemon's store, writer, reader, and registry reference-implementation detail. What is\nnormative is the [§4](../SPEC.md#4-delivery-modes) guarantee it upholds (`durable` is\nat-least-once for current members within retention) and the [§9](../SPEC.md#9-nats--jetstream-security-and-authorization)\nread checks it must apply. A conformant deployment may realize the backstop differently.\n\n## The three pieces\n\n- **Fan-out writer.** On each post to a `durable` channel it copies the message into every\n eligible member's private durable store. For an `@mention` on a *`live`* channel it also writes\n a copy for each mentioned peer authorized to read that channel, which is how a mention reaches\n an authorized peer who isn't currently joined ([SPEC §4](../SPEC.md#4-delivery-modes)). Fan-out\n handles routing; authorization remains with the broker policy. A post with an empty id is copied\n without a duplicate-suppression key, so two distinct id-less posts are both delivered and a\n redelivery of one may surface twice.\n- **Trusted reader.** It pulls each pending entry, re-checks that the member is still allowed to\n read it, and hands the authorized copy to the member's own `dlv_<owner>-<actor>-<uid>` DELIVER\n consumer, which has the same ack semantics. The copy does not ride the member's reply inbox. The\n entry stays pending until the member confirms it was surfaced. A crash between handing off\n and surfacing does not lose the message; the entry redelivers ([SPEC §8](../SPEC.md#8-nats--jetstream-binding)).\n An entry addressed to a retired lifecycle is dropped and removed from the store the first time\n the reader meets it. Retirement leaves a tombstone on that lifecycle's read-ACL row, and a retired\n lifecycle never comes back, so a later reader with a fresh cursor does not pay for it again. The\n reader acks such an entry only after the delete succeeds. A failed delete leaves the entry pending,\n so it is retried and given up after ten redeliveries, and an entry the stream no longer holds counts\n as removed. A daemon that stops serving while the delete is in flight neither acks nor gives up the\n entry, so the daemon that serves next retries it. When the entry came from a durable channel, the\n reader also removes the retired lifecycle's member row for that channel, when one exists: a daemon\n that died between creating a row and its post-write ACL read leaves one, and until it goes every\n later message on the channel is copied into the retired inbox and dropped again. The removal is\n best effort; a failure is a warning, and the next entry retries it. An entry whose owner has no ACL row at all is\n retried, then given up after ten redeliveries, and kept, because a missing row does not prove the\n owner is gone.\n- **Membership registry.** A privileged-written record of who is a durable member of each\n channel, carrying per-member join and leave cursors so a post concurrent with a join or leave\n orders deterministically ([SPEC §7](../SPEC.md#7-channels)). It is broker-known truth, not\n self-reported: an agent cannot assert its own membership.\n\n## Why a *trusted* reader\n\nThe per-member store is **mixed**: it holds copies for whatever channels a member was in when\neach post landed. An agent can leave a channel or lose a grant afterward, so \"this inbox belongs\nto agent A\" is not authorization to hand A everything in it. Agents therefore hold **no\ncontent-bearing read** on the store; the daemon reads it on their behalf and re-authorizes every\n`(instance, channel, message)` entry against the member's **current read ACL** and, for\n`durable`-channel entries, its **membership interval** (the post's sequence sits between the\nmember's join and leave cursors) before releasing content ([SPEC §7](../SPEC.md#7-channels),\n[§8](../SPEC.md#8-nats--jetstream-binding), [§9](../SPEC.md#9-nats--jetstream-security-and-authorization)).\n\nA **leave is a hard read boundary** for the backstop: once a member leaves, its backstop no\nlonger surfaces that channel's content. (Leaving does not revoke the ACL; the peer can still\nre-subscribe live or read ACL-bounded history within `allowSubscribe`.) See\n[identity-and-auth.md](identity-and-auth.md) for how the ACLs are minted and\n[presence-and-delivery.md](presence-and-delivery.md) for the delivery-class model.\n\n## Where it runs\n\n`cotal up` on an **authenticated** mesh starts the delivery daemon alongside the broker and the\nmanager, as its own long-lived infra role. It runs on a **scoped, least-privilege `delivery`\ncredential** co-located with the broker: never an allow-all cred, and it never holds the account\nsigning key. One daemon serves a space (a single-flight lease guards against a second binding the\nsame durables).\n\nOne process can also serve every space on a host: `cotal deliver --spaces <manifest> --server <url>`\nholds one lane per space the manifest names ([server daemons](cli.md#server-daemons)). A lane is\nthat space's daemon. It reads the space's own credential from the root, dials on its own\nconnections, which authenticate into that space's account, and holds its own lease, broker\nwatchdog, timer writer and membership feed, so a second daemon for the space is refused by the lease\nas before. A lane that loses the broker, its credential or its lease closes alone and the host\nreopens it; the other lanes keep serving.\n\nThe manager needs this daemon while it starts. Its SecretStore challenge, its boot repair of a frozen\nregistration gate, and the verified eviction a restart performs all go over the daemon's\n`ctl.delivery-admin` rail. Agents' durable join, leave and membership-list requests go over its\n`ctl.delivery` rail. Both are `ctl` subjects that [SPEC §13.11](../SPEC.md#1311-the-hard-cut)\nretires; the reference implementation still serves them (see\n[the control surface](control-surface.md)). A manager that starts while the daemon is still binding, or while the\ndaemon re-checks who owns its lease, waits up to 60 seconds for the rail to answer. Only a request\nthat times out or finds no responder is retried. Retries come closer together as the wait runs out,\nso a daemon that binds in its last seconds is still asked. The wait ends on time even while a retry\nis still connecting, and nothing is sent after it. A daemon that answers fails the start at once if\nit refuses or its reply cannot be read. One that stays silent for the whole wait fails it, and the\nmanager log names the rail.\n\nThe daemon answers `ctl.delivery-admin` requests one at a time, in the order they arrive, with one\nexception: the `lifecycleMemberships` inventory a retirement reads before it deletes the retired\nagent's membership rows. That request is answered without waiting for the others, so a manager stop\nthat retires many seats does not queue each inventory behind the other seats' evictions. Inventories\nthat arrive together share one read of the members bucket, and each one's read begins after it\narrived. Before the manager asks for a lifecycle's inventory, it narrows that lifecycle's read-ACL\nrow to no reads. A durable join reads that row again just before it writes its membership row, and\nonce more after. When the channel is no longer allowed, the join writes nothing, or removes the row it\njust wrote, and is refused. A leave or an activation only updates a row that still exists. A row of the\nretiring lifecycle is then either in the inventory or gone, whichever daemon process wrote it. The\ndaemon also fences on its own, for a manager that does not narrow the row: when the inventory request\narrives with the lifecycle's ACL row still allowing reads, it refuses every durable join and leave of\nthat lifecycle from that moment, on that daemon process. A request whose row is already narrowed, or\nretired, leaves no such mark, since the row refuses those writes by itself. Either way the read starts\nonly after the writes already running have finished.\n\nA reply on the `ctl.delivery` or `ctl.delivery-admin` rail that is larger than the broker's\n`max_payload` cannot be published. The daemon answers that request with a refusal giving the reply's\nsize in bytes, so the caller fails at once and does not wait out its timeout.\n\nA restart verify-evicts every holder in the manager's credential family, and the family keeps a\nledger row for every credential an earlier incarnation was issued. The manager keeps its serve,\ngoal-writer and session-ledger identities across restarts, so restarts add no holders; each attach\nsession adds one serving holder. The manager sends those holders\nas one `evictPrincipals` request per 256, and the daemon answers each request with one shared sweep\nof the broker. The manager records the holders each request verified before it sends the next, so a\nrestart cut short by its executor window resumes after the last recorded request. A daemon that does\nnot serve that verb refuses it, and the restart leaves the gate frozen.\n\nAn agent binds its per-member delivery durable even when the plane reached by its connection has no\nready delivery lease, so a daemon that starts later can deliver through it. A missing or not-ready\nlease emits a warning that names the durable, space, and condition. It tells the agent to reconnect\nagainst another plane if that plane serves the space, which re-binds the durable there.\n\nBefore it constructs its endpoint or claims that lease, the daemon reads the account-scoped `$SYS`\nobserver from the same source it will use for scans, whether that source is the workstation store or\nan injected hosted store. It refuses if the observer belongs to another account, is missing, or is\npart of a present but torn observer/evictor rotation. An absent evictor keeps the documented\npre-eviction, deny-new-only posture; eviction itself remains unavailable until it is provisioned.\n\nIt inherits the mesh's transport on **every** launch, including the relaunch a bare `cotal up`\nperforms when the daemon is missing. A TLS-required mesh always starts it with TLS demanded, so it\nrefuses a plaintext listener rather than upgrading on the server's unauthenticated greeting. It\nholds a standing credential and reconnects unattended, so a downgrade here would repeat with nobody\nwatching. See [transport.md](transport.md).\n\nAfter a reachability check at start-up, the daemon watches the broker only through its resident\nconnection's events. It opens no other connection to check the broker. A disconnect starts a clock,\nand a reconnect stops it. When the time since the disconnect, less any time the daemon's own\nevent loop was stalled, reaches the window (`COTAL_DELIVERY_BROKER_GONE_MS`, 15 seconds by\ndefault), the daemon logs\n`✗ delivery: broker connection unavailable (broker unreachable), exiting (coupled to the broker)`\nand exits. Wall time since the disconnect also has a backstop\n(`COTAL_DELIVERY_BROKER_GONE_BACKSTOP_MS`, four times the window by default and never less than it).\nReaching it logs\n`✗ delivery: broker connection unavailable past backstop (broker unreachable), exiting (coupled to the broker)`\nand exits, however long the daemon was stalled. A broker that stops answering without closing the\nsocket counts as disconnected only once the client's pings go unanswered, so the clock starts a few\nseconds after the broker stops.\n\nAn authentication-expiry error is not a broker disconnect. The daemon logs\n`! delivery: credential expired, awaiting proved renewal` at once and waits for a renewal it has\nproved against the broker; a reconnect alone does not clear it. If no such renewal arrives by the\nbackstop, it logs `✗ delivery: credential expired without renewal` and exits.\n\nThe daemon refuses a `reloadCreds` adoption until it has finished starting, which is after its lease\nwatch is bound. Its lease turns ready earlier than that, so a renewal owner can ask before start-up\nis done. The refusal says the daemon has not finished starting and adopts nothing. The next renewal\npass or the daemon's own 75% re-read adopts the re-signed credentials.\n\nAfter an adoption the daemon reconnects with the new credentials 250ms after its reply. A\ndelivery-admin request it reads in the meantime is answered once that reconnect completes, or\nafter 5s. A reply sent while the connection is down would be lost, and its caller, such as a\nmanager evicting its predecessor right after its boot renewal, would wait out its whole 15s request\ntimeout.\n\n`cotal up` reports the daemon **only when it is actually serving**. A daemon it started can exit\nwithout taking the single-flight lease because another daemon holds it, or because a crashed\nholder's lease has not expired yet. `up` then says so and exits non-zero instead of printing a\nhealthy control plane over a daemon that is not there. A lease write the credential is not allowed to make is reported\nas a denial naming the refused subject and operation, never as another daemon holding the lease.\nA lease write the broker refuses for another reason, such as the insufficient-resources answer of a\nstore over its `--max-file-store` cap, is quoted as the broker gave it. A running daemon whose lease\nkey expired creates it again. Only a create refused because a live lease exists makes it say that\nanother daemon has taken the shard. Any other refusal is quoted, with the line saying it could not\nre-acquire the lease, and the daemon exits all the same, because it serves only under its lease.\nThe daemon writes its own reason to `.cotal/delivery.<key>.log`, the log\nfor the space it serves ([Config](config.md#project-files)). That path is project-local. Detached\n`up` redirects the daemon's stdout and stderr onto the file, so wrapping the launcher in a\nsystemd unit does not put those lines in that unit's journal. A daemon stopped by SIGTERM or\nSIGINT, which is what `cotal down`, a service stop and Ctrl-C send, writes `received <signal>,\nexiting` to that log before it releases its lease. A signal that arrives while the daemon is\nstill claiming the lease waits for the broker's answer, and a claim that won is then released the\nsame way. A signal that arrives while the daemon's connection redials, as it does when the daemon\nmoves onto a renewed credential, waits up to five seconds from the drop for the redial before the\nrelease, because a request sent while the connection is down is never answered. A SIGKILL,\nincluding one from the kernel OOM killer, ends the daemon with no line.\n\nA foreground `cotal up` restarts a daemon it started when that daemon dies while the broker that\n`up` started is still running. It logs\n`delivery daemon exited (<cause>) while nats-server is running - restarting it`, then\n`delivery daemon running again` once the replacement's responder is bound. A replacement whose\nresponder does not bind gets the same not-bound warning as at startup instead. The daemon ends\nitself when it cannot reach the broker, and a starved host can make a running broker look\nunreachable. Without the restart, every retirement that needs the daemon would fail until someone\nran `cotal up` again. A failed restart is logged and retried after the 30-second lease TTL. A daemon\nthat exits cleanly or on SIGTERM or SIGINT stays stopped. So does one that bare `cotal down`\nstops, also when the daemon is too starved to exit on SIGTERM and `down` kills it, when it is a\nreplacement that is still starting, and when the stop lands between two restart attempts. A legacy\nstack has no command that stops only the daemon. Detached\n`up` exits after launching and restarts nothing; a bare `cotal up` relaunches a missing daemon there.\n\nCtrl-C on a foreground `up`, and a broker that exits under it, stop the daemon with the same stop\nbare `cotal down` uses for it. It holds the reservation `down` takes, so the delivery stop of a\nconcurrent `cotal down` is refused while it runs. It sends SIGKILL to a daemon that has not exited 15\nseconds after SIGTERM, and removes the daemon's credential only once its death is confirmed. A\nrecord whose pid now belongs to another program is cleared without a signal. If the broker exits\nwhile that stop is running, `up` waits for the stop to finish before it exits.\n\nThe daemon **records itself** in `.cotal/delivery.<key>.pid`, whichever way it was started, and\nremoves that record when it exits cleanly. A lane of `cotal deliver --spaces` is the exception: it\nwrites no record, because the record is what `cotal down` signals for one space and the host serves\nseveral. The launcher is not the only route to a running daemon: a\ncontainer entrypoint, a systemd unit, or `cotal deliver --space <space>` typed by hand all reach one\ntoo, and a record written only by the launcher goes stale the moment any of those restarts it.\n`cotal deliver` is a deprecated entry kept for existing units and scripts; new setups use the\n`delivery` service preset ([deprecated daemon entries](UPGRADING.md#deprecated-daemon-entries)). Typed\nby hand on the workstation, the daemon dials the broker recorded for the space in the mesh registry\n(a mismatching `--server` is refused before any dial); with no record for the space it uses the\nlocal mesh default, and a daemon with an injected store never consults the registry at all. The\nwrite happens once the daemon holds the single-flight lease, because that is the point at which it is\nthe space's daemon: one that loses the lease refuses to bind and exits, and must not overwrite the\nlive holder's record on its way out.\n\nThe daemon serves one workspace root, chosen at start: the one `cotal deliver --root <dir>` names,\nor the nearest `.cotal/` above its working directory. A workstation daemon with neither refuses at\nstart and names the directory it searched from, before it reads a credential or dials a broker,\nbecause a directory nobody set up holds none of its credentials. A daemon with an injected store\ntakes its credentials from that store and needs no `.cotal/`.\n\nReaders verify the record before believing it. A recorded pid is trusted only when the process behind\nit is alive **and** its command line names a delivery daemon, so a record that outlived its process\nand had its number reused is reported as stale rather than as a healthy daemon. `cotal down` never\nsignals such a process. Where a command line cannot be read, the record is trusted as before: the\ncheck only ever downgrades on proof.\n\nThe daemon also hosts the space's **checkpoint timer writer** ([SPEC §13.9](../SPEC.md#139-authority-boundary)):\nthe standing pump that turns workflow `.schedule` requests into armed broker schedules, on its own\nconnection under the same delivery credential. That connection presents the credential the daemon\nholds now and reconnects onto each renewed one the daemon adopts, so the broker never closes it for\nan expired credential and it never dials with one. Without a running writer no workflow pause on the\nspace ever expires. The writer restarts itself with backoff and logs while it is down; a fault\nthere never takes delivery down. Stopping the daemon ends the writer's pending fetch at once and\nwakes a retry backoff it is sleeping through, so a close never waits for a retry it will not make.\n\n**Open dev mode has no delivery daemon.** Open mode is deliberately **live-only**: there is no\ntrusted reader, so there is no durable backstop. Run an auth mesh if you need durable channels.\n\n## Without it\n\nThe self-serve **live** path never depends on the daemon: join is a broker-enforced subscribe\nunder `sub.allow`, so a `durable` channel still delivers live with no daemon present ([SPEC §7](../SPEC.md#7-channels)).\nOnly the durable backstop and its membership writes need the privileged host. If a peer joins a\n`durable` channel while the backstop can't be established, it is **joined live with the durable\nbackstop unestablished**: the live subscription is active, and the shortfall is surfaced as an\nexceptional delivery state, never reported as `joined durable` and never silently dropped ([SPEC §7](../SPEC.md#7-channels)).\n"
|
|
198
|
+
"body": "# The delivery daemon (Plane-3)\n\n> **Concept** (informative) · **For:** operators and implementers · **Normative:** [SPEC §4](../SPEC.md#4-delivery-modes), [§7](../SPEC.md#7-channels), [§8](../SPEC.md#8-nats--jetstream-binding)\n\nLive channel delivery is **at-most-once**: a message reaches only the peers subscribed at the\nmoment it is published ([SPEC §4](../SPEC.md#4-delivery-modes)). Agents are busy, mid-turn, or\noffline, so a channel marked **`durable`** needs a per-member backstop that holds each post until\nthat member has actually seen it. The delivery daemon is the server-side component that provides\nit. In the reference implementation this backstop is nicknamed **Plane-3** (the durable plane,\nalongside the live subject fabric and the presence/registry state).\n\nThe backstop defines a **delivery contract** while leaving the storage layout open: [SPEC §8](../SPEC.md#8-nats--jetstream-binding)\nmakes the daemon's store, writer, reader, and registry reference-implementation detail. What is\nnormative is the [§4](../SPEC.md#4-delivery-modes) guarantee it upholds (`durable` is\nat-least-once for current members within retention) and the [§9](../SPEC.md#9-nats--jetstream-security-and-authorization)\nread checks it must apply. A conformant deployment may realize the backstop differently.\n\n## The three pieces\n\n- **Fan-out writer.** On each post to a `durable` channel it copies the message into every\n eligible member's private durable store. For an `@mention` on a *`live`* channel it also writes\n a copy for each mentioned peer authorized to read that channel, which is how a mention reaches\n an authorized peer who isn't currently joined ([SPEC §4](../SPEC.md#4-delivery-modes)). Fan-out\n handles routing; authorization remains with the broker policy. A post with an empty id is copied\n without a duplicate-suppression key, so two distinct id-less posts are both delivered and a\n redelivery of one may surface twice.\n- **Trusted reader.** It pulls each pending entry, re-checks that the member is still allowed to\n read it, and hands the authorized copy to the member's own `dlv_<owner>-<actor>-<uid>` DELIVER\n consumer, which has the same ack semantics. The copy does not ride the member's reply inbox. The\n entry stays pending until the member confirms it was surfaced. A crash between handing off\n and surfacing does not lose the message; the entry redelivers ([SPEC §8](../SPEC.md#8-nats--jetstream-binding)).\n An entry addressed to a retired lifecycle is dropped and removed from the store the first time\n the reader meets it. Retirement leaves a tombstone on that lifecycle's read-ACL row, and a retired\n lifecycle never comes back, so a later reader with a fresh cursor does not pay for it again. The\n reader acks such an entry only after the delete succeeds. A failed delete leaves the entry pending,\n so it is retried and given up after ten redeliveries, and an entry the stream no longer holds counts\n as removed. A daemon that stops serving while the delete is in flight neither acks nor gives up the\n entry, so the daemon that serves next retries it. When the entry came from a durable channel, the\n reader also removes the retired lifecycle's member row for that channel, when one exists: a daemon\n that died between creating a row and its post-write ACL read leaves one, and until it goes every\n later message on the channel is copied into the retired inbox and dropped again. The removal is\n best effort; a failure is a warning, and the next entry retries it. An entry whose owner has no ACL row at all is\n retried, then given up after ten redeliveries, and kept, because a missing row does not prove the\n owner is gone.\n- **Membership registry.** A privileged-written record of who is a durable member of each\n channel, carrying per-member join and leave cursors so a post concurrent with a join or leave\n orders deterministically ([SPEC §7](../SPEC.md#7-channels)). It is broker-known truth, not\n self-reported: an agent cannot assert its own membership.\n\n## Why a *trusted* reader\n\nThe per-member store is **mixed**: it holds copies for whatever channels a member was in when\neach post landed. An agent can leave a channel or lose a grant afterward, so \"this inbox belongs\nto agent A\" is not authorization to hand A everything in it. Agents therefore hold **no\ncontent-bearing read** on the store; the daemon reads it on their behalf and re-authorizes every\n`(instance, channel, message)` entry against the member's **current read ACL** and, for\n`durable`-channel entries, its **membership interval** (the post's sequence sits between the\nmember's join and leave cursors) before releasing content ([SPEC §7](../SPEC.md#7-channels),\n[§8](../SPEC.md#8-nats--jetstream-binding), [§9](../SPEC.md#9-nats--jetstream-security-and-authorization)).\n\nA **leave is a hard read boundary** for the backstop: once a member leaves, its backstop no\nlonger surfaces that channel's content. (Leaving does not revoke the ACL; the peer can still\nre-subscribe live or read ACL-bounded history within `allowSubscribe`.) See\n[identity-and-auth.md](identity-and-auth.md) for how the ACLs are minted and\n[presence-and-delivery.md](presence-and-delivery.md) for the delivery-class model.\n\n## Where it runs\n\n`cotal up` on an **authenticated** mesh starts the delivery daemon alongside the broker and the\nmanager, as its own long-lived infra role. It runs on a **scoped, least-privilege `delivery`\ncredential** co-located with the broker: never an allow-all cred, and it never holds the account\nsigning key. One daemon serves a space (a single-flight lease guards against a second binding the\nsame durables).\n\nOne process can also serve every space on a host: `cotal deliver --spaces <manifest> --server <url>`\nholds one lane per space the manifest names ([server daemons](cli.md#server-daemons)). A lane is\nthat space's daemon. It reads the space's own credential from the root, dials on its own\nconnections, which authenticate into that space's account, and holds its own lease, broker\nwatchdog, timer writer and membership feed, so a second daemon for the space is refused by the lease\nas before. A lane that loses the broker, its credential or its lease closes alone and the host\nreopens it; the other lanes keep serving.\n\nThe manager needs this daemon while it starts. Its SecretStore challenge, its boot repair of a frozen\nregistration gate, and the verified eviction a restart performs all go over the daemon's\n`ctl.delivery-admin` rail. Agents' durable join, leave and membership-list requests go over its\n`ctl.delivery` rail. Both are `ctl` subjects that [SPEC §13.11](../SPEC.md#1311-the-hard-cut)\nretires; the reference implementation still serves them (see\n[the control surface](control-surface.md)). A manager that starts while the daemon is still binding, or while the\ndaemon re-checks who owns its lease, waits up to 60 seconds for the rail to answer. Only a request\nthat times out or finds no responder is retried. The first retry runs at once. Later retries are at\nmost one second apart, shortened as the wait runs out, so a daemon that binds in its last seconds is\nstill asked. The wait ends on time even while a retry is still connecting, and nothing is sent after\nit. A daemon that answers fails the start at once if it refuses or its reply cannot be read. One\nthat stays silent for the whole wait fails it, and the manager log names the rail.\n\nA manager retiring a static agent uses the same retry cadence for an unanswered verified-eviction\nrequest, within a 15-second total wait. A credential reload briefly removes the daemon's responder\nwhile it reconnects; that gap must not abandon an otherwise healthy retirement. A refusal or an\nunusable eviction reply still fails at once. The lifecycle stays held until eviction is verified\nand cleanup completes.\n\nThe daemon answers `ctl.delivery-admin` requests one at a time, in the order they arrive, with one\nexception: the `lifecycleMemberships` inventory a retirement reads before it deletes the retired\nagent's membership rows. That request is answered without waiting for the others, so a manager stop\nthat retires many seats does not queue each inventory behind the other seats' evictions. Inventories\nthat arrive together share one read of the members bucket, and each one's read begins after it\narrived. Before the manager asks for a lifecycle's inventory, it narrows that lifecycle's read-ACL\nrow to no reads. A durable join reads that row again just before it writes its membership row, and\nonce more after. When the channel is no longer allowed, the join writes nothing, or removes the row it\njust wrote, and is refused. A leave or an activation only updates a row that still exists. A row of the\nretiring lifecycle is then either in the inventory or gone, whichever daemon process wrote it. The\ndaemon also fences on its own, for a manager that does not narrow the row: when the inventory request\narrives with the lifecycle's ACL row still allowing reads, it refuses every durable join and leave of\nthat lifecycle from that moment, on that daemon process. A request whose row is already narrowed, or\nretired, leaves no such mark, since the row refuses those writes by itself. Either way the read starts\nonly after the writes already running have finished.\n\nA reply on the `ctl.delivery` or `ctl.delivery-admin` rail that is larger than the broker's\n`max_payload` cannot be published. The daemon answers that request with a refusal giving the reply's\nsize in bytes, so the caller fails at once and does not wait out its timeout.\n\nA restart verify-evicts every holder in the manager's credential family, and the family keeps a\nledger row for every credential an earlier incarnation was issued. The manager keeps its serve,\ngoal-writer and session-ledger identities across restarts, so restarts add no holders; each attach\nsession adds one serving holder. The manager sends those holders\nas one `evictPrincipals` request per 256, and the daemon answers each request with one shared sweep\nof the broker. The manager records the holders each request verified before it sends the next, so a\nrestart cut short by its executor window resumes after the last recorded request. A daemon that does\nnot serve that verb refuses it, and the restart leaves the gate frozen.\n\nAn agent binds its per-member delivery durable even when the plane reached by its connection has no\nready delivery lease, so a daemon that starts later can deliver through it. A missing or not-ready\nlease emits a warning that names the durable, space, and condition. It tells the agent to reconnect\nagainst another plane if that plane serves the space, which re-binds the durable there.\n\nBefore it constructs its endpoint or claims that lease, the daemon reads the account-scoped `$SYS`\nobserver from the same source it will use for scans, whether that source is the workstation store or\nan injected hosted store. It refuses if the observer belongs to another account, is missing, or is\npart of a present but torn observer/evictor rotation. An absent evictor keeps the documented\npre-eviction, deny-new-only posture; eviction itself remains unavailable until it is provisioned.\n\nIt inherits the mesh's transport on **every** launch, including the relaunch a bare `cotal up`\nperforms when the daemon is missing. A TLS-required mesh always starts it with TLS demanded, so it\nrefuses a plaintext listener rather than upgrading on the server's unauthenticated greeting. It\nholds a standing credential and reconnects unattended, so a downgrade here would repeat with nobody\nwatching. See [transport.md](transport.md).\n\nAfter a reachability check at start-up, the daemon watches the broker only through its resident\nconnection's events. It opens no other connection to check the broker. A disconnect starts a clock,\nand a reconnect stops it. When the time since the disconnect, less any time the daemon's own\nevent loop was stalled, reaches the window (`COTAL_DELIVERY_BROKER_GONE_MS`, 15 seconds by\ndefault), the daemon logs\n`✗ delivery: broker connection unavailable (broker unreachable), exiting (coupled to the broker)`\nand exits. Wall time since the disconnect also has a backstop\n(`COTAL_DELIVERY_BROKER_GONE_BACKSTOP_MS`, four times the window by default and never less than it).\nReaching it logs\n`✗ delivery: broker connection unavailable past backstop (broker unreachable), exiting (coupled to the broker)`\nand exits, however long the daemon was stalled. A broker that stops answering without closing the\nsocket counts as disconnected only once the client's pings go unanswered, so the clock starts a few\nseconds after the broker stops.\n\nAn authentication-expiry error is not a broker disconnect. The daemon logs\n`! delivery: credential expired, awaiting proved renewal` at once and waits for a renewal it has\nproved against the broker; a reconnect alone does not clear it. If no such renewal arrives by the\nbackstop, it logs `✗ delivery: credential expired without renewal` and exits.\n\nThe daemon refuses a `reloadCreds` adoption until it has finished starting, which is after its lease\nwatch is bound. Its lease turns ready earlier than that, so a renewal owner can ask before start-up\nis done. The refusal says the daemon has not finished starting and adopts nothing. The next renewal\npass or the daemon's own 75% re-read adopts the re-signed credentials.\n\nAfter an adoption the daemon reconnects with the new credentials 250ms after its reply. A\ndelivery-admin request it reads in the meantime is answered once that reconnect completes, or\nafter 5s. A reply sent while the connection is down would be lost, and its caller, such as a\nmanager evicting its predecessor right after its boot renewal, would wait out its whole 15s request\ntimeout.\n\n`cotal up` reports the daemon **only when it is actually serving**. A daemon it started can exit\nwithout taking the single-flight lease because another daemon holds it, or because a crashed\nholder's lease has not expired yet. `up` then says so and exits non-zero instead of printing a\nhealthy control plane over a daemon that is not there. A lease write the credential is not allowed to make is reported\nas a denial naming the refused subject and operation, never as another daemon holding the lease.\nA lease write the broker refuses for another reason, such as the insufficient-resources answer of a\nstore over its `--max-file-store` cap, is quoted as the broker gave it. A running daemon whose lease\nkey expired creates it again. Only a create refused because a live lease exists makes it say that\nanother daemon has taken the shard. Any other refusal is quoted, with the line saying it could not\nre-acquire the lease, and the daemon exits all the same, because it serves only under its lease.\nThe daemon writes its own reason to `.cotal/delivery.<key>.log`, the log\nfor the space it serves ([Config](config.md#project-files)). That path is project-local. Detached\n`up` redirects the daemon's stdout and stderr onto the file, so wrapping the launcher in a\nsystemd unit does not put those lines in that unit's journal. A daemon stopped by SIGTERM or\nSIGINT, which is what `cotal down`, a service stop and Ctrl-C send, writes `received <signal>,\nexiting` to that log before it releases its lease. A signal that arrives while the daemon is\nstill claiming the lease waits for the broker's answer, and a claim that won is then released the\nsame way. A signal that arrives while the daemon's connection redials, as it does when the daemon\nmoves onto a renewed credential, waits up to five seconds from the drop for the redial before the\nrelease, because a request sent while the connection is down is never answered. A SIGKILL,\nincluding one from the kernel OOM killer, ends the daemon with no line.\n\nA foreground `cotal up` restarts a daemon it started when that daemon dies while the broker that\n`up` started is still running. It logs\n`delivery daemon exited (<cause>) while nats-server is running - restarting it`, then\n`delivery daemon running again` once the replacement's responder is bound. A replacement whose\nresponder does not bind gets the same not-bound warning as at startup instead. The daemon ends\nitself when it cannot reach the broker, and a starved host can make a running broker look\nunreachable. Without the restart, every retirement that needs the daemon would fail until someone\nran `cotal up` again. A failed restart is logged and retried after the 30-second lease TTL. A daemon\nthat exits cleanly or on SIGTERM or SIGINT stays stopped. So does one that bare `cotal down`\nstops, also when the daemon is too starved to exit on SIGTERM and `down` kills it, when it is a\nreplacement that is still starting, and when the stop lands between two restart attempts. A legacy\nstack has no command that stops only the daemon. Detached\n`up` exits after launching and restarts nothing; a bare `cotal up` relaunches a missing daemon there.\n\nCtrl-C on a foreground `up`, and a broker that exits under it, stop the daemon with the same stop\nbare `cotal down` uses for it. It holds the reservation `down` takes, so the delivery stop of a\nconcurrent `cotal down` is refused while it runs. It sends SIGKILL to a daemon that has not exited 15\nseconds after SIGTERM, and removes the daemon's credential only once its death is confirmed. A\nrecord whose pid now belongs to another program is cleared without a signal. If the broker exits\nwhile that stop is running, `up` waits for the stop to finish before it exits.\n\nThe daemon **records itself** in `.cotal/delivery.<key>.pid`, whichever way it was started, and\nremoves that record when it exits cleanly. A lane of `cotal deliver --spaces` is the exception: it\nwrites no record, because the record is what `cotal down` signals for one space and the host serves\nseveral. The launcher is not the only route to a running daemon: a\ncontainer entrypoint, a systemd unit, or `cotal deliver --space <space>` typed by hand all reach one\ntoo, and a record written only by the launcher goes stale the moment any of those restarts it.\n`cotal deliver` is a deprecated entry kept for existing units and scripts; new setups use the\n`delivery` service preset ([deprecated daemon entries](UPGRADING.md#deprecated-daemon-entries)). Typed\nby hand on the workstation, the daemon dials the broker recorded for the space in the mesh registry\n(a mismatching `--server` is refused before any dial); with no record for the space it uses the\nlocal mesh default, and a daemon with an injected store never consults the registry at all. The\nwrite happens once the daemon holds the single-flight lease, because that is the point at which it is\nthe space's daemon: one that loses the lease refuses to bind and exits, and must not overwrite the\nlive holder's record on its way out.\n\nThe daemon serves one workspace root, chosen at start: the one `cotal deliver --root <dir>` names,\nor the nearest `.cotal/` above its working directory. A workstation daemon with neither refuses at\nstart and names the directory it searched from, before it reads a credential or dials a broker,\nbecause a directory nobody set up holds none of its credentials. A daemon with an injected store\ntakes its credentials from that store and needs no `.cotal/`.\n\nReaders verify the record before believing it. A recorded pid is trusted only when the process behind\nit is alive **and** its command line names a delivery daemon, so a record that outlived its process\nand had its number reused is reported as stale rather than as a healthy daemon. `cotal down` never\nsignals such a process. Where a command line cannot be read, the record is trusted as before: the\ncheck only ever downgrades on proof.\n\nThe daemon also hosts the space's **checkpoint timer writer** ([SPEC §13.9](../SPEC.md#139-authority-boundary)):\nthe standing pump that turns workflow `.schedule` requests into armed broker schedules, on its own\nconnection under the same delivery credential. That connection presents the credential the daemon\nholds now and reconnects onto each renewed one the daemon adopts, so the broker never closes it for\nan expired credential and it never dials with one. Without a running writer no workflow pause on the\nspace ever expires. The writer restarts itself with backoff and logs while it is down; a fault\nthere never takes delivery down. Stopping the daemon ends the writer's pending fetch at once and\nwakes a retry backoff it is sleeping through, so a close never waits for a retry it will not make.\n\n**Open dev mode has no delivery daemon.** Open mode is deliberately **live-only**: there is no\ntrusted reader, so there is no durable backstop. Run an auth mesh if you need durable channels.\n\n## Without it\n\nThe self-serve **live** path never depends on the daemon: join is a broker-enforced subscribe\nunder `sub.allow`, so a `durable` channel still delivers live with no daemon present ([SPEC §7](../SPEC.md#7-channels)).\nOnly the durable backstop and its membership writes need the privileged host. If a peer joins a\n`durable` channel while the backstop can't be established, it is **joined live with the durable\nbackstop unestablished**: the live subscription is active, and the shortfall is surfaced as an\nexceptional delivery state, never reported as `joined durable` and never silently dropped ([SPEC §7](../SPEC.md#7-channels)).\n"
|
|
199
199
|
},
|
|
200
200
|
{
|
|
201
201
|
"slug": "deploy",
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"docs-bundle.generated.js","sourceRoot":"","sources":["../src/docs-bundle.generated.ts"],"names":[],"mappings":"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
|
|
1
|
+
{"version":3,"file":"docs-bundle.generated.js","sourceRoot":"","sources":["../src/docs-bundle.generated.ts"],"names":[],"mappings":"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"}
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@cotal-ai/connector-core",
|
|
3
3
|
"description": "Shared MCP-bridge runtime for Cotal connectors: the mesh agent, cotal_* tools, and hook relay.",
|
|
4
|
-
"version": "0.128.
|
|
4
|
+
"version": "0.128.7",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"repository": {
|
|
7
7
|
"type": "git",
|
|
@@ -41,11 +41,11 @@
|
|
|
41
41
|
"@cotal-ai/core": ">=0.1.0"
|
|
42
42
|
},
|
|
43
43
|
"devDependencies": {
|
|
44
|
-
"@cotal-ai/auth": "0.128.
|
|
44
|
+
"@cotal-ai/auth": "0.128.7",
|
|
45
45
|
"jose": "^6.2.3",
|
|
46
46
|
"@cotal-ai/smoke-kit": "0.0.0",
|
|
47
47
|
"@ag-ui/core": "0.0.57",
|
|
48
|
-
"@cotal-ai/core": "0.128.
|
|
48
|
+
"@cotal-ai/core": "0.128.7",
|
|
49
49
|
"@nats-io/jetstream": "^3.4.0",
|
|
50
50
|
"@nats-io/transport-node": "^3.4.0"
|
|
51
51
|
},
|