@agentrq/acp-gateway 0.2.16 → 0.2.18

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/dist/index.js CHANGED
@@ -72,6 +72,7 @@ import { agentIdentity, describeAgentInfo, sendAgentIdentity, } from "./agentInf
72
72
  import { describeAgents, fetchRegistry, findAgent, hostPlatformTarget, } from "./registry.js";
73
73
  import { extractTaskIdFromMeta, extractTaskIdFromText, } from "./taskIdentity.js";
74
74
  import { extractModels, formatModelsText, setSessionModel, } from "./models.js";
75
+ import { MAX_MAX_CONCURRENCY, MIN_MAX_CONCURRENCY, normalizeConcurrency, sendConcurrencyNotification, } from "./concurrency.js";
75
76
  const lastTaskContent = new Map();
76
77
  // Cancellations are remembered by *where they fall in the stream of events*
77
78
  // rather than as a one-shot flag. agentrq reuses a chat's id as the task id, so
@@ -127,9 +128,97 @@ export const activeSessions = new Map();
127
128
  * agent and two.
128
129
  */
129
130
  let idleSessionInFlight = null;
131
+ /**
132
+ * The turn in progress for each task, so a second delivery waits for it.
133
+ *
134
+ * ACP gives a session one turn at a time, and this gateway gives a task one
135
+ * session — so two deliveries of a task running at once would put two prompts
136
+ * on one session, where the second is refused or interleaves and the streamed
137
+ * output of both lands in a single reply buffer to be flushed twice.
138
+ *
139
+ * Two deliveries of a task is ordinary, not exotic: agentrq reuses a chat's id
140
+ * as the task id, so two messages sent to the same chat arrive as two tasks
141
+ * with one id, and the repetition guard drops neither because it compares text
142
+ * and the two say different things. They must both reach the agent — losing the
143
+ * second would lose what someone typed — so they are serialised rather than
144
+ * deduplicated. A concurrency of 1 used to serialise them by accident; above 1
145
+ * nothing did.
146
+ */
147
+ const taskTurns = new Map();
148
+ /**
149
+ * Runs a task's turn once every earlier turn for that task has finished.
150
+ *
151
+ * A failed turn does not block the next one: a task whose first message errored
152
+ * must still be able to hear the second.
153
+ */
154
+ export async function runTurnForTask(taskId, turn) {
155
+ // Nothing to serialise against. A delivery with no task id is not a second
156
+ // message on anything — there is no chat for it to be the second of.
157
+ if (taskId === undefined)
158
+ return turn();
159
+ const previous = taskTurns.get(taskId);
160
+ if (previous) {
161
+ console.error(`[bridge] Task ${taskId} is already mid-turn; waiting for it rather than ` +
162
+ `prompting the same session twice at once`);
163
+ }
164
+ // `then(turn, turn)` rather than `then(turn)`: the next turn runs whether the
165
+ // one before it succeeded or threw.
166
+ const mine = previous ? previous.then(turn, turn) : turn();
167
+ const settled = mine.catch(() => { });
168
+ taskTurns.set(taskId, settled);
169
+ try {
170
+ await mine;
171
+ }
172
+ finally {
173
+ // Only if nothing has queued behind it, or the chain's tail is dropped and
174
+ // the next delivery starts beside the one still running.
175
+ if (taskTurns.get(taskId) === settled)
176
+ taskTurns.delete(taskId);
177
+ }
178
+ }
179
+ /** Forgets every in-progress turn. For tests. */
180
+ export function resetTaskTurns() {
181
+ taskTurns.clear();
182
+ }
183
+ /**
184
+ * Sessions that have been asked for but do not exist yet, by session key.
185
+ *
186
+ * `activeSessions` only learns about a session once the agent has spawned,
187
+ * handshaken, authenticated and opened it — seconds during which the map says
188
+ * nothing is there. Two deliveries of one task inside that window therefore
189
+ * both missed the cache and both spawned an agent: two processes prompting the
190
+ * same agent for the same task, and only the second reachable afterwards, so
191
+ * the first could never be closed.
192
+ *
193
+ * The workspace can deliver one task twice by pushing it and having it picked
194
+ * up by `getTask` — the repetition guard compares the text, and those two paths
195
+ * word it differently — and a raised concurrency limit is what lets both run at
196
+ * once instead of one after the other.
197
+ */
198
+ const sessionsInFlight = new Map();
199
+ /**
200
+ * Every agent process this gateway has started and not yet seen exit.
201
+ *
202
+ * `activeSessions` holds only the agents that got as far as an open session,
203
+ * which makes it the wrong thing to reap on the way out: an agent that is still
204
+ * handshaking — or one stopped waiting for a login that is never coming — is in
205
+ * no map at all, so shutdown closed nothing and the process was left behind. An
206
+ * agent that quits when its stdin closes gets away with that; one with an event
207
+ * loop of its own, which is exactly the sort that waits for a login, does not.
208
+ *
209
+ * Spawning is the moment to record it, because every window in which a session
210
+ * is not yet tracked begins there.
211
+ */
212
+ const liveAgentProcesses = new Set();
213
+ /** Stops tracking a process that has gone away on its own. */
214
+ function forgetAgentProcess(child) {
215
+ liveAgentProcesses.delete(child);
216
+ }
130
217
  /** Forgets any in-flight startup session. For tests. */
