@cogitator-ai/bridge 0.2.0 → 0.3.0

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.
Files changed (74) hide show
  1. package/README.md +156 -8
  2. package/dist/adapter.d.ts +123 -0
  3. package/dist/adapter.d.ts.map +1 -0
  4. package/dist/adapter.js +2 -0
  5. package/dist/adapter.js.map +1 -0
  6. package/dist/adapters/claude.d.ts +90 -0
  7. package/dist/adapters/claude.d.ts.map +1 -0
  8. package/dist/adapters/claude.js +359 -0
  9. package/dist/adapters/claude.js.map +1 -0
  10. package/dist/adapters/codex.d.ts +58 -0
  11. package/dist/adapters/codex.d.ts.map +1 -0
  12. package/dist/adapters/codex.js +330 -0
  13. package/dist/adapters/codex.js.map +1 -0
  14. package/dist/adapters/exec.d.ts +57 -0
  15. package/dist/adapters/exec.d.ts.map +1 -0
  16. package/dist/adapters/exec.js +149 -0
  17. package/dist/adapters/exec.js.map +1 -0
  18. package/dist/adapters/hosted.d.ts +168 -0
  19. package/dist/adapters/hosted.d.ts.map +1 -0
  20. package/dist/adapters/hosted.js +361 -0
  21. package/dist/adapters/hosted.js.map +1 -0
  22. package/dist/client.d.ts +9 -2
  23. package/dist/client.d.ts.map +1 -1
  24. package/dist/client.js +17 -3
  25. package/dist/client.js.map +1 -1
  26. package/dist/dispatcher.d.ts +67 -17
  27. package/dist/dispatcher.d.ts.map +1 -1
  28. package/dist/dispatcher.js +240 -17
  29. package/dist/dispatcher.js.map +1 -1
  30. package/dist/host.d.ts +1 -1
  31. package/dist/host.d.ts.map +1 -1
  32. package/dist/index.d.ts +13 -2
  33. package/dist/index.d.ts.map +1 -1
  34. package/dist/index.js +6 -0
  35. package/dist/index.js.map +1 -1
  36. package/dist/inputs.d.ts +40 -1
  37. package/dist/inputs.d.ts.map +1 -1
  38. package/dist/inputs.js +25 -2
  39. package/dist/inputs.js.map +1 -1
  40. package/dist/paths.d.ts +6 -0
  41. package/dist/paths.d.ts.map +1 -1
  42. package/dist/paths.js +19 -0
  43. package/dist/paths.js.map +1 -1
  44. package/dist/protocol.d.ts +5 -0
  45. package/dist/protocol.d.ts.map +1 -1
  46. package/dist/protocol.js +5 -0
  47. package/dist/protocol.js.map +1 -1
  48. package/dist/server.d.ts.map +1 -1
  49. package/dist/server.js +6 -1
  50. package/dist/server.js.map +1 -1
  51. package/dist/testing/conformance.d.ts +65 -0
  52. package/dist/testing/conformance.d.ts.map +1 -0
  53. package/dist/testing/conformance.js +217 -0
  54. package/dist/testing/conformance.js.map +1 -0
  55. package/dist/testing/fake-harnesses.d.ts +101 -0
  56. package/dist/testing/fake-harnesses.d.ts.map +1 -0
  57. package/dist/testing/fake-harnesses.js +291 -0
  58. package/dist/testing/fake-harnesses.js.map +1 -0
  59. package/dist/testing/index.d.ts +5 -0
  60. package/dist/testing/index.d.ts.map +1 -0
  61. package/dist/testing/index.js +3 -0
  62. package/dist/testing/index.js.map +1 -0
  63. package/dist/types.d.ts +3 -39
  64. package/dist/types.d.ts.map +1 -1
  65. package/dist/types.js +2 -0
  66. package/dist/types.js.map +1 -1
  67. package/dist/waiter.d.ts +36 -0
  68. package/dist/waiter.d.ts.map +1 -0
  69. package/dist/waiter.js +92 -0
  70. package/dist/waiter.js.map +1 -0
  71. package/fakes/claude.mjs +450 -0
  72. package/fakes/codex.mjs +391 -0
  73. package/fakes/lib.mjs +507 -0
  74. package/package.json +7 -1
package/README.md CHANGED
@@ -6,7 +6,7 @@ The agent bridge: Claude Code, Codex and other agents hand each other jobs, ask
6
6
 
7
7
  Nobody waits. An agent hands a job over, gets its number at once and ends its turn. Whatever comes later, a question or the result, arrives as a letter. The bridge in the middle is a dispatcher, not a model: it keeps jobs and letters, finds who a letter is for, applies the limits and writes everything down. It never calls a model.
