@cogitator-ai/bridge 0.3.0 → 0.5.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 +154 -19
- package/dist/adapter.d.ts +9 -1
- package/dist/adapter.d.ts.map +1 -1
- package/dist/adapters/claude.d.ts +55 -0
- package/dist/adapters/claude.d.ts.map +1 -1
- package/dist/adapters/claude.js +195 -17
- package/dist/adapters/claude.js.map +1 -1
- package/dist/adapters/codex.d.ts +16 -3
- package/dist/adapters/codex.d.ts.map +1 -1
- package/dist/adapters/codex.js +58 -9
- package/dist/adapters/codex.js.map +1 -1
- package/dist/adapters/exec.d.ts +16 -3
- package/dist/adapters/exec.d.ts.map +1 -1
- package/dist/adapters/exec.js +22 -10
- package/dist/adapters/exec.js.map +1 -1
- package/dist/adapters/hosted.d.ts +36 -4
- package/dist/adapters/hosted.d.ts.map +1 -1
- package/dist/adapters/hosted.js +188 -9
- package/dist/adapters/hosted.js.map +1 -1
- 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 +16 -1
- package/dist/client.d.ts.map +1 -1
- package/dist/client.js +24 -1
- package/dist/client.js.map +1 -1
- package/dist/dispatcher.d.ts +115 -3
- package/dist/dispatcher.d.ts.map +1 -1
- package/dist/dispatcher.js +496 -23
- package/dist/dispatcher.js.map +1 -1
- package/dist/errors.d.ts +1 -1
- package/dist/errors.d.ts.map +1 -1
- package/dist/errors.js.map +1 -1
- package/dist/guards.d.ts +3 -2
- package/dist/guards.d.ts.map +1 -1
- package/dist/guards.js +4 -3
- package/dist/guards.js.map +1 -1
- package/dist/host.d.ts +9 -0
- package/dist/host.d.ts.map +1 -1
- package/dist/host.js +2 -0
- package/dist/host.js.map +1 -1
- package/dist/index.d.ts +19 -9
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +11 -6
- package/dist/index.js.map +1 -1
- package/dist/inputs.d.ts +76 -1
- package/dist/inputs.d.ts.map +1 -1
- package/dist/inputs.js +31 -1
- package/dist/inputs.js.map +1 -1
- package/dist/job-record.d.ts +1 -0
- package/dist/job-record.d.ts.map +1 -1
- package/dist/job-record.js +1 -0
- package/dist/job-record.js.map +1 -1
- package/dist/letters.d.ts.map +1 -1
- package/dist/letters.js +23 -1
- package/dist/letters.js.map +1 -1
- package/dist/person-channel.d.ts +45 -0
- package/dist/person-channel.d.ts.map +1 -0
- package/dist/person-channel.js +154 -0
- package/dist/person-channel.js.map +1 -0
- package/dist/person-inbox.d.ts +30 -0
- package/dist/person-inbox.d.ts.map +1 -0
- package/dist/person-inbox.js +60 -0
- package/dist/person-inbox.js.map +1 -0
- package/dist/person.d.ts +52 -0
- package/dist/person.d.ts.map +1 -0
- package/dist/person.js +30 -0
- package/dist/person.js.map +1 -0
- package/dist/protocol.d.ts +6 -1
- package/dist/protocol.d.ts.map +1 -1
- package/dist/protocol.js +5 -1
- package/dist/protocol.js.map +1 -1
- package/dist/rights/index.d.ts +36 -0
- package/dist/rights/index.d.ts.map +1 -0
- package/dist/rights/index.js +186 -0
- package/dist/rights/index.js.map +1 -0
- package/dist/server.d.ts.map +1 -1
- package/dist/server.js +9 -0
- 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/store/sqlite.d.ts +6 -1
- package/dist/store/sqlite.d.ts.map +1 -1
- package/dist/store/sqlite.js +74 -18
- package/dist/store/sqlite.js.map +1 -1
- package/dist/store/store.d.ts +6 -2
- package/dist/store/store.d.ts.map +1 -1
- package/dist/testing/fake-harnesses.d.ts +22 -2
- package/dist/testing/fake-harnesses.d.ts.map +1 -1
- package/dist/testing/fake-harnesses.js +16 -4
- package/dist/testing/fake-harnesses.js.map +1 -1
- package/dist/testing/index.d.ts +1 -1
- package/dist/testing/index.d.ts.map +1 -1
- 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 +93 -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 +377 -0
- package/dist/tools/tools.js.map +1 -0
- package/dist/types.d.ts +81 -1
- package/dist/types.d.ts.map +1 -1
- package/dist/types.js +29 -0
- package/dist/types.js.map +1 -1
- package/fakes/claude.mjs +288 -23
- package/fakes/codex.mjs +199 -19
- package/fakes/lib.mjs +94 -16
- package/fakes/mcp.mjs +151 -0
- package/fakes/sandbox.mjs +84 -0
- package/package.json +18 -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
|
-
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.
|
|
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
|
|
@@ -22,22 +24,61 @@ cogitator bridge status # the dispatcher, the sessions it knows, the job
|
|
|
22
24
|
cogitator bridge log --follow # every letter as it goes
|
|
23
25
|
cogitator bridge log --job 12 # everything about one job
|
|
24
26
|
cogitator bridge doctor # whether Claude Code and Codex can be reached, and what to fix
|
|
27
|
+
cogitator bridge asks # what waits for your word: permission requests, questions left to you
|
|
25
28
|
```
|
|
26
29
|
|
|
27
30
|
`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.
|
|
28
31
|
|
|
32
|
+
## Set a project up
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
cogitator bridge install # Claude Code and Codex, for you in this project
|
|
36
|
+
cogitator bridge install claude # one harness
|
|
37
|
+
cogitator bridge install --dry-run # list the changes, make none
|
|
38
|
+
cogitator bridge uninstall # take out what install put in, and nothing else
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
`install` lists every change first and makes them after a yes (`--yes` skips the question):
|
|
42
|
+
|
|
43
|
+
| | Claude Code | Codex |
|
|
44
|
+
| ------------------- | ------------------------------------------------------------ | ---------------------------------- |
|
|
45
|
+
| The server of tools | `claude mcp add --scope local bridge` | `codex mcp add bridge` |
|
|
46
|
+
| Hooks | the project's `.claude/settings.local.json` | none needed |
|
|
47
|
+
| Tools run unasked | the rule `mcp__bridge` in the same file, unless `--no-allow` | Codex asks nothing for these tools |
|
|
48
|
+
| Notes for sessions | `CLAUDE.md` of the project, unless `--no-notes` | `AGENTS.md`, unless `--no-notes` |
|
|
49
|
+
|
|
50
|
+
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.
|
|
51
|
+
|
|
52
|
+
### The tools
|
|
53
|
+
|
|
54
|
+
| Tool | What it does |
|
|
55
|
+
| ---------- | --------------------------------------------------------------------------------------------------------------- |
|
|
56
|
+
| `delegate` | Hands a job to `codex`, `claude` or an agent by name, and returns its number at once |
|
|
57
|
+
| `ask` | Asks the other agent of a job a question. The answer wakes the session |
|
|
58
|
+
| `answer` | Answers a question another agent asked, or decides its permission request: allow, deny, or leave it to the user |
|
|
59
|
+
| `report` | Reports the result of a job handed to this session, which ends the job. `failed` says it did not |
|
|
60
|
+
| `note` | Tells the other agent something it need not answer |
|
|
61
|
+
| `inbox` | Reads the letters that wait, when nothing woke the session |
|
|
62
|
+
| `job` | Shows one job: its state, and for a job of this session its latest letters |
|
|
63
|
+
| `jobs` | Lists the jobs this session handed over or carries out |
|
|
64
|
+
| `cancel` | Takes back a job this session handed over |
|
|
65
|
+
| `agents` | Lists the sessions the bridge knows in the project, and the agents it can start a session of |
|
|
66
|
+
|
|
67
|
+
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.
|
|
68
|
+
|
|
29
69
|
## Claude Code and Codex
|
|
30
70
|
|
|
31
|
-
The dispatcher of `cogitator bridge serve` reaches both harnesses with the commands they document
|
|
71
|
+
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.
|
|
32
72
|
|
|
33
73
|
| | Claude Code | Codex |
|
|
34
74
|
| ----------------------- | --------------------------------------------------------- | ------------------------------------------------------------- |
|
|
35
75
|
| A letter reaches it by | a `Stop` hook of the session that waits at the bridge | `codex queue --resume` |
|
|
36
76
|
| A session for a job is | `claude --bg`, a background session `claude attach` opens | `codex exec`, a thread `codex resume` opens |
|
|
37
77
|
| It wakes by itself when | the session carries the hook | the thread is open in the Codex app, or the local daemon runs |
|
|
78
|
+
| The tools know it by | a hook that adds the session to every tool call | the thread Codex names in every tool call |
|
|
38
79
|
| Before it can start | Claude Code must trust the folder | nothing |
|
|
39
80
|
|
|
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,
|
|
81
|
+
**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`:
|
|
41
82
|
|
|
42
83
|
```json
|
|
43
84
|
{
|
|
@@ -47,7 +88,7 @@ The dispatcher of `cogitator bridge serve` reaches both harnesses with the comma
|
|
|
47
88
|
"hooks": [
|
|
48
89
|
{
|
|
49
90
|
"type": "command",
|
|
50
|
-
"command": "cogitator bridge wait --hook claude-code --timeout 43140",
|
|
91
|
+
"command": "cogitator bridge wait --hook claude-code --timeout 43140 --tools",
|
|
51
92
|
"timeout": 43200,
|
|
52
93
|
"async": true,
|
|
53
94
|
"asyncRewake": true
|
|
@@ -59,11 +100,15 @@ The dispatcher of `cogitator bridge serve` reaches both harnesses with the comma
|
|
|
59
100
|
}
|
|
60
101
|
```
|
|
61
102
|
|
|
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: `
|
|
103
|
+
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`.
|
|
104
|
+
|
|
105
|
+
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).
|
|
63
106
|
|
|
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.
|
|
107
|
+
**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.
|
|
65
108
|
|
|
66
|
-
|
|
109
|
+
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.
|
|
110
|
+
|
|
111
|
+
**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.
|
|
67
112
|
|
|
68
113
|
```bash
|
|
69
114
|
cogitator bridge delegate codex "Write the tests for the rate limiter" --check "pnpm test"
|
|
@@ -127,14 +172,14 @@ A job also carries who handed it over and who carries it out, the project and th
|
|
|
127
172
|
|
|
128
173
|
## Letters
|
|
129
174
|
|
|
130
|
-
| Kind | Sent by | Effect
|
|
131
|
-
| ------------ | ---------------- |
|
|
132
|
-
| `task` | `createJob` | The job itself
|
|
133
|
-
| `question` | either side | Needs an `answer`. From the one doing the job it puts the job on hold
|
|
134
|
-
| `permission` | either side | A question that asks for leave
|
|
135
|
-
| `answer` | the one asked | Answers a question, and resumes the job once none is open
|
|
136
|
-
| `report` | the one doing it | Ends the job, `outcome: 'completed'` (default) or `'failed'`
|
|
137
|
-
| `note` | either side | Something to know, needs no answer
|
|
175
|
+
| Kind | Sent by | Effect |
|
|
176
|
+
| ------------ | ---------------- | ------------------------------------------------------------------------------------------------ |
|
|
177
|
+
| `task` | `createJob` | The job itself |
|
|
178
|
+
| `question` | either side | Needs an `answer`. From the one doing the job it puts the job on hold |
|
|
179
|
+
| `permission` | either side | A question that asks for leave. When it names its call, the bridge decides whose answer it takes |
|
|
180
|
+
| `answer` | the one asked | Answers a question, and resumes the job once none is open |
|
|
181
|
+
| `report` | the one doing it | Ends the job, `outcome: 'completed'` (default) or `'failed'` |
|
|
182
|
+
| `note` | either side | Something to know, needs no answer |
|
|
138
183
|
|
|
139
184
|
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.
|
|
140
185
|
|
|
@@ -144,6 +189,53 @@ A letter is text: one with a NUL character in it is refused, since no harness ca
|
|
|
144
189
|
|
|
145
190
|
`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.
|
|
146
191
|
|
|
192
|
+
## Leave for a call, and the person
|
|
193
|
+
|
|
194
|
+
An agent that carries a job out sometimes needs leave for one call: to run a command, to change a file its own rules do not let it change. It asks with a `permission` letter that names the call (`ask`), and the bridge decides whose answer that takes before anybody is woken. The measure is the rights of the agent that handed the job over, read from the permission settings of the job's project (`.claude/settings.json`, `.cogitator/settings.json`, their `.local` files, the person's and the machine's), in the permission mode that agent runs in:
|
|
195
|
+
|
|
196
|
+
| Its rules say | What happens |
|
|
197
|
+
| ------------- | --------------------------------------------------------------------- |
|
|
198
|
+
| forbidden | The call is refused at once, in the bridge's name. Nobody is asked |
|
|
199
|
+
| allowed | The request goes to that agent, which answers `allow` or `deny` |
|
|
200
|
+
| ask a person | Only the person can allow it. The agent is told, and can still refuse |
|
|
201
|
+
|
|
202
|
+
So an agent never gets leave from another agent that the other one does not have itself. A job handed over from inside a job is bound by every agent up the chain. Without a rule the person is asked what a person at a session would be asked: a command, an address to fetch, a file outside the project. A change to the settings files themselves is always the person's to allow, whatever the rules and the mode say, and so is a command that names their folders: an agent does not write the rules it is judged by. For a command this reads the words of the command line and no more, as every rule on a command does.
|
|
203
|
+
|
|
204
|
+
The one who asked does not get the answer as mail: it waits for it with `verdict({ letter })`, which answers the moment the request is decided. A request whose job ends first counts as refused. The same call may be asked for again once it was allowed, and is held back as a repeat once it was refused.
|
|
205
|
+
|
|
206
|
+
An agent can also leave a letter to the person itself: `answer` with the decision `person` (`escalate` in code) passes a question or a request on, and the person's answer goes straight to the one who asked.
|
|
207
|
+
|
|
208
|
+
What waits for the person is theirs to answer from a terminal:
|
|
209
|
+
|
|
210
|
+
```bash
|
|
211
|
+
cogitator bridge asks # what waits for your word
|
|
212
|
+
cogitator bridge allow 12 # allow the call job 12 asks leave for
|
|
213
|
+
cogitator bridge deny 12 "not on a Friday"
|
|
214
|
+
cogitator bridge reply 12 "the release in March"
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
`serve` and the daemon also keep these letters in an inbox, `inbox.json` next to the database (an `experimental_Inbox` of core, so its sinks and whatever reads the file see them), and send them to a Telegram chat when `COGITATOR_BRIDGE_TELEGRAM_TOKEN` and `COGITATOR_BRIDGE_TELEGRAM_CHAT` name a bot and a chat: a permission request with Allow and Refuse buttons, a question to be answered by replying to it. `COGITATOR_BRIDGE_TELEGRAM_USERS` limits who in that chat is listened to. Give the bridge a bot of its own.
|
|
218
|
+
|
|
219
|
+
Waiting for the person does not spend the job's time: the deadline does not fail a job that waits for them, nor the jobs it is part of, and moves by as long as they waited once the person answered. An agent that takes a letter back from the person and answers it itself gets no time for it. The person has a limit of their own instead: after 4 hours they are reminded, after as long again the job fails. A permission request is a letter of the job like any other and counts against its letters.
|
|
220
|
+
|
|
221
|
+
In your own process the pieces are `hostBridge({ rights, person })`:
|
|
222
|
+
|
|
223
|
+
```typescript
|
|
224
|
+
import { channelRoute, hostBridge, inboxRoute, personRoutes } from '@cogitator-ai/bridge';
|
|
225
|
+
import { settingsRights } from '@cogitator-ai/bridge/rights';
|
|
226
|
+
import { telegramChannel } from '@cogitator-ai/channels';
|
|
227
|
+
import { experimental_Inbox } from '@cogitator-ai/core';
|
|
228
|
+
|
|
229
|
+
const telegram = channelRoute({ channel: telegramChannel({ token }), chatId: '123456' });
|
|
230
|
+
const host = await hostBridge({
|
|
231
|
+
rights: settingsRights(),
|
|
232
|
+
person: personRoutes([inboxRoute(new experimental_Inbox()), telegram]),
|
|
233
|
+
});
|
|
234
|
+
await telegram.start();
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
`rights` is any function from a job and a call to `allow`, `ask` or `deny`. Without one every call is the person's, and without `person` what only they could allow is refused. A route is anything with `ask` and `settle`, and `host.dispatcher.personAnswer({ letter, verdict })` takes the answer.
|
|
238
|
+
|
|
147
239
|
## Who a letter is for
|
|
148
240
|
|
|
149
241
|
A session enters the address book the first time it calls the bridge, and gets a name: `codex@my-project`, then `codex-2@my-project`. An address is:
|
|
@@ -174,6 +266,7 @@ Each number is a default that `hostBridge({ limits })` changes.
|
|
|
174
266
|
| Sessions starting | 2 | No more sessions are started at once |
|
|
175
267
|
| Silence | 12 hours | A session with no job in progress is taken for gone, unless its harness lists it or its hook waits |
|
|
176
268
|
| Session check | 1 minute | How often a harness that can list its sessions is asked which of them still run |
|
|
269
|
+
| Person's answer | 4 hours | The person is reminded of a letter that waits for them. After as long again the job fails |
|
|
177
270
|
| Delivery | 5 attempts | Retried with a growing wait, then left for the inbox |
|
|
178
271
|
|
|
179
272
|
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.
|
|
@@ -224,7 +317,7 @@ const host = await hostBridge({
|
|
|
224
317
|
|
|
225
318
|
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
319
|
|
|
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`.
|
|
320
|
+
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`. Nobody sits at a session the bridge started, so a call the provider's rules do not settle is asked through the bridge: the agent that handed the job over answers within its own rights, the person for the rest. A tool call of a runtime agent that needs approval goes the same way. 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
321
|
|
|
229
322
|
```typescript
|
|
230
323
|
import { AcpAgentProvider, resolveAcpAgent } from '@cogitator-ai/acp';
|
|
@@ -249,6 +342,47 @@ A session of a provider stays in the folder it was opened for: a later job for a
|
|
|
249
342
|
|
|
250
343
|
`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
344
|
|
|
345
|
+
## The tools in your own process
|
|
346
|
+
|
|
347
|
+
`cogitator bridge mcp` is a few lines over `@cogitator-ai/bridge/tools`, which needs `@cogitator-ai/core`:
|
|
348
|
+
|
|
349
|
+
```typescript
|
|
350
|
+
import { MCPServer } from '@cogitator-ai/mcp';
|
|
351
|
+
import { bridgePaths } from '@cogitator-ai/bridge';
|
|
352
|
+
import { BRIDGE_INSTRUCTIONS, bridgeTools } from '@cogitator-ai/bridge/tools';
|
|
353
|
+
|
|
354
|
+
const server = new MCPServer({
|
|
355
|
+
name: 'cogitator-bridge',
|
|
356
|
+
version: '1.0.0',
|
|
357
|
+
transport: 'stdio',
|
|
358
|
+
instructions: BRIDGE_INSTRUCTIONS,
|
|
359
|
+
});
|
|
360
|
+
server.registerTools(bridgeTools({ socketPath: bridgePaths().socket }));
|
|
361
|
+
await server.start();
|
|
362
|
+
```
|
|
363
|
+
|
|
364
|
+
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.
|
|
365
|
+
|
|
366
|
+
`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.
|
|
367
|
+
|
|
368
|
+
```typescript
|
|
369
|
+
import { claudeSetup } from '@cogitator-ai/bridge';
|
|
370
|
+
|
|
371
|
+
const setup = claudeSetup({
|
|
372
|
+
toolsServer: { command: 'cogitator', args: ['bridge', 'mcp'] },
|
|
373
|
+
});
|
|
374
|
+
const steps = await setup.install({
|
|
375
|
+
project: process.cwd(),
|
|
376
|
+
scope: 'project',
|
|
377
|
+
notes: true,
|
|
378
|
+
takeJobs: false,
|
|
379
|
+
allowTools: true,
|
|
380
|
+
});
|
|
381
|
+
for (const step of steps) console.log(step.title, step.lines);
|
|
382
|
+
```
|
|
383
|
+
|
|
384
|
+
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.
|
|
385
|
+
|
|
252
386
|
## Adapters
|
|
253
387
|
|
|
254
388
|
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:
|
|
@@ -293,6 +427,7 @@ const host = await hostBridge({ adapters: [adapter] });
|
|
|
293
427
|
| `deliver` | Hands a letter to a session. Leave it out when the sessions wait for their mail themselves, as Claude Code's do |
|
|
294
428
|
| `createSession` | Starts a session for a job, and may hand it the first letter while it does |
|
|
295
429
|
| `identify` | Tells which session a process belongs to, from its environment or from what the harness wrote to its hook |
|
|
430
|
+
| `toolCallHook` | Answers the hook a harness runs before a bridge tool call, so the call carries the session that makes it |
|
|
296
431
|
| `liveSessions` | Lists the sessions that run, so the bridge knows a closed one from a quiet one |
|
|
297
432
|
| `health` | What `cogitator bridge doctor` shows: versions, the commands the bridge needs, each with what to do about it |
|
|
298
433
|
| `attach` | Gets the calls the adapter's own sessions make, such as to report |
|
|
@@ -300,7 +435,7 @@ const host = await hostBridge({ adapters: [adapter] });
|
|
|
300
435
|
|
|
301
436
|
`deliver` may return `{ note }`: something a person should know about the delivery, kept in the journal.
|
|
302
437
|
|
|
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.
|
|
438
|
+
`@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.
|
|
304
439
|
|
|
305
440
|
```typescript
|
|
306
441
|
import { adapterConformanceCases } from '@cogitator-ai/bridge/testing';
|
|
@@ -312,11 +447,11 @@ for (const conformance of adapterConformanceCases(target)) {
|
|
|
312
447
|
|
|
313
448
|
## Trust
|
|
314
449
|
|
|
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.
|
|
450
|
+
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. A permission request is judged by the settings files of the job's project as they are on disk when it is asked. An answer of the person comes over the socket from a connection that named no session: the command line refuses to answer for the person from inside a session of an agent, which keeps an agent from doing so by accident and does not stop a process that hides what it is. A Telegram chat is as private as the token of its bot. 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.
|
|
316
451
|
|
|
317
452
|
## Errors
|
|
318
453
|
|
|
319
|
-
Every refusal is a `BridgeError` with a `code` to branch on and a message written for the agent that gets it: `not_registered`, `unknown_agent`, `ambiguous_agent`, `no_session`, `unknown_job`, `unknown_letter`, `not_a_party`, `job_finished`, `invalid_letter`, `invalid_input`, `depth_exceeded`, `budget_exhausted`, `loop_detected`, `already_running`, `not_running`, `storage`.
|
|
454
|
+
Every refusal is a `BridgeError` with a `code` to branch on and a message written for the agent that gets it: `not_registered`, `unknown_agent`, `ambiguous_agent`, `no_session`, `unknown_job`, `unknown_letter`, `not_a_party`, `job_finished`, `invalid_letter`, `invalid_input`, `depth_exceeded`, `budget_exhausted`, `loop_detected`, `needs_person`, `no_person`, `already_running`, `not_running`, `storage`.
|
|
320
455
|
|
|
321
456
|
## Documentation
|
|
322
457
|
|
package/dist/adapter.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import type { CreateJobInput, CreateJobResult, InboxInput, SendLetterInput, SendLetterResult } from './inputs.js';
|
|
1
|
+
import type { CreateJobInput, CreateJobResult, InboxInput, SendLetterInput, SendLetterResult, VerdictInput, VerdictResult } from './inputs.js';
|
|
2
2
|
import type { LetterFilter } from './store/store.js';
|
|
3
3
|
import type { AdapterCapabilities, AgentRecord, BridgeJob, CallerIdentity, Letter, RenderedLetter } from './types.js';
|
|
4
4
|
/** A letter on its way to a session, as an adapter gets it. */
|
|
@@ -71,6 +71,7 @@ export interface BridgeCalls {
|
|
|
71
71
|
register(identity: CallerIdentity): Promise<AgentRecord>;
|
|
72
72
|
createJob(caller: string, input: CreateJobInput): Promise<CreateJobResult>;
|
|
73
73
|
send(caller: string, input: SendLetterInput): Promise<SendLetterResult>;
|
|
74
|
+
verdict(caller: string, input: VerdictInput, signal?: AbortSignal): Promise<VerdictResult>;
|
|
74
75
|
inbox(caller: string, input?: InboxInput): Promise<RenderedLetter[]>;
|
|
75
76
|
acknowledge(caller: string, letterId: string): Promise<Letter>;
|
|
76
77
|
cancel(caller: string, job: number, reason?: string): Promise<BridgeJob>;
|
|
@@ -107,6 +108,13 @@ export interface BridgeAdapter {
|
|
|
107
108
|
* the variables of the harnesses the bridge knows
|
|
108
109
|
*/
|
|
109
110
|
identify?(context: IdentifyContext): CallerIdentity | undefined;
|
|
111
|
+
/**
|
|
112
|
+
* What a hook of the harness answers before a call of a bridge tool, so the call carries the
|
|
113
|
+
* session that makes it: the harness then hands the tool the arguments with the hint in them
|
|
114
|
+
* (`TOOL_CALL_HINT_KEY`). Undefined when the hook's input names no session, and the call goes
|
|
115
|
+
* on as it was. For a harness whose server of tools outlives its sessions
|
|
116
|
+
*/
|
|
117
|
+
toolCallHook?(context: IdentifyContext): string | undefined;
|
|
110
118
|
/**
|
|
111
119
|
* The sessions of the harness running on this machine, when the harness can list them. The
|
|
112
120
|
* bridge keeps a listed session in its address book however long it is silent, and takes one
|
package/dist/adapter.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EACd,eAAe,EACf,UAAU,EACV,eAAe,EACf,gBAAgB,
|
|
1
|
+
{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EACd,eAAe,EACf,UAAU,EACV,eAAe,EACf,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACd,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,KAAK,EACV,mBAAmB,EACnB,WAAW,EACX,SAAS,EACT,cAAc,EACd,MAAM,EACN,cAAc,EACf,MAAM,YAAY,CAAC;AAEpB,+DAA+D;AAC/D,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,WAAW,CAAC;IACnB,MAAM,EAAE,cAAc,CAAC;IACvB,GAAG,EAAE,SAAS,CAAC;CAChB;AAED,+EAA+E;AAC/E,MAAM,WAAW,eAAe;IAC9B,4FAA4F;IAC5F,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,0EAA0E;AAC1E,MAAM,WAAW,cAAc;IAC7B,sFAAsF;IACtF,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,GAAG,EAAE,SAAS,CAAC;IACf,kGAAkG;IAClG,WAAW,EAAE,cAAc,CAAC;CAC7B;AAED,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qGAAqG;IACrG,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC;AAED,2FAA2F;AAC3F,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8BAA8B;IAC9B,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,8GAA8G;AAC9G,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IACvB,uDAAuD;IACvD,GAAG,EAAE,MAAM,CAAC;IACZ,kEAAkE;IAClE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,YAAY,GAAG,IAAI,GAAG,MAAM,GAAG,MAAM,CAAC;AAElD,qDAAqD;AACrD,MAAM,WAAW,WAAW;IAC1B,yEAAyE;IACzE,EAAE,EAAE,MAAM,CAAC;IACX,yCAAyC;IACzC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,YAAY,CAAC;IACrB,qBAAqB;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0EAA0E;IAC1E,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,aAAa;IAC5B,0DAA0D;IAC1D,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,QAAQ,EAAE,cAAc,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IACzD,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IAC3E,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IACxE,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAC3F,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;IACrE,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC/D,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IACzE,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IACxC,OAAO,CAAC,MAAM,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;CACnD;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,+EAA+E;IAC/E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,kFAAkF;IAClF,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,YAAY,EAAE,mBAAmB,CAAC;IAC3C;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;IAChC;;;;OAIG;IACH,OAAO,CAAC,CAAC,QAAQ,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAAC;IACpE,oFAAoF;IACpF,aAAa,CAAC,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IACjE;;;;OAIG;IACH,QAAQ,CAAC,CAAC,OAAO,EAAE,eAAe,GAAG,cAAc,GAAG,SAAS,CAAC;IAChE;;;;;OAKG;IACH,YAAY,CAAC,CAAC,OAAO,EAAE,eAAe,GAAG,MAAM,GAAG,SAAS,CAAC;IAC5D;;;;OAIG;IACH,YAAY,CAAC,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;IACxC,oGAAoG;IACpG,MAAM,CAAC,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;IACxD,gGAAgG;IAChG,MAAM,CAAC,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAAC;IACnC,oEAAoE;IACpE,KAAK,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACzB"}
|
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import type { BridgeAdapter } from '../adapter.js';
|
|
2
|
+
import { type ToolsServerCommand } from './tools-server.js';
|
|
2
3
|
/** How letters reach a Claude Code session: a hook of the session waits for them. */
|
|
3
4
|
export declare const CLAUDE_DELIVERY = "hook";
|
|
4
5
|
/** How long a waiter of a Claude Code session waits before Claude Code ends it, 12 hours. */
|
|
@@ -12,6 +13,8 @@ export interface ClaudeWaitHookOptions {
|
|
|
12
13
|
agentName?: string;
|
|
13
14
|
/** The folder of the bridge's files, when it is not the default one */
|
|
14
15
|
bridgeHome?: string;
|
|
16
|
+
/** Whether the session has the bridge's tools: the waiter then says to answer with them */
|
|
17
|
+
tools?: boolean;
|
|
15
18
|
}
|
|
16
19
|
export interface ClaudeHookSettings {
|
|
17
20
|
hooks: {
|
|
@@ -38,6 +41,52 @@ export declare function claudeWaitCommand(options?: ClaudeWaitHookOptions): stri
|
|
|
38
41
|
export declare function claudeWaitHook(options?: ClaudeWaitHookOptions): ClaudeHookSettings;
|
|
39
42
|
/** Whether Claude Code settings hold a hook that waits at the bridge. */
|
|
40
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;
|
|
41
90
|
export type ClaudeTrust = 'trusted' | 'untrusted' | 'unknown';
|
|
42
91
|
/**
|
|
43
92
|
* Whether Claude Code trusts a folder, read from where it records that a person accepted its
|
|
@@ -76,6 +125,12 @@ export interface ClaudeCodeAdapterOptions {
|
|
|
76
125
|
userSettingsPath?: string;
|
|
77
126
|
/** How long a started session may take to show up among the running ones, 30 s by default */
|
|
78
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;
|
|
79
134
|
}
|
|
80
135
|
/**
|
|
81
136
|
* Reaches Claude Code sessions in their own windows. A session started for a job runs in the
|
|
@@ -1 +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;
|
|
1
|
+
{"version":3,"file":"claude.d.ts","sourceRoot":"","sources":["../../src/adapters/claude.ts"],"names":[],"mappings":"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"}
|