131
218
  export function resetIdleSession() {
132
219
  idleSessionInFlight = null;
220
+ sessionsInFlight.clear();
221
+ liveAgentProcesses.clear();
133
222
  }
134
223
  /** How long to wait for `session/close` RPC before terminating the session process regardless. */
135
224
  export const CLOSE_SESSION_TIMEOUT_MS = 2000;
@@ -186,10 +275,31 @@ export async function closeSession(session, timeoutMs = CLOSE_SESSION_TIMEOUT_MS
186
275
  export async function closeAllSessions(timeoutMs = CLOSE_SESSION_TIMEOUT_MS) {
187
276
  const sessions = Array.from(new Set(activeSessions.values()));
188
277
  activeSessions.clear();
189
- if (sessions.length === 0)
278
+ if (sessions.length > 0) {
279
+ console.error(`[acp] Cleanly closing ${sessions.length} active session(s)...`);
280
+ // Their processes are ended by closeSession; dropping them here keeps the
281
+ // count below honest about what is actually being left behind.
282
+ for (const session of sessions)
283
+ forgetAgentProcess(session.process);
284
+ await Promise.all(sessions.map((session) => closeSession(session, timeoutMs)));
285
+ }
286
+ // Whatever is still running never opened a session, so there is no session to
287
+ // close cleanly and nothing to say goodbye to — only a process to end. This
288
+ // is the agent that is still handshaking, or the one waiting on a login
289
+ // nobody is going to give it.
290
+ const stragglers = Array.from(liveAgentProcesses);
291
+ liveAgentProcesses.clear();
292
+ if (stragglers.length === 0)
190
293
  return;
191
- console.error(`[acp] Cleanly closing ${sessions.length} active session(s)...`);
192
- await Promise.all(sessions.map((session) => closeSession(session, timeoutMs)));
294
+ console.error(`[acp] Ending ${stragglers.length} agent process(es) that never opened a session...`);
295
+ for (const child of stragglers) {
296
+ try {
297
+ terminateAgentProcess(child);
298
+ }
299
+ catch (err) {
300
+ console.error("[acp] Error ending an agent process:", err);
301
+ }
302
+ }
193
303
  }
194
304
  /**
195
305
  * Registers signal handlers (SIGINT, SIGTERM) to trigger graceful shutdown.
@@ -419,13 +529,18 @@ export async function openAgentConnection({ acpCmdArgs, mcpBridge, env, label, t
419
529
  // Guard against unhandled child-process failures. Without these listeners a
420
530
  // crashed agent (e.g. on network loss) leaves a broken stdin pipe; the next
421
531
  // write raises EPIPE as an uncaught error and takes the gateway down with it.
532
+ // Tracked from here rather than from the open session, so shutdown can still
533
+ // end an agent that never reached one — see liveAgentProcesses.
534
+ liveAgentProcesses.add(agentProcess);
422
535
  agentProcess.on("error", (err) => {
423
536
  console.error(`[acp] Agent process error for ${label}:`, err.message);
537
+ forgetAgentProcess(agentProcess);
424
538
  acpClient.cancelPendingPermissions(`agent process for ${label} failed`);
425
539
  onExit?.();
426
540
  });
427
541
  agentProcess.on("exit", (code, signal) => {
428
542
  console.error(`[acp] Agent process for ${label} exited (code=${code}, signal=${signal})`);
543
+ forgetAgentProcess(agentProcess);
429
544
  // Nothing will act on these answers now, but the tool calls waiting on them
430
545
  // are holding task-queue slots that would never be given back.
431
546
  acpClient.cancelPendingPermissions(`agent process for ${label} exited`);
@@ -528,11 +643,36 @@ export class AuthenticationFailed extends Error {
528
643
  }
529
644
  }
530
645
  export async function getOrCreateSession(taskId, acpCmdArgs, configs, agentrqConfig, mcpBridge) {
531
- let sessionKey = taskId || IDLE_SESSION_KEY;
646
+ const sessionKey = taskId || IDLE_SESSION_KEY;
532
647
  const existing = activeSessions.get(sessionKey);
533
648
  if (existing) {
534
649
  return existing;
535
650
  }
651
+ // Someone already asked for this session and is still waiting for it. Join
652
+ // that wait rather than starting a second agent for the same work — the
653
+ // caller wants a session for this task, not a session of its own.
654
+ const pending = sessionsInFlight.get(sessionKey);
655
+ if (pending) {
656
+ console.error(`[acp] A session for ${taskId ? `task ${taskId}` : "the idle session"} is ` +
657
+ `already being opened; waiting for it rather than spawning a second agent`);
658
+ return pending;
659
+ }
660
+ const creation = createSession(taskId, sessionKey, acpCmdArgs, configs, agentrqConfig, mcpBridge);
661
+ sessionsInFlight.set(sessionKey, creation);
662
+ try {
663
+ return await creation;
664
+ }
665
+ finally {
666
+ // Only if it is still this attempt's: a session that was adopted and then
667
+ // re-requested may have registered a newer one under the same key.
668
+ if (sessionsInFlight.get(sessionKey) === creation) {
669
+ sessionsInFlight.delete(sessionKey);
670
+ }
671
+ }
672
+ }
673
+ /** Opens a session, with no regard for whether one is already on its way. */
674
+ async function createSession(taskId, initialSessionKey, acpCmdArgs, configs, agentrqConfig, mcpBridge) {
675
+ let sessionKey = initialSessionKey;
536
676
  // The session made at startup, before any task, is handed to the first task
537
677
  // that arrives rather than left beside a second agent doing the same job. Its
538
678
  // conversation is empty, so there is nothing for the task to inherit but the
@@ -552,6 +692,10 @@ export async function getOrCreateSession(taskId, acpCmdArgs, configs, agentrqCon
552
692
  if (idle) {
553
693
  idle.adopt(taskId);
554
694
  console.error(`[acp] Task ${taskId} took over the session opened at startup`);
695
+ const lastModels = idle.acpClient.lastModelsFor(idle.sessionId);
696
+ if (lastModels) {
697
+ void idle.acpClient.sendModelsToWorkspace(idle.sessionId, lastModels);
698
+ }
555
699
  return idle;
556
700
  }
557
701
  }
@@ -899,6 +1043,65 @@ bridge) {
899
1043
  configId,
900
1044
  });