8
8
 
9
- This release has the core: the dispatcher, its store, the socket it serves and the commands to run and watch it. A session takes part by reading its inbox through `BridgeClient`. Adapters that wake a session of a harness in its own window, and the MCP tools agents call, build on this core.
9
+ The bridge reaches a session where it lives. A Claude Code session wakes for its mail through a hook of its own, a Codex thread through its message queue, and an agent the bridge hosts itself (any model of the Cogitator runtime, any agent of the Agent Client Protocol) gets a letter as its next turn. A harness without an adapter still takes part: its sessions read their inbox. The MCP tools agents call are the next step, until then a session calls the bridge with `cogitator bridge` from its shell.
10
10
 
11
11
  ```bash
12
12
  pnpm add @cogitator-ai/bridge better-sqlite3
@@ -21,10 +21,60 @@ cogitator bridge serve # in the foreground, until Ctrl+C
21
21
  cogitator bridge status # the dispatcher, the sessions it knows, the jobs in progress
22
22
  cogitator bridge log --follow # every letter as it goes
23
23
  cogitator bridge log --job 12 # everything about one job
24
+ cogitator bridge doctor # whether Claude Code and Codex can be reached, and what to fix
24
25
  ```
25
26
 
26
27
  `cogitator daemon start --bridge` hosts it inside the assistant daemon instead. Its files live in `~/.cogitator/bridge` (`COGITATOR_BRIDGE_HOME` moves them): `bridge.db` and `bridge.sock`, both kept to their owner.
27
28
 
