@cogitator-ai/bridge 0.4.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 +72 -23
- package/dist/adapter.d.ts +2 -1
- package/dist/adapter.d.ts.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/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 +113 -3
- package/dist/dispatcher.d.ts.map +1 -1
- package/dist/dispatcher.js +493 -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 +11 -5
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +6 -3
- 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/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/tools/guidance.d.ts.map +1 -1
- package/dist/tools/guidance.js +1 -0
- package/dist/tools/guidance.js.map +1 -1
- package/dist/tools/tools.d.ts.map +1 -1
- package/dist/tools/tools.js +27 -4
- package/dist/tools/tools.js.map +1 -1
- 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/package.json +6 -1
package/README.md
CHANGED
|
@@ -24,6 +24,7 @@ cogitator bridge status # the dispatcher, the sessions it knows, the job
|
|
|
24
24
|
cogitator bridge log --follow # every letter as it goes
|
|
25
25
|
cogitator bridge log --job 12 # everything about one job
|
|
26
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
|
|
27
28
|
```
|
|
28
29
|
|
|
29
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.
|
|
@@ -50,18 +51,18 @@ What names a path of this machine goes where only you have it, never into a file
|
|
|
50
51
|
|
|
51
52
|
### The tools
|
|
52
53
|
|
|
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
|
|
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 |
|
|
65
66
|
|
|
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.
|
|
67
68
|
|
|
@@ -171,14 +172,14 @@ A job also carries who handed it over and who carries it out, the project and th
|
|
|
171
172
|
|
|
172
173
|
## Letters
|
|
173
174
|
|
|
174
|
-
| Kind | Sent by | Effect
|
|
175
|
-
| ------------ | ---------------- |
|
|
176
|
-
| `task` | `createJob` | The job itself
|
|
177
|
-
| `question` | either side | Needs an `answer`. From the one doing the job it puts the job on hold
|
|
178
|
-
| `permission` | either side | A question that asks for leave
|
|
179
|
-
| `answer` | the one asked | Answers a question, and resumes the job once none is open
|
|
180
|
-
| `report` | the one doing it | Ends the job, `outcome: 'completed'` (default) or `'failed'`
|
|
181
|
-
| `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 |
|
|
182
183
|
|
|
183
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.
|
|
184
185
|
|
|
@@ -188,6 +189,53 @@ A letter is text: one with a NUL character in it is refused, since no harness ca
|
|
|
188
189
|
|
|
189
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.
|
|
190
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
|
+
|
|
191
239
|
## Who a letter is for
|
|
192
240
|
|
|
193
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:
|
|
@@ -218,6 +266,7 @@ Each number is a default that `hostBridge({ limits })` changes.
|
|
|
218
266
|
| Sessions starting | 2 | No more sessions are started at once |
|
|
219
267
|
| Silence | 12 hours | A session with no job in progress is taken for gone, unless its harness lists it or its hook waits |
|
|
220
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 |
|
|
221
270
|
| Delivery | 5 attempts | Retried with a growing wait, then left for the inbox |
|
|
222
271
|
|
|
223
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.
|
|
@@ -268,7 +317,7 @@ const host = await hostBridge({
|
|
|
268
317
|
|
|
269
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.
|
|
270
319
|
|
|
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`.
|
|
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:
|
|
272
321
|
|
|
273
322
|
```typescript
|
|
274
323
|
import { AcpAgentProvider, resolveAcpAgent } from '@cogitator-ai/acp';
|
|
@@ -398,11 +447,11 @@ for (const conformance of adapterConformanceCases(target)) {
|
|
|
398
447
|
|
|
399
448
|
## Trust
|
|
400
449
|
|
|
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.
|
|
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.
|
|
402
451
|
|
|
403
452
|
## Errors
|
|
404
453
|
|
|
405
|
-
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`.
|
|
406
455
|
|
|
407
456
|
## Documentation
|
|
408
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>;
|
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":"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"}
|
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import type { StreamEvent } from '@cogitator-ai/server-shared';
|
|
2
|
+
import type { ToolApprovalDecision, ToolApprovalRequest } from '@cogitator-ai/types';
|
|
2
3
|
import type { BridgeAdapter } from '../adapter.js';
|
|
3
|
-
import type { BridgeJob } from '../types.js';
|
|
4
|
+
import type { BridgeJob, PermissionAsk } from '../types.js';
|
|
4
5
|
/** How letters reach a session the host runs itself: handed to its agent in the same process. */
|
|
5
6
|
export declare const HOSTED_DELIVERY = "hosted";
|
|
6
7
|
/** One turn of an agent the host runs. */
|
|
@@ -18,6 +19,13 @@ export interface HostedTurn {
|
|
|
18
19
|
export interface HostedTurnContext {
|
|
19
20
|
/** The job the turn carries out, when the job's first letter starts it */
|
|
20
21
|
job?: BridgeJob;
|
|
22
|
+
/**
|
|
23
|
+
* Asks leave for a tool call the agent's own rules do not settle: the bridge takes the request
|
|
24
|
+
* to whoever may answer it, the agent that handed the job over or the person, and resolves
|
|
25
|
+
* with their answer. Nobody sits at a hosted session, so this is the only way such a call is
|
|
26
|
+
* ever allowed
|
|
27
|
+
*/
|
|
28
|
+
approve?(request: ToolApprovalRequest): Promise<ToolApprovalDecision>;
|
|
21
29
|
}
|
|
22
30
|
/** A session of an agent the host runs. One turn goes on at a time. */
|
|
23
31
|
export interface HostedSession {
|
|
@@ -47,7 +55,25 @@ export interface HostedAdapterOptions {
|
|
|
47
55
|
onError?: (error: Error) => void;
|
|
48
56
|
/** How long a turn that was told to stop is waited for when the host closes, 5 s by default */
|
|
49
57
|
stopGraceMs?: number;
|
|
58
|
+
/**
|
|
59
|
+
* Says what a tool call an agent asks leave for touches, so the rules of the agent that handed
|
|
60
|
+
* the job over can judge it. `permissionAskOf` by default, which knows the tools of the
|
|
61
|
+
* Cogitator runtime and of ACP agents by name
|
|
62
|
+
*/
|
|
63
|
+
askOf?: (request: ToolApprovalRequest, session: {
|
|
64
|
+
cwd: string;
|
|
65
|
+
}) => PermissionAsk;
|
|
50
66
|
}
|
|
67
|
+
/**
|
|
68
|
+
* What a tool call touches, read from the name of its tool and its arguments: the tools of the
|
|
69
|
+
* Cogitator runtime and the names `AcpAgentProvider` gives the calls of an ACP agent. A command
|
|
70
|
+
* carries the environment it sets for itself, which the rules judge with it. A call it cannot
|
|
71
|
+
* read is known by the name of its tool alone, which leaves it to the person unless a rule names
|
|
72
|
+
* that tool.
|
|
73
|
+
*/
|
|
74
|
+
export declare function permissionAskOf(request: Pick<ToolApprovalRequest, 'toolName' | 'arguments'>, session: {
|
|
75
|
+
cwd: string;
|
|
76
|
+
}): PermissionAsk;
|
|
51
77
|
/**
|
|
52
78
|
* Runs the sessions of a harness inside the host: agents of the Cogitator runtime on any model
|
|
53
79
|
* (`cogitatorSessions`), agents behind the Agent Client Protocol (`providerSessions`), or
|
|
@@ -78,6 +104,8 @@ export interface HostedRuntime<TAgent> {
|
|
|
78
104
|
start(agent: TAgent, options: {
|
|
79
105
|
input: string;
|
|
80
106
|
threadId: string;
|
|
107
|
+
/** Asked for every tool call the agent's permission rules do not settle */
|
|
108
|
+
onApproval?: (request: ToolApprovalRequest) => Promise<ToolApprovalDecision | 'pause'>;
|
|
81
109
|
}): HostedRun;
|
|
82
110
|
}
|
|
83
111
|
export interface CogitatorSessionsOptions<TAgent> {
|
|
@@ -88,8 +116,10 @@ export interface CogitatorSessionsOptions<TAgent> {
|
|
|
88
116
|
/**
|
|
89
117
|
* Sessions of an agent of the Cogitator runtime, on whatever model the agent names: every turn
|
|
90
118
|
* is a run on the session's own thread, so with memory configured the agent remembers the
|
|
91
|
-
* turns before. A letter that arrives during a run steers it or follows it up. A
|
|
92
|
-
*
|
|
119
|
+
* turns before. A letter that arrives during a run steers it or follows it up. A tool call the
|
|
120
|
+
* agent's permission rules leave open is taken to the bridge: the agent that handed the job over
|
|
121
|
+
* answers within its own rights, the person for the rest. A run that pauses for a question of a
|
|
122
|
+
* tool fails its job: its answer is not a report.
|
|
93
123
|
*
|
|
94
124
|
* @example
|
|
95
125
|
* ```ts
|
|
@@ -115,6 +145,8 @@ export interface ProviderTurn {
|
|
|
115
145
|
setPermissionMode(mode: ProviderPermissionMode): Promise<void>;
|
|
116
146
|
emit(event: StreamEvent): void;
|
|
117
147
|
readonly signal: AbortSignal;
|
|
148
|
+
/** Asked for every call of the agent the provider's permission rules do not settle */
|
|
149
|
+
onApproval?(request: ToolApprovalRequest): Promise<ToolApprovalDecision | 'pause'>;
|
|
118
150
|
}
|
|
119
151
|
export type ProviderPermissionMode = 'default' | 'acceptEdits' | 'plan' | 'auto' | 'dontAsk' | 'bypassPermissions';
|
|
120
152
|
/** An agent that runs outside the runtime, turn by turn. `AcpAgentProvider` fits. */
|
|
@@ -139,7 +171,7 @@ export interface ProviderSessionsOptions {
|
|
|
139
171
|
root?: string;
|
|
140
172
|
/**
|
|
141
173
|
* The permission mode of every turn, `default` when absent: what the provider's rules do not
|
|
142
|
-
* settle is
|
|
174
|
+
* settle is taken to the bridge, which asks the agent that handed the job over or the person
|
|
143
175
|
*/
|
|
144
176
|
permissionMode?: ProviderPermissionMode;
|
|
145
177
|
}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"hosted.d.ts","sourceRoot":"","sources":["../../src/adapters/hosted.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"hosted.d.ts","sourceRoot":"","sources":["../../src/adapters/hosted.ts"],"names":[],"mappings":"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"}
|
package/dist/adapters/hosted.js
CHANGED
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
import { randomUUID } from 'node:crypto';
|
|
2
|
+
import { resolve } from 'node:path';
|
|
2
3
|
import { isBridgeError } from '../errors.js';
|
|
3
4
|
import { pause } from './exec.js';
|
|
5
|
+
import { oneLine } from '../letters.js';
|
|
4
6
|
import { isInside } from '../paths.js';
|
|
5
7
|
/** How letters reach a session the host runs itself: handed to its agent in the same process. */
|
|
6
8
|
export const HOSTED_DELIVERY = 'hosted';
|
|
@@ -8,6 +10,121 @@ const DEFAULT_STOP_GRACE_MS = 5_000;
|
|
|
8
10
|
const FINISHED = ['completed', 'failed', 'canceled'];
|
|
9
11
|
/** Letters an agent wants in the middle of its work, when its turn can take them. */
|
|
10
12
|
const STEERED = ['answer', 'permission', 'note'];
|
|
13
|
+
/** How long one look for the verdict of a permission request waits before it looks again. */
|
|
14
|
+
const VERDICT_POLL_MS = 60_000;
|
|
15
|
+
/**
|
|
16
|
+
* The pause before the next look when a look came back at once without a verdict, as from a
|
|
17
|
+
* dispatcher that is closing: the wait must not turn into a loop that never rests.
|
|
18
|
+
*/
|
|
19
|
+
const VERDICT_RETRY_MS = 250;
|
|
20
|
+
/** How much of a call's arguments the letter that asks leave for it shows. */
|
|
21
|
+
const ARGUMENTS_SHOWN = 2_000;
|
|
22
|
+
const COMMAND_TOOLS = new Set(['run_command', 'exec', 'bash', 'shell']);
|
|
23
|
+
const READ_TOOLS = new Set([
|
|
24
|
+
'read_file',
|
|
25
|
+
'file_read',
|
|
26
|
+
'list_files',
|
|
27
|
+
'file_list',
|
|
28
|
+
'glob',
|
|
29
|
+
'grep',
|
|
30
|
+
]);
|
|
31
|
+
const EDIT_TOOLS = new Set([
|
|
32
|
+
'edit_file',
|
|
33
|
+
'file_edit',
|
|
34
|
+
'write_file',
|
|
35
|
+
'file_write',
|
|
36
|
+
'delete_file',
|
|
37
|
+
'file_delete',
|
|
38
|
+
'move_file',
|
|
39
|
+
]);
|
|
40
|
+
const FETCH_TOOLS = new Set(['web_fetch', 'fetch']);
|
|
41
|
+
function textOf(value) {
|
|
42
|
+
return typeof value === 'string' && value.trim() !== '' ? value : undefined;
|
|
43
|
+
}
|
|
44
|
+
/**
|
|
45
|
+
* The environment a command sets for itself, as an object of strings or a list of names and
|
|
46
|
+
* values. A command whose environment cannot be read is not one the rules can judge: a variable
|
|
47
|
+
* may change what the command does.
|
|
48
|
+
*/
|
|
49
|
+
function envOf(value) {
|
|
50
|
+
if (value === undefined || value === null)
|
|
51
|
+
return undefined;
|
|
52
|
+
const entries = Array.isArray(value)
|
|
53
|
+
? value.map((entry) => entry !== null && typeof entry === 'object'
|
|
54
|
+
? [entry.name, entry.value]
|
|
55
|
+
: [undefined, undefined])
|
|
56
|
+
: typeof value === 'object'
|
|
57
|
+
? Object.entries(value)
|
|
58
|
+
: [[undefined, undefined]];
|
|
59
|
+
const read = {};
|
|
60
|
+
for (const [name, set] of entries) {
|
|
61
|
+
if (typeof name !== 'string' || name === '' || typeof set !== 'string')
|
|
62
|
+
return 'unreadable';
|
|
63
|
+
read[name] = set;
|
|
64
|
+
}
|
|
65
|
+
return Object.keys(read).length > 0 ? read : undefined;
|
|
66
|
+
}
|
|
67
|
+
/**
|
|
68
|
+
* What a tool call touches, read from the name of its tool and its arguments: the tools of the
|
|
69
|
+
* Cogitator runtime and the names `AcpAgentProvider` gives the calls of an ACP agent. A command
|
|
70
|
+
* carries the environment it sets for itself, which the rules judge with it. A call it cannot
|
|
71
|
+
* read is known by the name of its tool alone, which leaves it to the person unless a rule names
|
|
72
|
+
* that tool.
|
|
73
|
+
*/
|
|
74
|
+
export function permissionAskOf(request, session) {
|
|
75
|
+
const args = request.arguments;
|
|
76
|
+
const tool = oneLine(request.toolName).slice(0, 256) || 'tool';
|
|
77
|
+
const absolute = (path) => resolve(session.cwd, path);
|
|
78
|
+
const paths = [args.file_path, args.path, args.filePath, args.notebook_path]
|
|
79
|
+
.map(textOf)
|
|
80
|
+
.filter((path) => path !== undefined);
|
|
81
|
+
if (Array.isArray(args.paths)) {
|
|
82
|
+
paths.push(...args.paths.map(textOf).filter((path) => path !== undefined));
|
|
83
|
+
}
|
|
84
|
+
if (COMMAND_TOOLS.has(tool)) {
|
|
85
|
+
const command = textOf(args.command);
|
|
86
|
+
const cwd = textOf(args.cwd);
|
|
87
|
+
const env = envOf(args.env);
|
|
88
|
+
if (command && env !== 'unreadable') {
|
|
89
|
+
return {
|
|
90
|
+
tool,
|
|
91
|
+
access: 'command',
|
|
92
|
+
command,
|
|
93
|
+
cwd: absolute(cwd ?? '.'),
|
|
94
|
+
...(env && { env }),
|
|
95
|
+
};
|
|
96
|
+
}
|
|
97
|
+
}
|
|
98
|
+
if (READ_TOOLS.has(tool) && paths.length > 0) {
|
|
99
|
+
return { tool, access: 'read', paths: paths.map(absolute) };
|
|
100
|
+
}
|
|
101
|
+
if (EDIT_TOOLS.has(tool) && paths.length > 0) {
|
|
102
|
+
return { tool, access: 'edit', paths: paths.map(absolute) };
|
|
103
|
+
}
|
|
104
|
+
if (FETCH_TOOLS.has(tool)) {
|
|
105
|
+
const url = textOf(args.url);
|
|
106
|
+
if (url)
|
|
107
|
+
return { tool, access: 'fetch', url };
|
|
108
|
+
}
|
|
109
|
+
return { tool, access: 'other' };
|
|
110
|
+
}
|
|
111
|
+
/** The environment a command sets for itself, in words for a letter: ` with A=1, B=2`. */
|
|
112
|
+
function envWords(env) {
|
|
113
|
+
const set = Object.entries(env ?? {}).map(([name, value]) => `${name}=${value}`);
|
|
114
|
+
return set.length > 0 ? ` with ${set.join(', ')}` : '';
|
|
115
|
+
}
|
|
116
|
+
/** The words of a letter that asks leave for a call: what the agent said of it, then the call. */
|
|
117
|
+
function describeCall(request, ask) {
|
|
118
|
+
const said = request.description.trim();
|
|
119
|
+
const call = ask.access === 'command' && ask.command
|
|
120
|
+
? `Run in ${ask.cwd ?? 'its folder'}${envWords(ask.env)}:\n${ask.command}`
|
|
121
|
+
: ask.access === 'fetch' && ask.url
|
|
122
|
+
? `Fetch ${ask.url}`
|
|
123
|
+
: ask.paths && ask.paths.length > 0
|
|
124
|
+
? `${ask.access === 'edit' ? 'Change' : 'Read'}: ${ask.paths.join(', ')}`
|
|
125
|
+
: `Call ${ask.tool} with ${JSON.stringify(request.arguments).slice(0, ARGUMENTS_SHOWN)}`;
|
|
126
|
+
return said && said !== call ? `${said}\n${call}` : call;
|
|
127
|
+
}
|
|
11
128
|
function asError(error) {
|
|
12
129
|
return error instanceof Error ? error : new Error(String(error));
|
|
13
130
|
}
|
|
@@ -50,13 +167,21 @@ export function hostedAdapter(options) {
|
|
|
50
167
|
let turn;
|
|
51
168
|
const { letter } = mail;
|
|
52
169
|
const job = letter.kind === 'task' ? letter.job : undefined;
|
|
170
|
+
const running = {
|
|
171
|
+
turn: { result: Promise.resolve('') },
|
|
172
|
+
...(job !== undefined && { job }),
|
|
173
|
+
done: false,
|
|
174
|
+
};
|
|
53
175
|
try {
|
|
54
|
-
turn = hosted.session.turn(letter.text,
|
|
176
|
+
turn = hosted.session.turn(letter.text, {
|
|
177
|
+
...(job !== undefined && { job: mail.job }),
|
|
178
|
+
approve: (request) => approve(hosted, running, letter.job, request),
|
|
179
|
+
});
|
|
55
180
|
}
|
|
56
181
|
catch (error) {
|
|
57
182
|
turn = { result: Promise.reject(asError(error)) };
|
|
58
183
|
}
|
|
59
|
-
|
|
184
|
+
running.turn = turn;
|
|
60
185
|
hosted.running = running;
|
|
61
186
|
if (job !== undefined) {
|
|
62
187
|
hosted.waiting = hosted.waiting.filter((held) => held.letter.job !== job || !give(turn, held.letter));
|
|
@@ -71,12 +196,55 @@ export function hostedAdapter(options) {
|
|
|
71
196
|
}
|
|
72
197
|
})
|
|
73
198
|
.finally(() => {
|
|
199
|
+
running.done = true;
|
|
74
200
|
if (hosted.running !== running)
|
|
75
201
|
return;
|
|
76
202
|
delete hosted.running;
|
|
77
203
|
void startNext(hosted);
|
|
78
204
|
});
|
|
79
205
|
}
|
|
206
|
+
/**
|
|
207
|
+
* Takes a call the agent asks leave for to the bridge, as a permission request on the job the
|
|
208
|
+
* turn is about, and waits for the verdict. Whatever goes wrong refuses the call: a request
|
|
209
|
+
* the bridge does not take, a turn that is over, a host that closes.
|
|
210
|
+
*/
|
|
211
|
+
async function approve(hosted, running, job, request) {
|
|
212
|
+
if (!bridge)
|
|
213
|
+
return { approved: false, reason: 'The bridge is not there to ask' };
|
|
214
|
+
const ask = (options.askOf ?? permissionAskOf)(request, { cwd: hosted.cwd });
|
|
215
|
+
let letter;
|
|
216
|
+
try {
|
|
217
|
+
const sent = await bridge.send(hosted.agentName, {
|
|
218
|
+
job,
|
|
219
|
+
kind: 'permission',
|
|
220
|
+
body: describeCall(request, ask),
|
|
221
|
+
ask,
|
|
222
|
+
});
|
|
223
|
+
letter = sent.letter.id;
|
|
224
|
+
}
|
|
225
|
+
catch (error) {
|
|
226
|
+
return { approved: false, reason: asError(error).message };
|
|
227
|
+
}
|
|
228
|
+
while (!closed && !running.done) {
|
|
229
|
+
const asked = Date.now();
|
|
230
|
+
let decision;
|
|
231
|
+
try {
|
|
232
|
+
decision = await bridge.verdict(hosted.agentName, { letter, timeoutMs: VERDICT_POLL_MS });
|
|
233
|
+
}
|
|
234
|
+
catch (error) {
|
|
235
|
+
return { approved: false, reason: asError(error).message };
|
|
236
|
+
}
|
|
237
|
+
if (decision.state === 'waiting') {
|
|
238
|
+
if (Date.now() - asked < VERDICT_RETRY_MS)
|
|
239
|
+
await pause(VERDICT_RETRY_MS);
|
|
240
|
+
continue;
|
|
241
|
+
}
|
|
242
|
+
return decision.verdict === 'allow'
|
|
243
|
+
? { approved: true }
|
|
244
|
+
: { approved: false, reason: `Refused by ${decision.by}: ${decision.reason}` };
|
|
245
|
+
}
|
|
246
|
+
return { approved: false, reason: 'The turn is over' };
|
|
247
|
+
}
|
|
80
248
|
/** Whether the job a letter is about is over: reported on, failed or canceled. */
|
|
81
249
|
async function over(job) {
|
|
82
250
|
if (!bridge)
|
|
@@ -125,8 +293,10 @@ export function hostedAdapter(options) {
|
|
|
125
293
|
const running = hosted.running;
|
|
126
294
|
if (running?.job !== job || !(await over(job)))
|
|
127
295
|
return;
|
|
128
|
-
if (hosted.running === running)
|
|
296
|
+
if (hosted.running === running) {
|
|
297
|
+
running.done = true;
|
|
129
298
|
running.turn.abort?.(new Error(`Job #${job} is over`));
|
|
299
|
+
}
|
|
130
300
|
}
|
|
131
301
|
/** Hands a letter to a turn that goes on. False when the turn does not take it. */
|
|
132
302
|
function give(turn, letter) {
|
|
@@ -227,6 +397,8 @@ export function hostedAdapter(options) {
|
|
|
227
397
|
hosted.waiting.length = 0;
|
|
228
398
|
const turn = hosted.running?.turn;
|
|
229
399
|
if (turn) {
|
|
400
|
+
if (hosted.running)
|
|
401
|
+
hosted.running.done = true;
|
|
230
402
|
turn.abort?.(new Error('The host is closing'));
|
|
231
403
|
await Promise.race([
|
|
232
404
|
turn.result.catch(() => undefined),
|
|
@@ -242,13 +414,14 @@ export function hostedAdapter(options) {
|
|
|
242
414
|
* Why a run that paused fails its job: nothing is finished, and nobody is there to approve a
|
|
243
415
|
* tool call or answer a tool's question in a session the bridge hosts.
|
|
244
416
|
*/
|
|
245
|
-
const PAUSED = 'the run stopped to wait for an
|
|
246
|
-
'Give the agent the permission rules it needs before it starts';
|
|
417
|
+
const PAUSED = 'the run stopped to wait for an answer nobody gives in a hosted session: a question of a tool, or an approval the runtime did not ask the bridge for';
|
|
247
418
|
/**
|
|
248
419
|
* Sessions of an agent of the Cogitator runtime, on whatever model the agent names: every turn
|
|
249
420
|
* is a run on the session's own thread, so with memory configured the agent remembers the
|
|
250
|
-
* turns before. A letter that arrives during a run steers it or follows it up. A
|
|
251
|
-
*
|
|
421
|
+
* turns before. A letter that arrives during a run steers it or follows it up. A tool call the
|
|
422
|
+
* agent's permission rules leave open is taken to the bridge: the agent that handed the job over
|
|
423
|
+
* answers within its own rights, the person for the rest. A run that pauses for a question of a
|
|
424
|
+
* tool fails its job: its answer is not a report.
|
|
252
425
|
*
|
|
253
426
|
* @example
|
|
254
427
|
* ```ts
|
|
@@ -267,8 +440,13 @@ export function cogitatorSessions(options) {
|
|
|
267
440
|
const agent = agentOf(context);
|
|
268
441
|
const threadId = `bridge-${context.sessionId}`;
|
|
269
442
|
return {
|
|
270
|
-
turn(text) {
|
|
271
|
-
const
|
|
443
|
+
turn(text, about) {
|
|
444
|
+
const approve = about?.approve;
|
|
445
|
+
const run = options.runtime.start(agent, {
|
|
446
|
+
input: text,
|
|
447
|
+
threadId,
|
|
448
|
+
...(approve && { onApproval: approve }),
|
|
449
|
+
});
|
|
272
450
|
return {
|
|
273
451
|
result: run.result.then((result) => {
|
|
274
452
|
if (result.status === 'paused')
|
|
@@ -347,6 +525,7 @@ export function providerSessions(options) {
|
|
|
347
525
|
},
|
|
348
526
|
emit: () => undefined,
|
|
349
527
|
signal: stop.signal,
|
|
528
|
+
...(about?.approve && { onApproval: about.approve }),
|
|
350
529
|
})
|
|
351
530
|
.then((answer) => {
|
|
352
531
|
if (answer.refused)
|