901
1045
  }
1046
+ /**
1047
+ * Applies a concurrency limit the workspace asked for, and reports back the one
1048
+ * actually in force.
1049
+ *
1050
+ * The report is unconditional, which is the whole point of it. Someone moved a
1051
+ * control in the interface and is watching to see where it landed; a value that
1052
+ * was clamped, or one that was not a number at all, has to come back as the
1053
+ * real limit rather than as silence — otherwise the interface goes on showing a
1054
+ * number this gateway never adopted.
1055
+ */
1056
+ export async function handleSetConcurrency({ maxConcurrency }, queue,
1057
+ /** Absent only in tests. */
1058
+ bridge) {
1059
+ const requested = normalizeConcurrency(maxConcurrency);
1060
+ // In a finally, so the answer does not depend on applying the change going
1061
+ // well. "Always answered" is the whole design; leaving it as the last
1062
+ // statement made it true only while nothing above it threw.
1063
+ try {
1064
+ if (requested === undefined) {
1065
+ console.error(`[bridge] Received a set_concurrency notification asking for ` +
1066
+ `"${String(maxConcurrency)}", which is not a number of tasks; ` +
1067
+ `keeping the limit at ${queue.getMaxConcurrency()}`);
1068
+ }
1069
+ else {
1070
+ queue.setMaxConcurrency(requested);
1071
+ }
1072
+ }
1073
+ finally {
1074
+ if (bridge)
1075
+ await reportConcurrency(bridge, queue);
1076
+ }
1077
+ }
1078
+ /** Tells the workspace what the queue's limit is and what it is doing under it. */
1079
+ export async function reportConcurrency(bridge, queue) {
1080
+ await sendConcurrencyNotification(bridge, {
1081
+ maxConcurrency: queue.getMaxConcurrency(),
1082
+ active: queue.getActiveCount(),
1083
+ queued: queue.getQueueLength(),
1084
+ });
1085
+ }
1086
+ /**
1087
+ * Subscribes the queue to the workspace's concurrency directives.
1088
+ *
1089
+ * The reconnect subscription is the less obvious half. A reconnect mints a new
1090
+ * MCP session and the workspace keys this report to the connection it arrived
1091
+ * on — so a workspace that dropped and came back would otherwise go on showing
1092
+ * whatever limit it last heard about, which is the boot default for the rest of
1093
+ * the gateway's life.
1094
+ */
1095
+ export function registerConcurrencyListeners(bridge, queue) {
1096
+ bridge.on("setConcurrency", (params) => {
1097
+ handleSetConcurrency(params, queue, bridge).catch((err) => {
1098
+ console.error("[bridge] Error handling concurrency change:", err);
1099
+ });
1100
+ });
1101
+ bridge.on("reconnected", () => {
1102
+ void reportConcurrency(bridge, queue);
1103
+ });
1104
+ }
902
1105
  /**
903
1106
  * Handles task cancellation events from the MCP server.
904
1107
  * Cancels the ACP session/turn and immediately cancels any pending permissions.
@@ -1093,14 +1296,23 @@ export class TaskQueue {
1093
1296
  this.next();
1094
1297
  }
1095
1298
  }
1299
+ /**
1300
+ * Starts as many waiting tasks as the limit now has room for.
1301
+ *
1302
+ * A loop rather than a single task, because this is also what runs when the
1303
+ * limit is raised: going from 1 to 4 with three tasks waiting has to start
1304
+ * all three, and starting one and waiting for it to finish would make a raise
1305
+ * take effect one task at a time. `execute` counts the task as active before
1306
+ * it yields, so the condition is re-read against a number that already
1307
+ * includes everything this loop has started.
1308
+ */
1096
1309
  next() {
1097
- if (this.queue.length > 0 && this.activeTasks < this.maxConcurrency) {
1310
+ while (this.queue.length > 0 && this.activeTasks < this.maxConcurrency) {
1311
+ // Non-null: the loop condition has just established the queue is not empty.
1098
1312
  const nextTask = this.queue.shift();
1099
- if (nextTask) {
1100
- this.execute(nextTask).catch((err) => {
1101
- console.log("[queue] Error executing queued task:", err);
1102
- });
1103
- }
1313
+ this.execute(nextTask).catch((err) => {
1314
+ console.log("[queue] Error executing queued task:", err);
1315
+ });
1104
1316
  }
1105
1317
  }
1106
1318
  getActiveCount() {
@@ -1109,9 +1321,30 @@ export class TaskQueue {
1109
1321
  getQueueLength() {
1110
1322
  return this.queue.length;
1111
1323
  }
1324
+ getMaxConcurrency() {
1325
+ return this.maxConcurrency;
1326
+ }
1327
+ /**
1328
+ * Changes how many tasks may run at once, while tasks are running.
1329
+ *
1330
+ * Lowering the limit never interrupts anything: a task that has already been
1331
+ * handed to the agent keeps its turn, and the queue simply stops handing out
1332
+ * new ones until enough have finished. So a limit lowered below the number
1333
+ * currently running is honoured going forward rather than retroactively —
1334
+ * killing work already in flight is not what "run fewer at once" means.
1335
+ */
1336
+ setMaxConcurrency(maxConcurrency) {
1337
+ if (maxConcurrency === this.maxConcurrency)
1338
+ return;
1339
+ const previous = this.maxConcurrency;
1340
+ this.maxConcurrency = maxConcurrency;
1341
+ console.error(`[queue] Concurrency limit ${previous} -> ${maxConcurrency} ` +
1342
+ `(${this.activeTasks} running, ${this.queue.length} queued)`);
1343
+ this.next();
1344
+ }
1112
1345
  }
1113
1346
  /** Default maximum number of concurrent tasks allowed to prompt the ACP agent at once. */
1114
- export const DEFAULT_MAX_CONCURRENCY = 1;
1347
+ export const DEFAULT_MAX_CONCURRENCY = MIN_MAX_CONCURRENCY;
1115
1348
  /**
1116
1349
  * Parses the gateway's own flags — everything before the `--` that introduces
1117
1350
  * the agent command.
@@ -1132,11 +1365,40 @@ export function parseGatewayArgs(args) {
1132
1365
  switch (args[i]) {
1133
1366
  case "--max-concurrency":
1134
1367
  case "--maxConcurrency": {
1135
- const parsed = parseInt(value ?? "", 10);
1136
- if (!isNaN(parsed)) {
1137
- options.maxConcurrency = parsed;
1368
+ // A token that starts with a digit was meant as this flag's number, so
1369
+ // it is consumed whether or not it reads as one — left behind, it fell
1370
+ // into `rest`, which is the agent command when no `--` was used, and
1371
+ // `--max-concurrency 8x claude` went looking for an agent called "8x".
1372
+ //
1373
+ // A token that does not start with a digit was never the number. It is
1374
+ // the agent command with the number left out, and eating it would turn
1375
+ // `--max-concurrency claude` from a gateway running claude at the
1376
+ // default into a gateway with nothing to run at all.
1377
+ const looksNumeric = value !== undefined && /^[0-9]/.test(value);
1378
+ if (looksNumeric)
1138
1379
  i++;
1380
+ // Read by the same rule the workspace's set_concurrency goes through,
1381
+ // so the flag and the runtime control cannot disagree about what a
1382
+ // number means. It is also what stops `--max-concurrency 0`, which
1383
+ // used to be accepted and then held every task in the queue forever.
1384
+ const parsed = looksNumeric ? normalizeConcurrency(value) : undefined;
1385
+ if (parsed === undefined) {
1386
+ if (value !== undefined) {
1387
+ console.error(`[acp-gateway] --max-concurrency "${value}" is not a number of ` +
1388
+ `tasks; keeping ${options.maxConcurrency}.`);
1389
+ }
1390
+ break;
1391
+ }
1392
+ // Said out loud, unlike the workspace's path, which reports the limit
1393
+ // it settled on back to the interface. Nothing reports a flag back to
1394
+ // the person who typed it, so an existing `--max-concurrency 128` would
1395
+ // otherwise quietly boot at the ceiling with no sign it had been cut.
1396
+ const asked = Number(value);
1397
+ if (Number.isFinite(asked) && Math.trunc(asked) !== parsed) {
1398
+ console.error(`[acp-gateway] --max-concurrency ${value} is outside ` +
1399
+ `${MIN_MAX_CONCURRENCY}-${MAX_MAX_CONCURRENCY}; using ${parsed}.`);
1139
1400
  }
1401
+ options.maxConcurrency = parsed;
1140
1402
  break;
1141
1403
  }
1142
1404
  case "--permission-timeout": {
@@ -1415,8 +1677,9 @@ AUTHENTICATION
1415
1677
  mid-run. Defaults to choosing one automatically.
1416
1678
 
1417
1679
  BRIDGE
1418
- --max-concurrency <number> How many tasks may prompt the agent at once.
1419
- Defaults to ${DEFAULT_MAX_CONCURRENCY}.
1680
+ --max-concurrency <number> How many tasks may prompt the agent at once, from
1681
+ ${MIN_MAX_CONCURRENCY} to ${MAX_MAX_CONCURRENCY}. Defaults to ${DEFAULT_MAX_CONCURRENCY}. This is the limit
1682
+ to start on — agentrq can change it while running.
1420
1683
  --permission-timeout <min> How long a tool call waits for someone to approve
1421
1684
  it before the turn is cancelled. Defaults to 30.
1422
1685
  0 waits indefinitely, which is what a wedged
@@ -1554,13 +1817,21 @@ async function main() {
1554
1817
  }
1555
1818
  console.error("\n[bridge] Incoming task from MCP server. Forwarding to ACP agent...");
1556
1819
  const queuedSeq = nextTaskSeq();
1557
- taskQueue.run(async () => {
1820
+ // Behind any turn already running for this task, and behind it *before*
1821
+ // asking for a queue slot: one session takes one turn at a time, and two
1822
+ // messages on one chat arrive as two deliveries of one task. Waiting
1823
+ // inside a slot would hold a share of the concurrency limit while doing
1824
+ // nothing at all — enough messages on one chat would hold every slot and
1825
+ // stop the gateway running anything else.
1826
+ runTurnForTask(taskId, () => taskQueue.run(async () => {
1558
1827
  if (isTaskCancelled(taskId, queuedSeq)) {
1559
1828
  console.error(`[bridge] Task ${taskId} was cancelled before execution started, skipping`);
1560
1829
  return;
1561
1830
  }
1562
1831
  try {
1563
1832
  const sessionInfo = await getOrCreateSession(taskId, acpCmdArgs, configs, agentrqConfig, mcpBridge);
1833
+ // Checked again here as well as above: waiting for the turn ahead
1834
+ // of this one is another window in which a cancel can land.
1564
1835
  if (isTaskCancelled(taskId, queuedSeq)) {
1565
1836
  console.error(`[bridge] Task ${taskId} was cancelled during session setup, cancelling session`);
1566
1837
  await sessionInfo.acpClient.cancelTurn(sessionInfo.sessionId);
@@ -1577,7 +1848,7 @@ async function main() {
1577
1848
  catch (err) {
1578
1849
  console.error("[acp] Error during prompt execution:", err);
1579
1850
  }
1580
- }).catch((err) => {
1851
+ })).catch((err) => {
1581
1852
  console.error("[bridge] Error queuing task:", err);
1582
1853
  });
1583
1854
  });
@@ -1592,6 +1863,7 @@ async function main() {
1592
1863
  console.error("[bridge] Error handling model selection:", err);
1593
1864
  });
1594
1865
  });
1866
+ registerConcurrencyListeners(mcpBridge, taskQueue);
1595
1867
  // Everything above is listening; nothing below can be missed.
1596
1868
  //
1597
1869
  // The agent comes up before the workspace is told anything, so a task can
@@ -1612,6 +1884,11 @@ async function main() {
1612
1884
  process.exit(1);
1613
1885
  }
1614
1886
  await mcpBridge.connect();
1887
+ // Said before any task runs, because that is when a human looking at the
1888
+ // workspace wants to know how much work it will take at once — and because
1889
+ // the control cannot be rendered at all until the workspace knows both the
1890
+ // current limit and that this gateway is one that will act on a change.
1891
+ void reportConcurrency(mcpBridge, taskQueue);
1615
1892
  // Only when the agent has not spoken for itself. A session that came up
1616
1893
  // already reported the agent's own name, title and version from its
1617
1894
  // handshake, and the registry's entry is a coarser answer to the same
@@ -1715,12 +1992,15 @@ export async function checkForNextTask(mcpBridge, acpCmdArgsOrConnection, config
1715
1992
  await acpClientToUse.reportStopReason(sessionIdToUse, promptResult.stopReason);
1716
1993
  console.error(`\n[acp] Agent completed with: ${promptResult.stopReason}`);
1717
1994
  };
1718
- if (taskQueue) {
1719
- await taskQueue.run(runFn);
1720
- }
1721
- else {
1722
- await runFn();
1723
- }
1995
+ // Serialised against any turn already running for this task, for the
1996
+ // reason runTurnForTask records: this path and the push notification can
1997
+ // both be handed the same task, and word it differently enough that the
1998
+ // repetition guard drops neither.
1999
+ //
2000
+ // Outside the queue slot rather than inside it, so a delivery that is
2001
+ // only waiting for the turn ahead of it is not also holding a share of
2002
+ // the concurrency limit while it waits.
2003
+ await runTurnForTask(taskId, () => taskQueue ? taskQueue.run(runFn) : runFn());
1724
2004
  }
1725
2005
  else {
1726
2006
  console.error("[bridge] No pending tasks available.");