29
+ ## Claude Code and Codex
30
+
31
+ The dispatcher of `cogitator bridge serve` reaches both harnesses with the commands they document, and changes nothing in their settings.
32
+
33
+ | | Claude Code | Codex |
34
+ | ----------------------- | --------------------------------------------------------- | ------------------------------------------------------------- |
35
+ | A letter reaches it by | a `Stop` hook of the session that waits at the bridge | `codex queue --resume` |
36
+ | A session for a job is | `claude --bg`, a background session `claude attach` opens | `codex exec`, a thread `codex resume` opens |
37
+ | It wakes by itself when | the session carries the hook | the thread is open in the Codex app, or the local daemon runs |
38
+ | Before it can start | Claude Code must trust the folder | nothing |
39
+
40
+ **Claude Code.** Nothing is pushed into a window from outside. After every turn a background hook of the session runs `cogitator bridge wait`, which waits at the dispatcher and, when a letter comes, exits with code 2 and the letter on stderr: that wakes the session with the letter as its next input (`asyncRewake` in Claude Code's hooks). Under the letter it adds one line saying how to answer through the bridge. While the hook waits the session is free, you can talk to it. A session the bridge starts carries the hook itself. For the sessions you open yourself, put it into the project's `.claude/settings.local.json`, `cogitator bridge doctor` prints the exact lines:
41
+
42
+ ```json
43
+ {
44
+ "hooks": {
45
+ "Stop": [
46
+ {
47
+ "hooks": [
48
+ {
49
+ "type": "command",
50
+ "command": "cogitator bridge wait --hook claude-code --timeout 43140",
51
+ "timeout": 43200,
52
+ "async": true,
53
+ "asyncRewake": true
54
+ }
55
+ ]
56
+ }
57
+ ]
58
+ }
59
+ }
60
+ ```
61
+
62
+ A dispatcher that keeps its files somewhere else (`--home`, `COGITATOR_BRIDGE_HOME`) puts that folder into the hook, so its sessions call it and not the default one. A session without the hook still gets its letters, when it asks: `cogitator bridge inbox`. The hook waits 12 hours at most, then the session reads its mail at its next turn. A session a person opened decides for itself what to do with a job another agent hands it: every letter says it was not typed by the user, and such a session may ask its person before it acts. A session the bridge started for a job takes the job as its task. Claude Code starts a background session only in a folder it trusts: the bridge checks that first and fails the job with what to do (open the folder in Claude Code once and accept its prompt).
63
+
64
+ **Codex.** A letter goes into the message queue of the thread. A thread open in the Codex app takes it within seconds. A thread that is open nowhere, such as one the bridge started, wakes only when Codex's local daemon runs (`codex app-server daemon start`). The bridge never starts that daemon for you: without it the letter stays in the queue until the thread is opened. Codex does not tell the two cases apart, so the journal notes every letter queued while no daemon runs. A thread the bridge starts runs in the `workspace-write` sandbox, and what it prints goes to a file of its own in `~/.cogitator/bridge/sessions`, which the bridge never removes. From that sandbox the thread cannot reach the bridge with shell commands, so the bridge takes the final answer of its first turn as the report, and a turn that fails as a failed job. A thread that has to ask questions on the way needs a wider sandbox until the MCP tools arrive: `cogitator bridge serve --codex-sandbox danger-full-access`, or the `sandbox` option of `codexAdapter`. That sandbox holds nothing back, so name it only on a machine where you would let the thread do anything.
65
+
66
+ **From inside a session.** Until the bridge has tools of its own, an agent calls it from its shell. The session is known by what its harness put into the environment.
67
+
68
+ ```bash
69
+ cogitator bridge delegate codex "Write the tests for the rate limiter" --check "pnpm test"
70
+ cogitator bridge send --job 12 --kind question "Mock Redis or run a real one?"
71
+ cogitator bridge send --job 12 --kind report "Done: 14 tests pass"
72
+ cogitator bridge inbox
73
+ cogitator bridge cancel 12 "Not needed any more"
74
+ ```
75
+
76
+ A long text is piped in: `git diff | cogitator bridge send --job 12 --kind note -`. A text that starts with a dash goes after `--`, so it is not taken for an option.
77
+
28
78
  ## A job from hand-over to report
29
79
 
30
80
  ```typescript
@@ -88,7 +138,9 @@ A job also carries who handed it over and who carries it out, the project and th
88
138
 
89
139
  A letter moves `queued`, `delivered`, `read`, `handled` and never back. `acknowledge(letterId)` is how a note is put away. A question or a job is not dismissed that way: it is done with once answered or reported on, or when its job is over.
90
140
 
91
- A retry is safe when the letter has an id: `send({ id })` and `createJob({ letterId })` change nothing the second time. The same id with other words is refused. A field the bridge does not know is refused too, instead of being dropped in silence.
141
+ A letter is text: one with a NUL character in it is refused, since no harness can be handed it. A retry is safe when the letter has an id: `send({ id })` and `createJob({ letterId })` change nothing the second time. The same id with other words is refused. A field the bridge does not know is refused too, instead of being dropped in silence.
142
+
143
+ `wait({ timeoutMs })` is the inbox for a process that would rather sleep than ask: it answers the moment a letter is queued for the session, and with nothing when the time runs out. What it returns stays queued until `delivered(ids)` says it reached the session, so a waiter that dies with a letter in hand loses nothing. A session has one waiter at a time, and a letter a waiter holds is given to nobody else meanwhile, so a session reached two ways does not get it twice. `waitForMail` wraps both and also waits for a dispatcher that is not running, which is what `cogitator bridge wait` does.
92
144
 
93
145
  `inbox()` returns 20 letters at most (`limit`, up to 100) and no more text than one answer holds, and marks only the letters it returned: call it again for the rest. `inbox({ unhandled: true })` adds the newest of what was taken before and not answered or put away, for a session that may have missed an answer, and `afterSeq` looks further back or forward than one call returns. `letters()` and `readJournal()` return 200 entries at most, go on from the last one with `afterSeq`. The history of the A2A task under a job keeps the first 4000 characters of a long letter, the letter itself is kept whole.
94
146
 
@@ -103,7 +155,9 @@ A session enters the address book the first time it calls the bridge, and gets a
103
155
 
104
156
  When no session fits and the harness has an adapter that can start one, the bridge starts it for the job. When several fit, the call is refused with their names and how long ago each was heard from. Every worktree of a repository is one project. A harness name is letters, digits, `.`, `_` and `-`, whatever the case. A session is addressed by whatever it is called, or the start of it, as long as that does not begin with `-`.
105
157
 
106
- A session that has not called the bridge for 12 hours and has no job in progress is taken for gone, so yesterday's closed window does not stand in the way of today's. It is back under the same name the moment it calls again.
158
+ A session that has not called the bridge for 12 hours and has no job in progress is taken for gone, so yesterday's closed window does not stand in the way of today's. It is back under the same name the moment it calls again. Where the harness can list its sessions (`claude agents --json`), the bridge asks once a minute: a session that is listed, or whose hook waits for mail, stays however long it is silent, and one that was listed and then is missing two times in a row counts as gone, its jobs failing with that reason instead of after the reply timeout.
159
+
160
+ Folders are compared by their real path, so a project reached through a symlink is the same project.
107
161
 
108
162
  ## Limits
109
163
 
@@ -118,7 +172,8 @@ Each number is a default that `hostBridge({ limits })` changes.
118
172
  | Jobs out | 20 | An agent with that many jobs still in progress cannot hand over another |
119
173
  | Jobs per hour | 60 | Handing over faster is refused as a loop |
120
174
  | Sessions starting | 2 | No more sessions are started at once |
121
- | Silence | 12 hours | A session with no job in progress is taken for gone |
175
+ | Silence | 12 hours | A session with no job in progress is taken for gone, unless its harness lists it or its hook waits |
176
+ | Session check | 1 minute | How often a harness that can list its sessions is asked which of them still run |
122
177
  | Delivery | 5 attempts | Retried with a growing wait, then left for the inbox |
123
178
 
124
179
  Two more rules have no number. A letter that says what the previous one in the same direction said is not delivered, and neither is a job the same agent already has from the caller and has not finished.
@@ -141,9 +196,82 @@ await host.close();
141
196
 
142
197
  `hostBridge` throws `BridgeError` with the code `already_running` when another dispatcher holds the store. Which dispatcher owns the store is decided by the store itself: a lease row taken in a transaction, renewed on every tick and checked inside every write. A dispatcher whose process is gone is replaced at once, and one that was replaced while its machine slept writes nothing after it wakes. `BridgeDispatcher` and `SqliteBridgeStore` are exported for tests and tools of your own, and on their own they take no lease: it is `hostBridge` that makes sure there is one writer.
143
198
 
144
- ### Adapters
199
+ ## Agents the bridge hosts
200
+
201
+ Claude Code and Codex live in their own apps. Any other agent can live in the host: the bridge starts a session for a job, hands it the job's first letter as its turn, and takes the agent's answer for the job's report. The agent needs no tool to report, and one that fails reports that.
202
+
203
+ ```typescript
204
+ import { Agent, Cogitator } from '@cogitator-ai/core';
205
+ import { cogitatorSessions, hostBridge, hostedAdapter } from '@cogitator-ai/bridge';
206
+
207
+ const cogitator = new Cogitator({ memory: { adapter: 'memory' } });
208
+ const reviewer = new Agent({
209
+ name: 'reviewer',
210
+ model: 'ollama/qwen3.5:4b',
211
+ instructions: 'You review diffs. The first line of a letter says who sent it.',
212
+ });
213
+
214
+ const host = await hostBridge({
215
+ adapters: [
216
+ hostedAdapter({
217
+ harness: 'qwen',
218
+ steer: true,
219
+ open: cogitatorSessions({ runtime: cogitator, agent: reviewer }),
220
+ }),
221
+ ],
222
+ });
223
+ ```
145
224
 
146
- An adapter tells the bridge how to reach the sessions of one harness:
225
+ Now `delegate qwen "Review the diff"` from a Claude Code window starts a run of `reviewer` and wakes the window with its answer. Every session keeps its own thread, so with memory configured the agent remembers its earlier turns. An answer or a note that arrives while a run goes on steers it in the middle, a second job waits for its own turn, and so does what is written about it meanwhile. A job that is canceled stops the run that carries it out, and one canceled before its turn is never started. A run that pauses for an approval or for a question of a tool fails its job, since nobody is there to answer: give a hosted agent the permission rules it needs before it starts.
226
+
227
+ An agent of the [Agent Client Protocol](https://www.npmjs.com/package/@cogitator-ai/acp), such as Gemini CLI, is hosted the same way through `AcpAgentProvider`. Its permissions are decided by the provider's rules, since no person sits at a session the bridge started. A provider works in the folder of its workspace whatever folder a job names, so say where that is with `root` (a job for another folder is refused), or give `provider` as a function that makes one for the folder of each session:
228
+
229
+ ```typescript
230
+ import { AcpAgentProvider, resolveAcpAgent } from '@cogitator-ai/acp';
231
+ import { hostedAdapter, providerSessions } from '@cogitator-ai/bridge';
232
+ import { LocalWorkspace } from '@cogitator-ai/core';
233
+
234
+ const workspace = new LocalWorkspace({ root: process.cwd() });
235
+ const launch = await resolveAcpAgent('gemini');
236
+ const provider = new AcpAgentProvider({
237
+ agent: { command: launch.command, args: launch.args },
238
+ workspace,
239
+ name: 'gemini',
240
+ permissions: { rules: { allow: ['Bash(pnpm test *)'] } },
241
+ });
242
+ const gemini = hostedAdapter({
243
+ harness: 'gemini',
244
+ open: providerSessions({ provider, root: process.cwd() }),
245
+ });
246
+ ```
247
+
248
+ A session of a provider stays in the folder it was opened for: a later job for a folder outside it fails with that reason.
249
+
250
+ `open` returns a session: anything with a `turn(text, { job })` whose `result` resolves with the agent's answer, so a session of your own is a few lines. Hosted sessions live in the host's process and end with it.
251
+
252
+ ## Adapters
253
+
254
+ An adapter tells the bridge how to reach the sessions of one harness. `claudeCodeAdapter()`, `codexAdapter()` and `hostedAdapter()` are the ones above. `cogitator bridge serve` runs the first two as they come. To choose the permission mode of Claude Code sessions or the sandbox of Codex threads, or to add hosted agents, host the dispatcher in a process of your own:
255
+
256
+ ```typescript
257
+ import {
258
+ claudeCodeAdapter,
259
+ codexAdapter,
260
+ cogitatorSessions,
261
+ hostBridge,
262
+ hostedAdapter,
263
+ } from '@cogitator-ai/bridge';
264
+
265
+ const host = await hostBridge({
266
+ adapters: [
267
+ claudeCodeAdapter({ permissionMode: 'acceptEdits' }),
268
+ codexAdapter({ sandbox: 'read-only' }),
269
+ hostedAdapter({ harness: 'qwen', open: cogitatorSessions({ runtime: cogitator, agent }) }),
270
+ ],
271
+ });
272
+ ```
273
+
274
+ The port is small enough to write an adapter of your own:
147
275
 
148
276
  ```typescript
149
277
  import type { BridgeAdapter } from '@cogitator-ai/bridge';
@@ -160,11 +288,31 @@ const adapter: BridgeAdapter = {
160
288
  const host = await hostBridge({ adapters: [adapter] });
161
289
  ```
162
290
 
163
- Without an adapter a session still takes part: its letters wait in its inbox.
291
+ | Member | What it is for |
292
+ | --------------- | --------------------------------------------------------------------------------------------------------------- |
293
+ | `deliver` | Hands a letter to a session. Leave it out when the sessions wait for their mail themselves, as Claude Code's do |
294
+ | `createSession` | Starts a session for a job, and may hand it the first letter while it does |
295
+ | `identify` | Tells which session a process belongs to, from its environment or from what the harness wrote to its hook |
296
+ | `liveSessions` | Lists the sessions that run, so the bridge knows a closed one from a quiet one |
297
+ | `health` | What `cogitator bridge doctor` shows: versions, the commands the bridge needs, each with what to do about it |
298
+ | `attach` | Gets the calls the adapter's own sessions make, such as to report |
299
+ | `close` | Stops what the adapter runs when the dispatcher closes |
300
+
301
+ `deliver` may return `{ note }`: something a person should know about the delivery, kept in the journal.
302
+
303
+ `@cogitator-ai/bridge/testing` has what the adapters of this package are tested with. `adapterConformanceCases(target)` is the adapter contract as cases to run against your adapter and its harness. `installFakeHarnesses()` puts stand-ins of the `claude` and `codex` commands on a `PATH`: they keep background sessions, fire hooks, hold queues and run a scripted turn, so code that drives the real command lines is tested without them.
304
+
305
+ ```typescript
306
+ import { adapterConformanceCases } from '@cogitator-ai/bridge/testing';
307
+
308
+ for (const conformance of adapterConformanceCases(target)) {
309
+ it.skipIf(conformance.skip !== undefined)(conformance.name, () => conformance.run());
310
+ }
311
+ ```
164
312
 
165
313
  ## Trust
166
314
 
167
- The bridge is a tool of one person on one machine. The socket and the database are created for their owner only, a folder or a database that belongs to another user is refused, and every process of that user can connect: read any job and letter, and call as a session by naming its id. A job is done inside the project it is handed over in, or the worktree its caller works in. Do not point `COGITATOR_BRIDGE_HOME` at a folder other users can write to. On Windows the dispatcher listens on a named pipe that other users of the same machine can reach, so run it only on a machine you do not share.
315
+ The bridge is a tool of one person on one machine. The socket and the database are created for their owner only, a folder or a database that belongs to another user is refused, and every process of that user can connect: read any job and letter, and call as a session by naming its id. A job is done inside the project it is handed over in, or the worktree its caller works in. A session the bridge starts has the rights its harness gives it: a Claude Code session the permission mode you configure (`claudeCodeAdapter({ permissionMode })`), a Codex thread the `workspace-write` sandbox unless you choose another (`codexAdapter({ sandbox })`). A letter is text from another agent, never an order from you: every letter says so in its first line. Do not point `COGITATOR_BRIDGE_HOME` at a folder other users can write to. On Windows the dispatcher listens on a named pipe that other users of the same machine can reach, so run it only on a machine you do not share. The Claude Code and Codex adapters run on macOS and Linux.
168
316
 
169
317
  ## Errors
170
318
 
@@ -0,0 +1,123 @@
1
+ import type { CreateJobInput, CreateJobResult, InboxInput, SendLetterInput, SendLetterResult } from './inputs.js';
2
+ import type { LetterFilter } from './store/store.js';
3
+ import type { AdapterCapabilities, AgentRecord, BridgeJob, CallerIdentity, Letter, RenderedLetter } from './types.js';
4
+ /** A letter on its way to a session, as an adapter gets it. */
5
+ export interface LetterDelivery {
6
+ agent: AgentRecord;
7
+ letter: RenderedLetter;
8
+ job: BridgeJob;
9
+ }
10
+ /** What an adapter adds about a letter it handed over, kept in the journal. */
11
+ export interface DeliveryReceipt {
12
+ /** What a person should know: the harness took the letter, but the session will not wake */
13
+ note?: string;
14
+ }
15
+ /** What the bridge asks of an adapter that starts a session for a job. */
16
+ export interface SessionRequest {
17
+ /** The name the bridge gave the session, to hand to it as `COGITATOR_BRIDGE_AGENT` */
18
+ agentName: string;
19
+ harness: string;
20
+ project: string;
21
+ cwd: string;
22
+ sessionName?: string;
23
+ job: BridgeJob;
24
+ /** The job's first letter, for a harness that takes the first message when it starts a session */
25
+ firstLetter: RenderedLetter;
26
+ }
27
+ export interface CreatedSession {
28
+ sessionId: string;
29
+ sessionName?: string;
30
+ /** Whether the session got `firstLetter` when it started, so the bridge does not deliver it again */
31
+ deliveredFirstLetter?: boolean;
32
+ }
33
+ /** A session of a harness that runs on this machine right now, as the harness lists it. */
34
+ export interface LiveSession {
35
+ sessionId: string;
36
+ cwd?: string;
37
+ name?: string;
38
+ /** In the middle of a turn */
39
+ busy?: boolean;
40
+ }
41
+ /** What tells a process of a harness apart: its environment and, for a hook, what the harness wrote to it. */
42
+ export interface IdentifyContext {
43
+ env: NodeJS.ProcessEnv;
44
+ /** The folder the process runs in, an absolute path */
45
+ cwd: string;
46
+ /** The stdin of a hook of the harness, when the process is one */
47
+ hookInput?: string;
48
+ }
49
+ export type HealthStatus = 'ok' | 'warn' | 'fail';
50
+ /** One thing `cogitator bridge doctor` looked at. */
51
+ export interface HealthCheck {
52
+ /** Stable among the checks of one adapter: `version`, `trust`, `hook` */
53
+ id: string;
54
+ /** What was looked at, in a few words */
55
+ title: string;
56
+ status: HealthStatus;
57
+ /** What was found */
58
+ detail?: string;
59
+ /** What to do about a `warn` or a `fail`, a command where there is one */
60
+ fix?: string;
61
+ }
62
+ export interface HealthContext {
63
+ /** The project folder to look at: its trust, its hooks */
64
+ cwd: string;
65
+ }
66
+ /**
67
+ * The bridge as a session an adapter runs itself calls it, such as to report when its agent is
68
+ * done. Every call names the agent it is made as.
69
+ */
70
+ export interface BridgeCalls {
71
+ register(identity: CallerIdentity): Promise<AgentRecord>;
72
+ createJob(caller: string, input: CreateJobInput): Promise<CreateJobResult>;
73
+ send(caller: string, input: SendLetterInput): Promise<SendLetterResult>;
74
+ inbox(caller: string, input?: InboxInput): Promise<RenderedLetter[]>;
75
+ acknowledge(caller: string, letterId: string): Promise<Letter>;
76
+ cancel(caller: string, job: number, reason?: string): Promise<BridgeJob>;
77
+ job(number: number): Promise<BridgeJob>;
78
+ letters(filter?: LetterFilter): Promise<Letter[]>;
79
+ }
80
+ /**
81
+ * How the bridge reaches the sessions of one harness. Without an adapter a session still takes
82
+ * part: it reads its inbox whenever it calls the bridge.
83
+ */
84
+ export interface BridgeAdapter {
85
+ /** The harness it reaches, in lower case: letters, digits, `.`, `_` and `-` */
86
+ readonly harness: string;
87
+ /** The mechanism letters travel by, recorded with every session of the harness */
88
+ readonly delivery: string;
89
+ readonly capabilities: AdapterCapabilities;
90
+ /**
91
+ * True when the adapter runs every session of the harness itself, so one `liveSessions` does
92
+ * not list cannot be running. Otherwise only a session that was listed before and no longer
93
+ * is counts as gone: a harness may run sessions it lists nowhere
94
+ */
95
+ readonly ownsSessions?: boolean;
96
+ /**
97
+ * Hands the letter to the session. Rejects when it could not, and the bridge tries again.
98
+ * Absent when the sessions of the harness wait for their mail themselves (`BridgeDispatcher.wait`,
99
+ * `cogitator bridge wait`): the bridge then keeps a letter until the session's waiter takes it
100
+ */
101
+ deliver?(delivery: LetterDelivery): Promise<DeliveryReceipt | void>;
102
+ /** Starts a session for a job. Present when `capabilities.createSession` is true */
103
+ createSession?(request: SessionRequest): Promise<CreatedSession>;
104
+ /**
105
+ * Tells which session of the harness a process belongs to. Undefined when it is none of them.
106
+ * A harness that only names its session in the environment needs none: `callerFromEnv` reads
107
+ * the variables of the harnesses the bridge knows
108
+ */
109
+ identify?(context: IdentifyContext): CallerIdentity | undefined;
110
+ /**
111
+ * The sessions of the harness running on this machine, when the harness can list them. The
112
+ * bridge keeps a listed session in its address book however long it is silent, and takes one
113
+ * that was listed and no longer is for gone
114
+ */
115
+ liveSessions?(): Promise<LiveSession[]>;
116
+ /** What `cogitator bridge doctor` shows about the harness: its version, its commands, the folder */
117
+ health?(context: HealthContext): Promise<HealthCheck[]>;
118
+ /** Called once by the dispatcher that uses the adapter, with the calls its sessions may make */
119
+ attach?(bridge: BridgeCalls): void;
120
+ /** Stops what the adapter runs. The host calls it when it closes */
121
+ close?(): Promise<void>;
122
+ }
123
+ //# sourceMappingURL=adapter.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=adapter.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"adapter.js","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":""}
@@ -0,0 +1,90 @@
1
+ import type { BridgeAdapter } from '../adapter.js';
2
+ /** How letters reach a Claude Code session: a hook of the session waits for them. */
3
+ export declare const CLAUDE_DELIVERY = "hook";
4
+ /** How long a waiter of a Claude Code session waits before Claude Code ends it, 12 hours. */
5
+ export declare const DEFAULT_HOOK_TIMEOUT_S: number;
6
+ export interface ClaudeWaitHookOptions {
7
+ /** How the bridge's command line is run, `cogitator bridge` by default */
8
+ bridgeCommand?: string;
9
+ /** Seconds the hook may run, 12 hours by default */
10
+ timeoutS?: number;
11
+ /** The name the bridge gave the session, for one it started itself */
12
+ agentName?: string;
13
+ /** The folder of the bridge's files, when it is not the default one */
14
+ bridgeHome?: string;
15
+ }
16
+ export interface ClaudeHookSettings {
17
+ hooks: {
18
+ Stop: {
19
+ hooks: {
20
+ type: 'command';
21
+ command: string;
22
+ timeout: number;
23
+ async: true;
24
+ asyncRewake: true;
25
+ }[];
26
+ }[];
27
+ };
28
+ }
29
+ /** The command a hook of a Claude Code session runs to wait for the session's mail. */
30
+ export declare function claudeWaitCommand(options?: ClaudeWaitHookOptions): string;
31
+ /**
32
+ * The settings that make a Claude Code session wake for its mail: a `Stop` hook that runs in the
33
+ * background after every turn (`async`), waits at the bridge, and wakes the session with what it
34
+ * got (`asyncRewake`: the hook exits with code 2 and its stderr becomes the session's next
35
+ * input). The session is free while the hook waits. Merge them into the project's
36
+ * `.claude/settings.local.json`, or pass them to one session with `claude --settings`.
37
+ */
38
+ export declare function claudeWaitHook(options?: ClaudeWaitHookOptions): ClaudeHookSettings;
39
+ /** Whether Claude Code settings hold a hook that waits at the bridge. */
40
+ export declare function hasClaudeWaitHook(settings: unknown): boolean;
41
+ export type ClaudeTrust = 'trusted' | 'untrusted' | 'unknown';
42
+ /**
43
+ * Whether Claude Code trusts a folder, read from where it records that a person accepted its
44
+ * trust prompt (`projects[<folder>].hasTrustDialogAccepted` in `~/.claude.json`). Trust of a
45
+ * folder covers the folders inside it. `unknown` when the record cannot be read.
46
+ */
47
+ export declare function claudeTrust(folder: string, configPath?: string): ClaudeTrust;
48
+ export interface ClaudeCodeAdapterOptions {
49
+ /** The Claude Code executable, `claude` on `PATH` by default */
50
+ command?: string;
51
+ /** How a session's hook runs the bridge's command line, `cogitator bridge` by default */
52
+ bridgeCommand?: string;
53
+ /**
54
+ * The folder of the bridge's files the sessions call, when it is not the default one:
55
+ * `COGITATOR_BRIDGE_HOME` of `env` when that is set. A hook is told it on its command line,
56
+ * since Claude Code does not promise a background session the environment it was started in
57
+ */
58
+ bridgeHome?: string;
59
+ /** The environment of the commands and of the sessions it starts, `process.env` by default */
60
+ env?: NodeJS.ProcessEnv;
61
+ /** The permission mode of the sessions it starts, Claude Code's own default when absent */
62
+ permissionMode?: string;
63
+ /** More arguments for `claude --bg`, such as `['--model', 'sonnet']` */
64
+ sessionArgs?: readonly string[];
65
+ /** Seconds a waiter may wait before Claude Code ends it, 12 hours by default */
66
+ hookTimeoutS?: number;
67
+ /**
68
+ * Where Claude Code records the folders it trusts: `.claude.json` in `CLAUDE_CONFIG_DIR` when
69
+ * the environment sets it, `~/.claude.json` otherwise
70
+ */
71
+ configPath?: string;
72
+ /**
73
+ * Where Claude Code keeps a person's settings: `settings.json` in `CLAUDE_CONFIG_DIR` when the
74
+ * environment sets it, `~/.claude/settings.json` otherwise
75
+ */
76
+ userSettingsPath?: string;
77
+ /** How long a started session may take to show up among the running ones, 30 s by default */
78
+ sessionListedMs?: number;
79
+ }
80
+ /**
81
+ * Reaches Claude Code sessions in their own windows. A session started for a job runs in the
82
+ * background of Claude Code (`claude --bg`): `claude attach` opens it, `claude agents` lists it.
83
+ * Letters reach a session through a hook of its own: after every turn the hook waits at the
84
+ * bridge (`cogitator bridge wait`) and wakes the session with the mail, so nothing is pushed
85
+ * into a window from outside and the session stays free to talk to. A session the bridge starts
86
+ * carries the hook itself. One opened by a person needs it in the project's settings, see
87
+ * `claudeWaitHook`.
88
+ */
89
+ export declare function claudeCodeAdapter(options?: ClaudeCodeAdapterOptions): BridgeAdapter;
90
+ //# sourceMappingURL=claude.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"claude.d.ts","sourceRoot":"","sources":["../../src/adapters/claude.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,aAAa,EAOd,MAAM,eAAe,CAAC;AAcvB,qFAAqF;AACrF,eAAO,MAAM,eAAe,SAAS,CAAC;AAEtC,6FAA6F;AAC7F,eAAO,MAAM,sBAAsB,QAAY,CAAC;AAKhD,MAAM,WAAW,qBAAqB;IACpC,0EAA0E;IAC1E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,oDAAoD;IACpD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sEAAsE;IACtE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uEAAuE;IACvE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE;QACL,IAAI,EAAE;YACJ,KAAK,EAAE;gBACL,IAAI,EAAE,SAAS,CAAC;gBAChB,OAAO,EAAE,MAAM,CAAC;gBAChB,OAAO,EAAE,MAAM,CAAC;gBAChB,KAAK,EAAE,IAAI,CAAC;gBACZ,WAAW,EAAE,IAAI,CAAC;aACnB,EAAE,CAAC;SACL,EAAE,CAAC;KACL,CAAC;CACH;AAED,uFAAuF;AACvF,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,qBAA0B,GAAG,MAAM,CAW7E;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,OAAO,GAAE,qBAA0B,GAAG,kBAAkB,CAkBtF;AAED,yEAAyE;AACzE,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,OAAO,GAAG,OAAO,CAQ5D;AAwCD,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,WAAW,GAAG,SAAS,CAAC;AAE9D;;;;GAIG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,MAAM,EACd,UAAU,SAAkC,GAC3C,WAAW,CAcb;AAED,MAAM,WAAW,wBAAwB;IACvC,gEAAgE;IAChE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yFAAyF;IACzF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8FAA8F;IAC9F,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,2FAA2F;IAC3F,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,wEAAwE;IACxE,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,gFAAgF;IAChF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,6FAA6F;IAC7F,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAoBD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,wBAA6B,GAAG,aAAa,CA0OvF"}