@cogitator-ai/bridge 0.2.0 → 0.4.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.
- package/README.md +242 -8
- package/dist/adapter.d.ts +130 -0
- package/dist/adapter.d.ts.map +1 -0
- package/dist/adapter.js +2 -0
- package/dist/adapter.js.map +1 -0
- package/dist/adapters/claude.d.ts +145 -0
- package/dist/adapters/claude.d.ts.map +1 -0
- package/dist/adapters/claude.js +537 -0
- package/dist/adapters/claude.js.map +1 -0
- package/dist/adapters/codex.d.ts +71 -0
- package/dist/adapters/codex.d.ts.map +1 -0
- package/dist/adapters/codex.js +379 -0
- package/dist/adapters/codex.js.map +1 -0
- package/dist/adapters/exec.d.ts +70 -0
- package/dist/adapters/exec.d.ts.map +1 -0
- package/dist/adapters/exec.js +161 -0
- package/dist/adapters/exec.js.map +1 -0
- package/dist/adapters/hosted.d.ts +168 -0
- package/dist/adapters/hosted.d.ts.map +1 -0
- package/dist/adapters/hosted.js +361 -0
- package/dist/adapters/hosted.js.map +1 -0
- package/dist/adapters/tools-server.d.ts +21 -0
- package/dist/adapters/tools-server.d.ts.map +1 -0
- package/dist/adapters/tools-server.js +19 -0
- package/dist/adapters/tools-server.js.map +1 -0
- package/dist/client.d.ts +9 -2
- package/dist/client.d.ts.map +1 -1
- package/dist/client.js +17 -3
- package/dist/client.js.map +1 -1
- package/dist/dispatcher.d.ts +69 -17
- package/dist/dispatcher.d.ts.map +1 -1
- package/dist/dispatcher.js +243 -17
- package/dist/dispatcher.js.map +1 -1
- package/dist/host.d.ts +1 -1
- package/dist/host.d.ts.map +1 -1
- package/dist/index.d.ts +18 -3
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +9 -1
- package/dist/index.js.map +1 -1
- package/dist/inputs.d.ts +40 -1
- package/dist/inputs.d.ts.map +1 -1
- package/dist/inputs.js +25 -2
- package/dist/inputs.js.map +1 -1
- package/dist/paths.d.ts +6 -0
- package/dist/paths.d.ts.map +1 -1
- package/dist/paths.js +19 -0
- package/dist/paths.js.map +1 -1
- package/dist/protocol.d.ts +5 -0
- package/dist/protocol.d.ts.map +1 -1
- package/dist/protocol.js +5 -0
- package/dist/protocol.js.map +1 -1
- package/dist/server.d.ts.map +1 -1
- package/dist/server.js +6 -1
- package/dist/server.js.map +1 -1
- package/dist/setup/claude.d.ts +53 -0
- package/dist/setup/claude.d.ts.map +1 -0
- package/dist/setup/claude.js +261 -0
- package/dist/setup/claude.js.map +1 -0
- package/dist/setup/codex.d.ts +22 -0
- package/dist/setup/codex.d.ts.map +1 -0
- package/dist/setup/codex.js +95 -0
- package/dist/setup/codex.js.map +1 -0
- package/dist/setup/files.d.ts +22 -0
- package/dist/setup/files.d.ts.map +1 -0
- package/dist/setup/files.js +86 -0
- package/dist/setup/files.js.map +1 -0
- package/dist/setup/index.d.ts +6 -0
- package/dist/setup/index.d.ts.map +1 -0
- package/dist/setup/index.js +3 -0
- package/dist/setup/index.js.map +1 -0
- package/dist/setup/setup.d.ts +52 -0
- package/dist/setup/setup.d.ts.map +1 -0
- package/dist/setup/setup.js +2 -0
- package/dist/setup/setup.js.map +1 -0
- package/dist/testing/conformance.d.ts +65 -0
- package/dist/testing/conformance.d.ts.map +1 -0
- package/dist/testing/conformance.js +217 -0
- package/dist/testing/conformance.js.map +1 -0
- package/dist/testing/fake-harnesses.d.ts +121 -0
- package/dist/testing/fake-harnesses.d.ts.map +1 -0
- package/dist/testing/fake-harnesses.js +303 -0
- package/dist/testing/fake-harnesses.js.map +1 -0
- package/dist/testing/index.d.ts +5 -0
- package/dist/testing/index.d.ts.map +1 -0
- package/dist/testing/index.js +3 -0
- package/dist/testing/index.js.map +1 -0
- package/dist/tools/caller.d.ts +39 -0
- package/dist/tools/caller.d.ts.map +1 -0
- package/dist/tools/caller.js +92 -0
- package/dist/tools/caller.js.map +1 -0
- package/dist/tools/guidance.d.ts +33 -0
- package/dist/tools/guidance.d.ts.map +1 -0
- package/dist/tools/guidance.js +92 -0
- package/dist/tools/guidance.js.map +1 -0
- package/dist/tools/index.d.ts +27 -0
- package/dist/tools/index.d.ts.map +1 -0
- package/dist/tools/index.js +24 -0
- package/dist/tools/index.js.map +1 -0
- package/dist/tools/tools.d.ts +38 -0
- package/dist/tools/tools.d.ts.map +1 -0
- package/dist/tools/tools.js +354 -0
- package/dist/tools/tools.js.map +1 -0
- package/dist/types.d.ts +3 -39
- package/dist/types.d.ts.map +1 -1
- package/dist/types.js +2 -0
- package/dist/types.js.map +1 -1
- package/dist/waiter.d.ts +36 -0
- package/dist/waiter.d.ts.map +1 -0
- package/dist/waiter.js +92 -0
- package/dist/waiter.js.map +1 -0
- package/fakes/claude.mjs +715 -0
- package/fakes/codex.mjs +571 -0
- package/fakes/lib.mjs +585 -0
- package/fakes/mcp.mjs +151 -0
- package/fakes/sandbox.mjs +84 -0
- package/package.json +19 -1
package/README.md
CHANGED
|
@@ -6,7 +6,9 @@ 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
|
-
|
|
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.
|
|
10
|
+
|
|
11
|
+
Agents call the bridge with tools of their own, served over MCP: `delegate`, `ask`, `answer`, `report` and the rest. A server of tools lives outside the sandbox of its session, so a Codex thread in a sandbox takes part like any other. `cogitator bridge install` sets Claude Code and Codex up for a project, and shows every change before it makes it.
|
|
10
12
|
|
|
11
13
|
```bash
|
|
12
14
|
pnpm add @cogitator-ai/bridge better-sqlite3
|
|
@@ -21,10 +23,102 @@ cogitator bridge serve # in the foreground, until Ctrl+C
|
|
|
21
23
|
cogitator bridge status # the dispatcher, the sessions it knows, the jobs in progress
|
|
22
24
|
cogitator bridge log --follow # every letter as it goes
|
|
23
25
|
cogitator bridge log --job 12 # everything about one job
|
|
26
|
+
cogitator bridge doctor # whether Claude Code and Codex can be reached, and what to fix
|
|
24
27
|
```
|
|
25
28
|
|
|
26
29
|
`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
30
|
|
|
31
|
+
## Set a project up
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
cogitator bridge install # Claude Code and Codex, for you in this project
|
|
35
|
+
cogitator bridge install claude # one harness
|
|
36
|
+
cogitator bridge install --dry-run # list the changes, make none
|
|
37
|
+
cogitator bridge uninstall # take out what install put in, and nothing else
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
`install` lists every change first and makes them after a yes (`--yes` skips the question):
|
|
41
|
+
|
|
42
|
+
| | Claude Code | Codex |
|
|
43
|
+
| ------------------- | ------------------------------------------------------------ | ---------------------------------- |
|
|
44
|
+
| The server of tools | `claude mcp add --scope local bridge` | `codex mcp add bridge` |
|
|
45
|
+
| Hooks | the project's `.claude/settings.local.json` | none needed |
|
|
46
|
+
| Tools run unasked | the rule `mcp__bridge` in the same file, unless `--no-allow` | Codex asks nothing for these tools |
|
|
47
|
+
| Notes for sessions | `CLAUDE.md` of the project, unless `--no-notes` | `AGENTS.md`, unless `--no-notes` |
|
|
48
|
+
|
|
49
|
+
What names a path of this machine goes where only you have it, never into a file the project shares. A linked git worktree is a checkout of its own: run `install` in each one whose sessions need the bridge. The notes say how the tools go together and that a letter of the bridge is not typed by you. By default they tell a session you opened to ask you before it carries out a job of another agent: `--take-jobs` lets it go ahead. `--user` sets every project of yours up instead of one. Codex keeps its servers for every project whichever way it is asked, so a per-project `uninstall` leaves its server and `uninstall codex --user` removes it. Settings that are not a JSON object are refused, never overwritten, and running `install` again changes only what is out of date. Sessions that are open get the tools when they are started again.
|
|
50
|
+
|
|
51
|
+
### The tools
|
|
52
|
+
|
|
53
|
+
| Tool | What it does |
|
|
54
|
+
| ---------- | ------------------------------------------------------------------------------------------------ |
|
|
55
|
+
| `delegate` | Hands a job to `codex`, `claude` or an agent by name, and returns its number at once |
|
|
56
|
+
| `ask` | Asks the other agent of a job a question. The answer wakes the session |
|
|
57
|
+
| `answer` | Answers a question another agent asked |
|
|
58
|
+
| `report` | Reports the result of a job handed to this session, which ends the job. `failed` says it did not |
|
|
59
|
+
| `note` | Tells the other agent something it need not answer |
|
|
60
|
+
| `inbox` | Reads the letters that wait, when nothing woke the session |
|
|
61
|
+
| `job` | Shows one job: its state, and for a job of this session its latest letters |
|
|
62
|
+
| `jobs` | Lists the jobs this session handed over or carries out |
|
|
63
|
+
| `cancel` | Takes back a job this session handed over |
|
|
64
|
+
| `agents` | Lists the sessions the bridge knows in the project, and the agents it can start a session of |
|
|
65
|
+
|
|
66
|
+
No tool waits for another agent. The server tells every client the same in its `instructions`: after `delegate` say in one line what was handed over and end the turn, reply to a letter with the tools and never only in the chat, and treat a job of another agent as that agent's request, not the user's.
|
|
67
|
+
|
|
68
|
+
## Claude Code and Codex
|
|
69
|
+
|
|
70
|
+
The dispatcher of `cogitator bridge serve` reaches both harnesses with the commands they document. It changes nothing in their settings: `cogitator bridge install` does, for the sessions you open yourself, and a session the bridge starts carries what it needs.
|
|
71
|
+
|
|
72
|
+
| | Claude Code | Codex |
|
|
73
|
+
| ----------------------- | --------------------------------------------------------- | ------------------------------------------------------------- |
|
|
74
|
+
| A letter reaches it by | a `Stop` hook of the session that waits at the bridge | `codex queue --resume` |
|
|
75
|
+
| A session for a job is | `claude --bg`, a background session `claude attach` opens | `codex exec`, a thread `codex resume` opens |
|
|
76
|
+
| It wakes by itself when | the session carries the hook | the thread is open in the Codex app, or the local daemon runs |
|
|
77
|
+
| The tools know it by | a hook that adds the session to every tool call | the thread Codex names in every tool call |
|
|
78
|
+
| Before it can start | Claude Code must trust the folder | nothing |
|
|
79
|
+
|
|
80
|
+
**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, `cogitator bridge install` puts it into the project's `.claude/settings.local.json`:
|
|
81
|
+
|
|
82
|
+
```json
|
|
83
|
+
{
|
|
84
|
+
"hooks": {
|
|
85
|
+
"Stop": [
|
|
86
|
+
{
|
|
87
|
+
"hooks": [
|
|
88
|
+
{
|
|
89
|
+
"type": "command",
|
|
90
|
+
"command": "cogitator bridge wait --hook claude-code --timeout 43140 --tools",
|
|
91
|
+
"timeout": 43200,
|
|
92
|
+
"async": true,
|
|
93
|
+
"asyncRewake": true
|
|
94
|
+
}
|
|
95
|
+
]
|
|
96
|
+
}
|
|
97
|
+
]
|
|
98
|
+
}
|
|
99
|
+
}
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
A dispatcher that keeps its files somewhere else (`--home`, `COGITATOR_BRIDGE_HOME`) puts that folder into the hook and into the command of the server of tools, so its sessions call it and not the default one. A session without the hook still gets its letters, when it asks: the `inbox` tool, or `cogitator bridge inbox`.
|
|
103
|
+
|
|
104
|
+
Claude Code starts a server of tools once and keeps it across `/clear`, so the session a server was started for is not always the one that calls. A second hook, on the bridge's tools only (`PreToolUse`, `cogitator bridge caller`), adds the session to the arguments of every call, and the tools go by that. Without it they go by the session the server was started for, which `cogitator bridge doctor` warns about. 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).
|
|
105
|
+
|
|
106
|
+
**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.
|
|
107
|
+
|
|
108
|
+
The sandbox keeps the shell commands of a thread from the bridge's socket (`connect EPERM`), and Codex gives a server of tools none of the thread's environment. The tools need neither: Codex runs their server outside the sandbox and names the thread in every call, so a thread asks, answers and reports from any sandbox. The tools say they destroy nothing and stay on this machine, which is why Codex runs them without an approval, in `codex exec` too. A thread the bridge starts gets the tools whatever Codex has set up, and when its turn ends without a report the bridge takes its final answer as one, and a turn that fails as a failed job. `cogitator bridge serve --codex-sandbox <mode>` and the `sandbox` option of `codexAdapter` choose what the thread itself may do: `danger-full-access` holds nothing back, so name it only on a machine where you would let the thread do anything.
|
|
109
|
+
|
|
110
|
+
**From a shell.** A session without the tools, and you at a terminal inside one, call the bridge with its command line. The session is known by what its harness put into the environment. A sandbox that keeps commands from sockets keeps this from the bridge too: that is what the tools are for.
|
|
111
|
+
|
|
112
|
+
```bash
|
|
113
|
+
cogitator bridge delegate codex "Write the tests for the rate limiter" --check "pnpm test"
|
|
114
|
+
cogitator bridge send --job 12 --kind question "Mock Redis or run a real one?"
|
|
115
|
+
cogitator bridge send --job 12 --kind report "Done: 14 tests pass"
|
|
116
|
+
cogitator bridge inbox
|
|
117
|
+
cogitator bridge cancel 12 "Not needed any more"
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
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.
|
|
121
|
+
|
|
28
122
|
## A job from hand-over to report
|
|
29
123
|
|
|
30
124
|
```typescript
|
|
@@ -88,7 +182,9 @@ A job also carries who handed it over and who carries it out, the project and th
|
|
|
88
182
|
|
|
89
183
|
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
184
|
|
|
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.
|
|
185
|
+
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.
|
|
186
|
+
|
|
187
|
+
`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
188
|
|
|
93
189
|
`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
190
|
|
|
@@ -103,7 +199,9 @@ A session enters the address book the first time it calls the bridge, and gets a
|
|
|
103
199
|
|
|
104
200
|
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
201
|
|
|
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.
|
|
202
|
+
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.
|
|
203
|
+
|
|
204
|
+
Folders are compared by their real path, so a project reached through a symlink is the same project.
|
|
107
205
|
|
|
108
206
|
## Limits
|
|
109
207
|
|
|
@@ -118,7 +216,8 @@ Each number is a default that `hostBridge({ limits })` changes.
|
|
|
118
216
|
| Jobs out | 20 | An agent with that many jobs still in progress cannot hand over another |
|
|
119
217
|
| Jobs per hour | 60 | Handing over faster is refused as a loop |
|
|
120
218
|
| 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
|
|
219
|
+
| Silence | 12 hours | A session with no job in progress is taken for gone, unless its harness lists it or its hook waits |
|
|
220
|
+
| Session check | 1 minute | How often a harness that can list its sessions is asked which of them still run |
|
|
122
221
|
| Delivery | 5 attempts | Retried with a growing wait, then left for the inbox |
|
|
123
222
|
|
|
124
223
|
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 +240,123 @@ await host.close();
|
|
|
141
240
|
|
|
142
241
|
`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
242
|
|
|
144
|
-
|
|
243
|
+
## Agents the bridge hosts
|
|
145
244
|
|
|
146
|
-
|
|
245
|
+
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.
|
|
246
|
+
|
|
247
|
+
```typescript
|
|
248
|
+
import { Agent, Cogitator } from '@cogitator-ai/core';
|
|
249
|
+
import { cogitatorSessions, hostBridge, hostedAdapter } from '@cogitator-ai/bridge';
|
|
250
|
+
|
|
251
|
+
const cogitator = new Cogitator({ memory: { adapter: 'memory' } });
|
|
252
|
+
const reviewer = new Agent({
|
|
253
|
+
name: 'reviewer',
|
|
254
|
+
model: 'ollama/qwen3.5:4b',
|
|
255
|
+
instructions: 'You review diffs. The first line of a letter says who sent it.',
|
|
256
|
+
});
|
|
257
|
+
|
|
258
|
+
const host = await hostBridge({
|
|
259
|
+
adapters: [
|
|
260
|
+
hostedAdapter({
|
|
261
|
+
harness: 'qwen',
|
|
262
|
+
steer: true,
|
|
263
|
+
open: cogitatorSessions({ runtime: cogitator, agent: reviewer }),
|
|
264
|
+
}),
|
|
265
|
+
],
|
|
266
|
+
});
|
|
267
|
+
```
|
|
268
|
+
|
|
269
|
+
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.
|
|
270
|
+
|
|
271
|
+
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:
|
|
272
|
+
|
|
273
|
+
```typescript
|
|
274
|
+
import { AcpAgentProvider, resolveAcpAgent } from '@cogitator-ai/acp';
|
|
275
|
+
import { hostedAdapter, providerSessions } from '@cogitator-ai/bridge';
|
|
276
|
+
import { LocalWorkspace } from '@cogitator-ai/core';
|
|
277
|
+
|
|
278
|
+
const workspace = new LocalWorkspace({ root: process.cwd() });
|
|
279
|
+
const launch = await resolveAcpAgent('gemini');
|
|
280
|
+
const provider = new AcpAgentProvider({
|
|
281
|
+
agent: { command: launch.command, args: launch.args },
|
|
282
|
+
workspace,
|
|
283
|
+
name: 'gemini',
|
|
284
|
+
permissions: { rules: { allow: ['Bash(pnpm test *)'] } },
|
|
285
|
+
});
|
|
286
|
+
const gemini = hostedAdapter({
|
|
287
|
+
harness: 'gemini',
|
|
288
|
+
open: providerSessions({ provider, root: process.cwd() }),
|
|
289
|
+
});
|
|
290
|
+
```
|
|
291
|
+
|
|
292
|
+
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.
|
|
293
|
+
|
|
294
|
+
`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.
|
|
295
|
+
|
|
296
|
+
## The tools in your own process
|
|
297
|
+
|
|
298
|
+
`cogitator bridge mcp` is a few lines over `@cogitator-ai/bridge/tools`, which needs `@cogitator-ai/core`:
|
|
299
|
+
|
|
300
|
+
```typescript
|
|
301
|
+
import { MCPServer } from '@cogitator-ai/mcp';
|
|
302
|
+
import { bridgePaths } from '@cogitator-ai/bridge';
|
|
303
|
+
import { BRIDGE_INSTRUCTIONS, bridgeTools } from '@cogitator-ai/bridge/tools';
|
|
304
|
+
|
|
305
|
+
const server = new MCPServer({
|
|
306
|
+
name: 'cogitator-bridge',
|
|
307
|
+
version: '1.0.0',
|
|
308
|
+
transport: 'stdio',
|
|
309
|
+
instructions: BRIDGE_INSTRUCTIONS,
|
|
310
|
+
});
|
|
311
|
+
server.registerTools(bridgeTools({ socketPath: bridgePaths().socket }));
|
|
312
|
+
await server.start();
|
|
313
|
+
```
|
|
314
|
+
|
|
315
|
+
Every call reaches the dispatcher on a connection of its own, so the server may start before the dispatcher and lives through its restarts. Who calls is read from each call, not once (`callerOfToolCall`): the hint a hook of the harness added to the arguments, else the thread Codex names in `_meta`, else the environment of the server.
|
|
316
|
+
|
|
317
|
+
`claudeSetup()` and `codexSetup()` are what `cogitator bridge install` runs. `install()` and `uninstall()` return steps, each with a title, the command it runs or the lines a file gains, and an `apply()`: nothing changes until a step is applied, and a harness that is set up has no steps.
|
|
318
|
+
|
|
319
|
+
```typescript
|
|
320
|
+
import { claudeSetup } from '@cogitator-ai/bridge';
|
|
321
|
+
|
|
322
|
+
const setup = claudeSetup({
|
|
323
|
+
toolsServer: { command: 'cogitator', args: ['bridge', 'mcp'] },
|
|
324
|
+
});
|
|
325
|
+
const steps = await setup.install({
|
|
326
|
+
project: process.cwd(),
|
|
327
|
+
scope: 'project',
|
|
328
|
+
notes: true,
|
|
329
|
+
takeJobs: false,
|
|
330
|
+
allowTools: true,
|
|
331
|
+
});
|
|
332
|
+
for (const step of steps) console.log(step.title, step.lines);
|
|
333
|
+
```
|
|
334
|
+
|
|
335
|
+
Pass `toolsServer` to `claudeCodeAdapter()` and `codexAdapter()` too, and the sessions they start get the tools: Claude Code with `--mcp-config`, the hook that names the session and the rule for the tools, Codex as overrides of its configuration.
|
|
336
|
+
|
|
337
|
+
## Adapters
|
|
338
|
+
|
|
339
|
+
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:
|
|
340
|
+
|
|
341
|
+
```typescript
|
|
342
|
+
import {
|
|
343
|
+
claudeCodeAdapter,
|
|
344
|
+
codexAdapter,
|
|
345
|
+
cogitatorSessions,
|
|
346
|
+
hostBridge,
|
|
347
|
+
hostedAdapter,
|
|
348
|
+
} from '@cogitator-ai/bridge';
|
|
349
|
+
|
|
350
|
+
const host = await hostBridge({
|
|
351
|
+
adapters: [
|
|
352
|
+
claudeCodeAdapter({ permissionMode: 'acceptEdits' }),
|
|
353
|
+
codexAdapter({ sandbox: 'read-only' }),
|
|
354
|
+
hostedAdapter({ harness: 'qwen', open: cogitatorSessions({ runtime: cogitator, agent }) }),
|
|
355
|
+
],
|
|
356
|
+
});
|
|
357
|
+
```
|
|
358
|
+
|
|
359
|
+
The port is small enough to write an adapter of your own:
|
|
147
360
|
|
|
148
361
|
```typescript
|
|
149
362
|
import type { BridgeAdapter } from '@cogitator-ai/bridge';
|
|
@@ -160,11 +373,32 @@ const adapter: BridgeAdapter = {
|
|
|
160
373
|
const host = await hostBridge({ adapters: [adapter] });
|
|
161
374
|
```
|
|
162
375
|
|
|
163
|
-
|
|
376
|
+
| Member | What it is for |
|
|
377
|
+
| --------------- | --------------------------------------------------------------------------------------------------------------- |
|
|
378
|
+
| `deliver` | Hands a letter to a session. Leave it out when the sessions wait for their mail themselves, as Claude Code's do |
|
|
379
|
+
| `createSession` | Starts a session for a job, and may hand it the first letter while it does |
|
|
380
|
+
| `identify` | Tells which session a process belongs to, from its environment or from what the harness wrote to its hook |
|
|
381
|
+
| `toolCallHook` | Answers the hook a harness runs before a bridge tool call, so the call carries the session that makes it |
|
|
382
|
+
| `liveSessions` | Lists the sessions that run, so the bridge knows a closed one from a quiet one |
|
|
383
|
+
| `health` | What `cogitator bridge doctor` shows: versions, the commands the bridge needs, each with what to do about it |
|
|
384
|
+
| `attach` | Gets the calls the adapter's own sessions make, such as to report |
|
|
385
|
+
| `close` | Stops what the adapter runs when the dispatcher closes |
|
|
386
|
+
|
|
387
|
+
`deliver` may return `{ note }`: something a person should know about the delivery, kept in the journal.
|
|
388
|
+
|
|
389
|
+
`@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. They run MCP servers the way the real ones were measured to (`claude mcp`, `codex mcp`, the environment a server gets, what a tool call carries, the tools a session nobody sits at may call), and keep the commands of a sandboxed Codex thread from sockets and from writing outside its folder, so a test shows what works from a sandbox.
|
|
390
|
+
|
|
391
|
+
```typescript
|
|
392
|
+
import { adapterConformanceCases } from '@cogitator-ai/bridge/testing';
|
|
393
|
+
|
|
394
|
+
for (const conformance of adapterConformanceCases(target)) {
|
|
395
|
+
it.skipIf(conformance.skip !== undefined)(conformance.name, () => conformance.run());
|
|
396
|
+
}
|
|
397
|
+
```
|
|
164
398
|
|
|
165
399
|
## Trust
|
|
166
400
|
|
|
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.
|
|
401
|
+
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, and whether a session you opened takes a job without asking you is yours to say at `cogitator bridge install` (`--take-jobs`). A tool call names its session the way a connection to the socket does, and is believed the same way. 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
402
|
|
|
169
403
|
## Errors
|
|
170
404
|
|
|
@@ -0,0 +1,130 @@
|
|
|
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
|
+
* What a hook of the harness answers before a call of a bridge tool, so the call carries the
|
|
112
|
+
* session that makes it: the harness then hands the tool the arguments with the hint in them
|
|
113
|
+
* (`TOOL_CALL_HINT_KEY`). Undefined when the hook's input names no session, and the call goes
|
|
114
|
+
* on as it was. For a harness whose server of tools outlives its sessions
|
|
115
|
+
*/
|
|
116
|
+
toolCallHook?(context: IdentifyContext): string | undefined;
|
|
117
|
+
/**
|
|
118
|
+
* The sessions of the harness running on this machine, when the harness can list them. The
|
|
119
|
+
* bridge keeps a listed session in its address book however long it is silent, and takes one
|
|
120
|
+
* that was listed and no longer is for gone
|
|
121
|
+
*/
|
|
122
|
+
liveSessions?(): Promise<LiveSession[]>;
|
|
123
|
+
/** What `cogitator bridge doctor` shows about the harness: its version, its commands, the folder */
|
|
124
|
+
health?(context: HealthContext): Promise<HealthCheck[]>;
|
|
125
|
+
/** Called once by the dispatcher that uses the adapter, with the calls its sessions may make */
|
|
126
|
+
attach?(bridge: BridgeCalls): void;
|
|
127
|
+
/** Stops what the adapter runs. The host calls it when it closes */
|
|
128
|
+
close?(): Promise<void>;
|
|
129
|
+
}
|
|
130
|
+
//# 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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"}
|
package/dist/adapter.js
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":""}
|
|
@@ -0,0 +1,145 @@
|
|
|
1
|
+
import type { BridgeAdapter } from '../adapter.js';
|
|
2
|
+
import { type ToolsServerCommand } from './tools-server.js';
|
|
3
|
+
/** How letters reach a Claude Code session: a hook of the session waits for them. */
|
|
4
|
+
export declare const CLAUDE_DELIVERY = "hook";
|
|
5
|
+
/** How long a waiter of a Claude Code session waits before Claude Code ends it, 12 hours. */
|
|
6
|
+
export declare const DEFAULT_HOOK_TIMEOUT_S: number;
|
|
7
|
+
export interface ClaudeWaitHookOptions {
|
|
8
|
+
/** How the bridge's command line is run, `cogitator bridge` by default */
|
|
9
|
+
bridgeCommand?: string;
|
|
10
|
+
/** Seconds the hook may run, 12 hours by default */
|
|
11
|
+
timeoutS?: number;
|
|
12
|
+
/** The name the bridge gave the session, for one it started itself */
|
|
13
|
+
agentName?: string;
|
|
14
|
+
/** The folder of the bridge's files, when it is not the default one */
|
|
15
|
+
bridgeHome?: string;
|
|
16
|
+
/** Whether the session has the bridge's tools: the waiter then says to answer with them */
|
|
17
|
+
tools?: boolean;
|
|
18
|
+
}
|
|
19
|
+
export interface ClaudeHookSettings {
|
|
20
|
+
hooks: {
|
|
21
|
+
Stop: {
|
|
22
|
+
hooks: {
|
|
23
|
+
type: 'command';
|
|
24
|
+
command: string;
|
|
25
|
+
timeout: number;
|
|
26
|
+
async: true;
|
|
27
|
+
asyncRewake: true;
|
|
28
|
+
}[];
|
|
29
|
+
}[];
|
|
30
|
+
};
|
|
31
|
+
}
|
|
32
|
+
/** The command a hook of a Claude Code session runs to wait for the session's mail. */
|
|
33
|
+
export declare function claudeWaitCommand(options?: ClaudeWaitHookOptions): string;
|
|
34
|
+
/**
|
|
35
|
+
* The settings that make a Claude Code session wake for its mail: a `Stop` hook that runs in the
|
|
36
|
+
* background after every turn (`async`), waits at the bridge, and wakes the session with what it
|
|
37
|
+
* got (`asyncRewake`: the hook exits with code 2 and its stderr becomes the session's next
|
|
38
|
+
* input). The session is free while the hook waits. Merge them into the project's
|
|
39
|
+
* `.claude/settings.local.json`, or pass them to one session with `claude --settings`.
|
|
40
|
+
*/
|
|
41
|
+
export declare function claudeWaitHook(options?: ClaudeWaitHookOptions): ClaudeHookSettings;
|
|
42
|
+
/** Whether Claude Code settings hold a hook that waits at the bridge. */
|
|
43
|
+
export declare function hasClaudeWaitHook(settings: unknown): boolean;
|
|
44
|
+
/** How a Claude Code session names the tools of the bridge's server, and what rules match them by. */
|
|
45
|
+
export declare const CLAUDE_TOOLS_PREFIX = "mcp__bridge";
|
|
46
|
+
/** The permission rule that lets a session call the bridge's tools without a prompt. */
|
|
47
|
+
export declare const CLAUDE_TOOLS_PERMISSION = "mcp__bridge";
|
|
48
|
+
export interface ClaudeToolsHookOptions {
|
|
49
|
+
/** How the bridge's command line is run, `cogitator bridge` by default */
|
|
50
|
+
bridgeCommand?: string;
|
|
51
|
+
}
|
|
52
|
+
export interface ClaudeToolsHookSettings {
|
|
53
|
+
hooks: {
|
|
54
|
+
PreToolUse: {
|
|
55
|
+
matcher: string;
|
|
56
|
+
hooks: {
|
|
57
|
+
type: 'command';
|
|
58
|
+
command: string;
|
|
59
|
+
timeout: number;
|
|
60
|
+
}[];
|
|
61
|
+
}[];
|
|
62
|
+
};
|
|
63
|
+
}
|
|
64
|
+
/** The command a hook of a Claude Code session runs before a call of a bridge tool. */
|
|
65
|
+
export declare function claudeCallerCommand(options?: ClaudeToolsHookOptions): string;
|
|
66
|
+
/**
|
|
67
|
+
* The settings that tell the bridge's tools which Claude Code session calls them: a `PreToolUse`
|
|
68
|
+
* hook on the tools of the bridge's server that adds the session to the arguments of the call.
|
|
69
|
+
* Claude Code starts the server once and keeps it across `/clear`, so the session the server was
|
|
70
|
+
* started for is not always the one that calls. Without the hook the tools go by that first
|
|
71
|
+
* session.
|
|
72
|
+
*/
|
|
73
|
+
export declare function claudeToolsHook(options?: ClaudeToolsHookOptions): ClaudeToolsHookSettings;
|
|
74
|
+
/** Whether Claude Code settings hold the hook that names the session of a bridge tool call. */
|
|
75
|
+
export declare function hasClaudeToolsHook(settings: unknown): boolean;
|
|
76
|
+
/**
|
|
77
|
+
* What the hook of `claudeToolsHook` answers Claude Code with: the arguments of the call with
|
|
78
|
+
* the session that makes it added (`hookSpecificOutput.updatedInput`). Undefined when the input
|
|
79
|
+
* is not that of a `PreToolUse` hook, and the call goes on as the model wrote it.
|
|
80
|
+
*
|
|
81
|
+
* @param hookInput what Claude Code wrote to the hook's stdin
|
|
82
|
+
*/
|
|
83
|
+
export declare function claudeToolCallHook(hookInput: string): string | undefined;
|
|
84
|
+
/**
|
|
85
|
+
* Where Claude Code has the bridge's server of tools for the sessions of a folder: `local`
|
|
86
|
+
* (this person, this project), `project` (the project's `.mcp.json`) or `user` (this person,
|
|
87
|
+
* every project). Undefined when it has it nowhere.
|
|
88
|
+
*/
|
|
89
|
+
export declare function claudeToolsScope(folder: string, configPath?: string): 'local' | 'project' | 'user' | undefined;
|
|
90
|
+
export type ClaudeTrust = 'trusted' | 'untrusted' | 'unknown';
|
|
91
|
+
/**
|
|
92
|
+
* Whether Claude Code trusts a folder, read from where it records that a person accepted its
|
|
93
|
+
* trust prompt (`projects[<folder>].hasTrustDialogAccepted` in `~/.claude.json`). Trust of a
|
|
94
|
+
* folder covers the folders inside it. `unknown` when the record cannot be read.
|
|
95
|
+
*/
|
|
96
|
+
export declare function claudeTrust(folder: string, configPath?: string): ClaudeTrust;
|
|
97
|
+
export interface ClaudeCodeAdapterOptions {
|
|
98
|
+
/** The Claude Code executable, `claude` on `PATH` by default */
|
|
99
|
+
command?: string;
|
|
100
|
+
/** How a session's hook runs the bridge's command line, `cogitator bridge` by default */
|
|
101
|
+
bridgeCommand?: string;
|
|
102
|
+
/**
|
|
103
|
+
* The folder of the bridge's files the sessions call, when it is not the default one:
|
|
104
|
+
* `COGITATOR_BRIDGE_HOME` of `env` when that is set. A hook is told it on its command line,
|
|
105
|
+
* since Claude Code does not promise a background session the environment it was started in
|
|
106
|
+
*/
|
|
107
|
+
bridgeHome?: string;
|
|
108
|
+
/** The environment of the commands and of the sessions it starts, `process.env` by default */
|
|
109
|
+
env?: NodeJS.ProcessEnv;
|
|
110
|
+
/** The permission mode of the sessions it starts, Claude Code's own default when absent */
|
|
111
|
+
permissionMode?: string;
|
|
112
|
+
/** More arguments for `claude --bg`, such as `['--model', 'sonnet']` */
|
|
113
|
+
sessionArgs?: readonly string[];
|
|
114
|
+
/** Seconds a waiter may wait before Claude Code ends it, 12 hours by default */
|
|
115
|
+
hookTimeoutS?: number;
|
|
116
|
+
/**
|
|
117
|
+
* Where Claude Code records the folders it trusts: `.claude.json` in `CLAUDE_CONFIG_DIR` when
|
|
118
|
+
* the environment sets it, `~/.claude.json` otherwise
|
|
119
|
+
*/
|
|
120
|
+
configPath?: string;
|
|
121
|
+
/**
|
|
122
|
+
* Where Claude Code keeps a person's settings: `settings.json` in `CLAUDE_CONFIG_DIR` when the
|
|
123
|
+
* environment sets it, `~/.claude/settings.json` otherwise
|
|
124
|
+
*/
|
|
125
|
+
userSettingsPath?: string;
|
|
126
|
+
/** How long a started session may take to show up among the running ones, 30 s by default */
|
|
127
|
+
sessionListedMs?: number;
|
|
128
|
+
/**
|
|
129
|
+
* How a session starts the bridge's server of tools. With it the sessions the adapter starts
|
|
130
|
+
* get the tools, the hook that tells the tools which session calls, and the permission to call
|
|
131
|
+
* them. Without it they use the bridge's command line
|
|
132
|
+
*/
|
|
133
|
+
toolsServer?: ToolsServerCommand;
|
|
134
|
+
}
|
|
135
|
+
/**
|
|
136
|
+
* Reaches Claude Code sessions in their own windows. A session started for a job runs in the
|
|
137
|
+
* background of Claude Code (`claude --bg`): `claude attach` opens it, `claude agents` lists it.
|
|
138
|
+
* Letters reach a session through a hook of its own: after every turn the hook waits at the
|
|
139
|
+
* bridge (`cogitator bridge wait`) and wakes the session with the mail, so nothing is pushed
|
|
140
|
+
* into a window from outside and the session stays free to talk to. A session the bridge starts
|
|
141
|
+
* carries the hook itself. One opened by a person needs it in the project's settings, see
|
|
142
|
+
* `claudeWaitHook`.
|
|
143
|
+
*/
|
|
144
|
+
export declare function claudeCodeAdapter(options?: ClaudeCodeAdapterOptions): BridgeAdapter;
|
|
145
|
+
//# sourceMappingURL=claude.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"claude.d.ts","sourceRoot":"","sources":["../../src/adapters/claude.ts"],"names":[],"mappings":"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"}
|