@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.
Files changed (81) hide show
  1. package/README.md +72 -23
  2. package/dist/adapter.d.ts +2 -1
  3. package/dist/adapter.d.ts.map +1 -1
  4. package/dist/adapters/hosted.d.ts +36 -4
  5. package/dist/adapters/hosted.d.ts.map +1 -1
  6. package/dist/adapters/hosted.js +188 -9
  7. package/dist/adapters/hosted.js.map +1 -1
  8. package/dist/client.d.ts +16 -1
  9. package/dist/client.d.ts.map +1 -1
  10. package/dist/client.js +24 -1
  11. package/dist/client.js.map +1 -1
  12. package/dist/dispatcher.d.ts +113 -3
  13. package/dist/dispatcher.d.ts.map +1 -1
  14. package/dist/dispatcher.js +493 -23
  15. package/dist/dispatcher.js.map +1 -1
  16. package/dist/errors.d.ts +1 -1
  17. package/dist/errors.d.ts.map +1 -1
  18. package/dist/errors.js.map +1 -1
  19. package/dist/guards.d.ts +3 -2
  20. package/dist/guards.d.ts.map +1 -1
  21. package/dist/guards.js +4 -3
  22. package/dist/guards.js.map +1 -1
  23. package/dist/host.d.ts +9 -0
  24. package/dist/host.d.ts.map +1 -1
  25. package/dist/host.js +2 -0
  26. package/dist/host.js.map +1 -1
  27. package/dist/index.d.ts +11 -5
  28. package/dist/index.d.ts.map +1 -1
  29. package/dist/index.js +6 -3
  30. package/dist/index.js.map +1 -1
  31. package/dist/inputs.d.ts +76 -1
  32. package/dist/inputs.d.ts.map +1 -1
  33. package/dist/inputs.js +31 -1
  34. package/dist/inputs.js.map +1 -1
  35. package/dist/job-record.d.ts +1 -0
  36. package/dist/job-record.d.ts.map +1 -1
  37. package/dist/job-record.js +1 -0
  38. package/dist/job-record.js.map +1 -1
  39. package/dist/letters.d.ts.map +1 -1
  40. package/dist/letters.js +23 -1
  41. package/dist/letters.js.map +1 -1
  42. package/dist/person-channel.d.ts +45 -0
  43. package/dist/person-channel.d.ts.map +1 -0
  44. package/dist/person-channel.js +154 -0
  45. package/dist/person-channel.js.map +1 -0
  46. package/dist/person-inbox.d.ts +30 -0
  47. package/dist/person-inbox.d.ts.map +1 -0
  48. package/dist/person-inbox.js +60 -0
  49. package/dist/person-inbox.js.map +1 -0
  50. package/dist/person.d.ts +52 -0
  51. package/dist/person.d.ts.map +1 -0
  52. package/dist/person.js +30 -0
  53. package/dist/person.js.map +1 -0
  54. package/dist/protocol.d.ts +6 -1
  55. package/dist/protocol.d.ts.map +1 -1
  56. package/dist/protocol.js +5 -1
  57. package/dist/protocol.js.map +1 -1
  58. package/dist/rights/index.d.ts +36 -0
  59. package/dist/rights/index.d.ts.map +1 -0
  60. package/dist/rights/index.js +186 -0
  61. package/dist/rights/index.js.map +1 -0
  62. package/dist/server.d.ts.map +1 -1
  63. package/dist/server.js +9 -0
  64. package/dist/server.js.map +1 -1
  65. package/dist/store/sqlite.d.ts +6 -1
  66. package/dist/store/sqlite.d.ts.map +1 -1
  67. package/dist/store/sqlite.js +74 -18
  68. package/dist/store/sqlite.js.map +1 -1
  69. package/dist/store/store.d.ts +6 -2
  70. package/dist/store/store.d.ts.map +1 -1
  71. package/dist/tools/guidance.d.ts.map +1 -1
  72. package/dist/tools/guidance.js +1 -0
  73. package/dist/tools/guidance.js.map +1 -1
  74. package/dist/tools/tools.d.ts.map +1 -1
  75. package/dist/tools/tools.js +27 -4
  76. package/dist/tools/tools.js.map +1 -1
  77. package/dist/types.d.ts +81 -1
  78. package/dist/types.d.ts.map +1 -1
  79. package/dist/types.js +29 -0
  80. package/dist/types.js.map +1 -1
  81. 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 to do something |
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`. 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:
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>;
@@ -1 +1 @@
1
- {"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"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"}
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 run that
92
- * pauses for an approval or for a question of a tool fails its job: its answer is not a report.
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 refused, since no person sits at a session the bridge started
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":"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"}
1
+ {"version":3,"file":"hosted.d.ts","sourceRoot":"","sources":["../../src/adapters/hosted.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC/D,OAAO,KAAK,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AACrF,OAAO,KAAK,EACV,aAAa,EAMd,MAAM,eAAe,CAAC;AAKvB,OAAO,KAAK,EAAE,SAAS,EAAwB,aAAa,EAAkB,MAAM,aAAa,CAAC;AAElG,iGAAiG;AACjG,eAAO,MAAM,eAAe,WAAW,CAAC;AAExC,0CAA0C;AAC1C,MAAM,WAAW,UAAU;IACzB,8EAA8E;IAC9E,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IACjC,qFAAqF;IACrF,KAAK,CAAC,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAC9B,6FAA6F;IAC7F,QAAQ,CAAC,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IACjC,qBAAqB;IACrB,KAAK,CAAC,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CAChC;AAED,kCAAkC;AAClC,MAAM,WAAW,iBAAiB;IAChC,0EAA0E;IAC1E,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB;;;;;OAKG;IACH,OAAO,CAAC,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;CACvE;AAED,uEAAuE;AACvE,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,UAAU,CAAC;IAC5D,KAAK,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACzB;AAED,2CAA2C;AAC3C,MAAM,WAAW,oBAAoB;IACnC,0CAA0C;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,+CAA+C;IAC/C,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,gCAAgC;IAChC,GAAG,EAAE,SAAS,CAAC;CAChB;AAED,MAAM,MAAM,iBAAiB,GAAG,CAC9B,OAAO,EAAE,oBAAoB,KAC1B,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;AAE5C,MAAM,WAAW,oBAAoB;IACnC,4EAA4E;IAC5E,OAAO,EAAE,MAAM,CAAC;IAChB,gCAAgC;IAChC,IAAI,EAAE,iBAAiB,CAAC;IACxB,4FAA4F;IAC5F,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,0FAA0F;IAC1F,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACjC,+FAA+F;IAC/F,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,mBAAmB,EAAE,OAAO,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,KAAK,aAAa,CAAC;CACnF;AA6ED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,IAAI,CAAC,mBAAmB,EAAE,UAAU,GAAG,WAAW,CAAC,EAC5D,OAAO,EAAE;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,GACvB,aAAa,CAmCf;AA4CD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,aAAa,CAuQ1E;AAED,0FAA0F;AAC1F,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,GAAG,QAAQ,CAAA;KAAE,CAAC,CAAC;IAC9E,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;IACnC,KAAK,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC;CAClC;AASD,2EAA2E;AAC3E,MAAM,WAAW,aAAa,CAAC,MAAM;IACnC,KAAK,CACH,KAAK,EAAE,MAAM,EACb,OAAO,EAAE;QACP,KAAK,EAAE,MAAM,CAAC;QACd,QAAQ,EAAE,MAAM,CAAC;QACjB,2EAA2E;QAC3E,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,mBAAmB,KAAK,OAAO,CAAC,oBAAoB,GAAG,OAAO,CAAC,CAAC;KACxF,GACA,SAAS,CAAC;CACd;AAED,MAAM,WAAW,wBAAwB,CAAC,MAAM;IAC9C,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC/B,sEAAsE;IACtE,KAAK,EAAE,MAAM,GAAG,CAAC,CAAC,OAAO,EAAE,oBAAoB,KAAK,MAAM,CAAC,CAAC;CAC7D;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EACtC,OAAO,EAAE,wBAAwB,CAAC,MAAM,CAAC,GACxC,iBAAiB,CA8BnB;AAED,2GAA2G;AAC3G,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,SAAS;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC1D,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACrD,YAAY,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5D,cAAc,IAAI,sBAAsB,CAAC;IACzC,iBAAiB,CAAC,IAAI,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/D,IAAI,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,CAAC;IAC/B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,sFAAsF;IACtF,UAAU,CAAC,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,oBAAoB,GAAG,OAAO,CAAC,CAAC;CACpF;AAED,MAAM,MAAM,sBAAsB,GAChC,SAAS,GAAG,aAAa,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,mBAAmB,CAAC;AAEhF,qFAAqF;AACrF,MAAM,WAAW,YAAY;IAC3B,OAAO,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IAC5E,KAAK,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACzB;AAED,MAAM,WAAW,uBAAuB;IACtC;;;;OAIG;IACH,QAAQ,EACN,YAAY,GAAG,CAAC,CAAC,OAAO,EAAE,oBAAoB,KAAK,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC;IAC3F;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,cAAc,CAAC,EAAE,sBAAsB,CAAC;CACzC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,iBAAiB,CAyDpF"}
@@ -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, job === undefined ? {} : { job: mail.job });
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
- const running = { turn, ...(job !== undefined && { job }) };
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 approval or an answer, which nobody gives in a hosted session. ' +
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 run that
251
- * pauses for an approval or for a question of a tool fails its job: its answer is not a report.
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 run = options.runtime.start(agent, { input: text, threadId });
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)