@agentrq/acp-gateway 0.2.17 → 0.2.19

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
@@ -903,6 +1043,155 @@ bridge) {
903
1043
  configId,
904
1044
  });
905
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
+ // Often asked for while the queue's own reports are still going out —
1075
+ // raising the limit starts waiting tasks, and each announces itself. That
1076
+ // is why this is here anyway: the queue says nothing at all when a set
1077
+ // moves no numbers, and a set must always be answered.
1078
+ //
1079
+ // Awaiting it is what makes the answer real. Reports go out one at a time,
1080
+ // and this resolves only once no further report is wanted, so by the time
1081
+ // it returns the workspace has been told the limit that actually took
1082
+ // effect — after, not before, anything the raise set running.
1083
+ if (bridge)
1084
+ await reportConcurrency(bridge, queue);
1085
+ }
1086
+ }
1087
+ /**
1088
+ * The report on the wire, if one is, and whether the numbers moved while it flew.
1089
+ *
1090
+ * Each report is its own HTTP POST, and two in flight at once may be processed
1091
+ * in either order — so the workspace would be left showing whichever landed
1092
+ * last rather than whichever is true. That cost little while a report followed
1093
+ * a human moving a control. It costs a great deal now that one follows every
1094
+ * task transition, because `execute` announces a freed slot and then `next()`
1095
+ * immediately announces the task that took it: two reports, one tick apart,
1096
+ * disagreeing about the same number. Landing them the wrong way round leaves
1097
+ * the interface wrong until something else moves — which is the very failure
1098
+ * this feature exists to end.
1099
+ */
1100
+ let reportOnTheWire = null;
1101
+ let numbersMovedAgain = false;
1102
+ /** Forgets any report in flight. For tests. */
1103
+ export function resetConcurrencyReports() {
1104
+ reportOnTheWire = null;
1105
+ numbersMovedAgain = false;
1106
+ }
1107
+ /**
1108
+ * Tells the workspace what the queue's limit is and what it is doing under it.
1109
+ *
1110
+ * One report at a time, so they arrive in the order they were asked for. A
1111
+ * report wanted while one is flying does not queue up behind it: the numbers
1112
+ * are read again when the wire is free, so a burst of transitions costs one
1113
+ * further report rather than one per transition, and every report carries the
1114
+ * state at the moment it was actually sent. Whatever the workspace hears last
1115
+ * is therefore the truth, which is the only property that really matters here.
1116
+ *
1117
+ * Callers may await this and know a report reflecting their change has gone
1118
+ * out — `handleSetConcurrency` depends on exactly that.
1119
+ */
1120
+ export function reportConcurrency(bridge, queue) {
1121
+ if (reportOnTheWire) {
1122
+ numbersMovedAgain = true;
1123
+ return reportOnTheWire;
1124
+ }
1125
+ // Assigned from the call rather than after it: `drainConcurrencyReports` runs
1126
+ // as far as its first await before returning, and nothing else can run in
1127
+ // between.
1128
+ return (reportOnTheWire = drainConcurrencyReports(bridge, queue));
1129
+ }
1130
+ /**
1131
+ * Sends reports until nobody has asked for another.
1132
+ *
1133
+ * The slot is cleared in a `finally` inside this function rather than off the
1134
+ * returned promise, so that it happens in the same tick the loop ends. Clearing
1135
+ * it a microtask later would leave a window where a caller sees a report in
1136
+ * flight, sets the flag, and is answered by a loop that has already stopped
1137
+ * reading it — a report asked for and never sent.
1138
+ *
1139
+ * The bridge is whichever caller opened the slot. The gateway has exactly one
1140
+ * for its whole life, and a reconnect replaces what is inside it rather than
1141
+ * the object, so there is no second bridge for a collapsed report to miss.
1142
+ */
1143
+ async function drainConcurrencyReports(bridge, queue) {
1144
+ try {
1145
+ do {
1146
+ numbersMovedAgain = false;
1147
+ // Read here, not at the call: a collapsed report is worth sending only
1148
+ // because it describes the queue now rather than when it was asked for.
1149
+ await sendConcurrencyNotification(bridge, {
1150
+ maxConcurrency: queue.getMaxConcurrency(),
1151
+ active: queue.getActiveCount(),
1152
+ queued: queue.getQueueLength(),
1153
+ });
1154
+ } while (numbersMovedAgain);
1155
+ }
1156
+ finally {
1157
+ reportOnTheWire = null;
1158
+ }
1159
+ }
1160
+ /**
1161
+ * Builds the task queue already able to report itself.
1162
+ *
1163
+ * Out here rather than inline in `main()` for the reason
1164
+ * `registerConcurrencyListeners` is: `main()` spawns processes and never
1165
+ * returns, so nothing written inside it can be tested, and wiring that nothing
1166
+ * exercises is wiring nobody finds out is wrong.
1167
+ *
1168
+ * The callback names the queue it is being handed to. That is safe because it
1169
+ * only ever runs later, from inside the queue's own methods, by which time the
1170
+ * binding exists.
1171
+ */
1172
+ export function createTaskQueue(maxConcurrency, bridge) {
1173
+ const queue = new TaskQueue(maxConcurrency, () => void reportConcurrency(bridge, queue));
1174
+ return queue;
1175
+ }
1176
+ /**
1177
+ * Subscribes the queue to the workspace's concurrency directives.
1178
+ *
1179
+ * The reconnect subscription is the less obvious half. A reconnect mints a new
1180
+ * MCP session and the workspace keys this report to the connection it arrived
1181
+ * on — so a workspace that dropped and came back would otherwise go on showing
1182
+ * whatever limit it last heard about, which is the boot default for the rest of
1183
+ * the gateway's life.
1184
+ */
1185
+ export function registerConcurrencyListeners(bridge, queue) {
1186
+ bridge.on("setConcurrency", (params) => {
1187
+ handleSetConcurrency(params, queue, bridge).catch((err) => {
1188
+ console.error("[bridge] Error handling concurrency change:", err);
1189
+ });
1190
+ });
1191
+ bridge.on("reconnected", () => {
1192
+ void reportConcurrency(bridge, queue);
1193
+ });
1194
+ }
906
1195
  /**
907
1196
  * Handles task cancellation events from the MCP server.
908
1197
  * Cancels the ACP session/turn and immediately cancels any pending permissions.
@@ -1063,10 +1352,37 @@ export function createAcpSessionSwitcher(connection, params, initialSessionId) {
1063
1352
  }
1064
1353
  export class TaskQueue {
1065
1354
  maxConcurrency;
1355
+ onChange;
1066
1356
  activeTasks = 0;
1067
1357
  queue = [];
1068
- constructor(maxConcurrency) {
1358
+ /**
1359
+ * @param onChange Told whenever the number running or waiting moves, so
1360
+ * somebody can report it. The queue has no idea who is listening — it holds
1361
+ * no bridge and knows nothing about notifications — because what it owes the
1362
+ * interface is the fact that its numbers moved, not the delivery of that
1363
+ * fact. Absent only in tests, matching `handleSetConcurrency`'s `bridge?`.
1364
+ */
1365
+ constructor(maxConcurrency, onChange) {
1069
1366
  this.maxConcurrency = maxConcurrency;
1367
+ this.onChange = onChange;
1368
+ }
1369
+ /**
1370
+ * Says the numbers moved, and survives a listener that cannot take the news.
1371
+ *
1372
+ * Guarded because this is called from `execute`, including from its `finally`:
1373
+ * a listener that threw there would replace the task's own error with its own,
1374
+ * losing what actually went wrong, and one that threw on the way in would stop
1375
+ * the task before it started. Running tasks is this class's job; telling an
1376
+ * interface about them is a courtesy, and a courtesy must not be able to break
1377
+ * the job.
1378
+ */
1379
+ announce() {
1380
+ try {
1381
+ this.onChange?.();
1382
+ }
1383
+ catch (err) {
1384
+ console.error("[queue] Error reporting the queue's state:", err);
1385
+ }
1070
1386
  }
1071
1387
  async run(taskFn) {
1072
1388
  if (this.activeTasks < this.maxConcurrency) {
@@ -1084,27 +1400,46 @@ export class TaskQueue {
1084
1400
  throw err;
1085
1401
  }
1086
1402
  });
1403
+ // Nothing started, but something is now waiting — which is exactly the
1404
+ // state a full gateway is in, and the one worth seeing.
1405
+ this.announce();
1087
1406
  });
1088
1407
  }
1089
1408
  }
1090
1409
  async execute(taskFn) {
1091
1410
  this.activeTasks++;
1411
+ // Before the task is awaited rather than after, or the report would not go
1412
+ // out until the work it is announcing had already finished.
1413
+ this.announce();
1092
1414
  try {
1093
1415
  await taskFn();
1094
1416
  }
1095
1417
  finally {
1096
1418
  this.activeTasks--;
1419
+ // Before `next()`, so this says a slot came free; whatever `next()` then
1420
+ // starts announces itself. The other order would report the same settled
1421
+ // state twice and never show the gap.
1422
+ this.announce();
1097
1423
  this.next();
1098
1424
  }
1099
1425
  }
1426
+ /**
1427
+ * Starts as many waiting tasks as the limit now has room for.
1428
+ *
1429
+ * A loop rather than a single task, because this is also what runs when the
1430
+ * limit is raised: going from 1 to 4 with three tasks waiting has to start
1431
+ * all three, and starting one and waiting for it to finish would make a raise
1432
+ * take effect one task at a time. `execute` counts the task as active before
1433
+ * it yields, so the condition is re-read against a number that already
1434
+ * includes everything this loop has started.
1435
+ */
1100
1436
  next() {
1101
- if (this.queue.length > 0 && this.activeTasks < this.maxConcurrency) {
1437
+ while (this.queue.length > 0 && this.activeTasks < this.maxConcurrency) {
1438
+ // Non-null: the loop condition has just established the queue is not empty.
1102
1439
  const nextTask = this.queue.shift();
1103
- if (nextTask) {
1104
- this.execute(nextTask).catch((err) => {
1105
- console.log("[queue] Error executing queued task:", err);
1106
- });
1107
- }
1440
+ this.execute(nextTask).catch((err) => {
1441
+ console.log("[queue] Error executing queued task:", err);
1442
+ });
1108
1443
  }
1109
1444
  }
1110
1445
  getActiveCount() {
@@ -1113,9 +1448,30 @@ export class TaskQueue {
1113
1448
  getQueueLength() {
1114
1449
  return this.queue.length;
1115
1450
  }
1451
+ getMaxConcurrency() {
1452
+ return this.maxConcurrency;
1453
+ }
1454
+ /**
1455
+ * Changes how many tasks may run at once, while tasks are running.
1456
+ *
1457
+ * Lowering the limit never interrupts anything: a task that has already been
1458
+ * handed to the agent keeps its turn, and the queue simply stops handing out
1459
+ * new ones until enough have finished. So a limit lowered below the number
1460
+ * currently running is honoured going forward rather than retroactively —
1461
+ * killing work already in flight is not what "run fewer at once" means.
1462
+ */
1463
+ setMaxConcurrency(maxConcurrency) {
1464
+ if (maxConcurrency === this.maxConcurrency)
1465
+ return;
1466
+ const previous = this.maxConcurrency;
1467
+ this.maxConcurrency = maxConcurrency;
1468
+ console.error(`[queue] Concurrency limit ${previous} -> ${maxConcurrency} ` +
1469
+ `(${this.activeTasks} running, ${this.queue.length} queued)`);
1470
+ this.next();
1471
+ }
1116
1472
  }
1117
1473
  /** Default maximum number of concurrent tasks allowed to prompt the ACP agent at once. */
1118
- export const DEFAULT_MAX_CONCURRENCY = 1;
1474
+ export const DEFAULT_MAX_CONCURRENCY = MIN_MAX_CONCURRENCY;
1119
1475
  /**
1120
1476
  * Parses the gateway's own flags — everything before the `--` that introduces
1121
1477
  * the agent command.
@@ -1136,11 +1492,40 @@ export function parseGatewayArgs(args) {
1136
1492
  switch (args[i]) {
1137
1493
  case "--max-concurrency":
1138
1494
  case "--maxConcurrency": {
1139
- const parsed = parseInt(value ?? "", 10);
1140
- if (!isNaN(parsed)) {
1141
- options.maxConcurrency = parsed;
1495
+ // A token that starts with a digit was meant as this flag's number, so
1496
+ // it is consumed whether or not it reads as one — left behind, it fell
1497
+ // into `rest`, which is the agent command when no `--` was used, and
1498
+ // `--max-concurrency 8x claude` went looking for an agent called "8x".
1499
+ //
1500
+ // A token that does not start with a digit was never the number. It is
1501
+ // the agent command with the number left out, and eating it would turn
1502
+ // `--max-concurrency claude` from a gateway running claude at the
1503
+ // default into a gateway with nothing to run at all.
1504
+ const looksNumeric = value !== undefined && /^[0-9]/.test(value);
1505
+ if (looksNumeric)
1142
1506
  i++;
1507
+ // Read by the same rule the workspace's set_concurrency goes through,
1508
+ // so the flag and the runtime control cannot disagree about what a
1509
+ // number means. It is also what stops `--max-concurrency 0`, which
1510
+ // used to be accepted and then held every task in the queue forever.
1511
+ const parsed = looksNumeric ? normalizeConcurrency(value) : undefined;
1512
+ if (parsed === undefined) {
1513
+ if (value !== undefined) {
1514
+ console.error(`[acp-gateway] --max-concurrency "${value}" is not a number of ` +
1515
+ `tasks; keeping ${options.maxConcurrency}.`);
1516
+ }
1517
+ break;
1143
1518
  }
1519
+ // Said out loud, unlike the workspace's path, which reports the limit
1520
+ // it settled on back to the interface. Nothing reports a flag back to
1521
+ // the person who typed it, so an existing `--max-concurrency 128` would
1522
+ // otherwise quietly boot at the ceiling with no sign it had been cut.
1523
+ const asked = Number(value);
1524
+ if (Number.isFinite(asked) && Math.trunc(asked) !== parsed) {
1525
+ console.error(`[acp-gateway] --max-concurrency ${value} is outside ` +
1526
+ `${MIN_MAX_CONCURRENCY}-${MAX_MAX_CONCURRENCY}; using ${parsed}.`);
1527
+ }
1528
+ options.maxConcurrency = parsed;
1144
1529
  break;
1145
1530
  }
1146
1531
  case "--permission-timeout": {
@@ -1419,8 +1804,9 @@ AUTHENTICATION
1419
1804
  mid-run. Defaults to choosing one automatically.
1420
1805
 
1421
1806
  BRIDGE
1422
- --max-concurrency <number> How many tasks may prompt the agent at once.
1423
- Defaults to ${DEFAULT_MAX_CONCURRENCY}.
1807
+ --max-concurrency <number> How many tasks may prompt the agent at once, from
1808
+ ${MIN_MAX_CONCURRENCY} to ${MAX_MAX_CONCURRENCY}. Defaults to ${DEFAULT_MAX_CONCURRENCY}. This is the limit
1809
+ to start on — agentrq can change it while running.
1424
1810
  --permission-timeout <min> How long a tool call waits for someone to approve
1425
1811
  it before the turn is cancelled. Defaults to 30.
1426
1812
  0 waits indefinitely, which is what a wedged
@@ -1500,9 +1886,10 @@ async function main() {
1500
1886
  authConfig.methodId = authMethodId;
1501
1887
  modelConfig.modelId = options.modelId;
1502
1888
  permissionConfig.timeoutMs = options.permissionTimeoutMs;
1503
- const taskQueue = new TaskQueue(maxConcurrency);
1504
1889
  // 3. Initialize MCP Bridge
1505
1890
  const mcpBridge = new MCPBridge(agentrqConfig);
1891
+ // After the bridge, because the queue now reports itself to it.
1892
+ const taskQueue = createTaskQueue(maxConcurrency, mcpBridge);
1506
1893
  // Auth commands talk to the agent and exit; they never start bridging tasks.
1507
1894
  // They run before the bridge connects, so a first-time login still works when
1508
1895
  // the workspace is unreachable — `callTool` connects on demand if the login
@@ -1558,13 +1945,21 @@ async function main() {
1558
1945
  }
1559
1946
  console.error("\n[bridge] Incoming task from MCP server. Forwarding to ACP agent...");
1560
1947
  const queuedSeq = nextTaskSeq();
1561
- taskQueue.run(async () => {
1948
+ // Behind any turn already running for this task, and behind it *before*
1949
+ // asking for a queue slot: one session takes one turn at a time, and two
1950
+ // messages on one chat arrive as two deliveries of one task. Waiting
1951
+ // inside a slot would hold a share of the concurrency limit while doing
1952
+ // nothing at all — enough messages on one chat would hold every slot and
1953
+ // stop the gateway running anything else.
1954
+ runTurnForTask(taskId, () => taskQueue.run(async () => {
1562
1955
  if (isTaskCancelled(taskId, queuedSeq)) {
1563
1956
  console.error(`[bridge] Task ${taskId} was cancelled before execution started, skipping`);
1564
1957
  return;
1565
1958
  }
1566
1959
  try {
1567
1960
  const sessionInfo = await getOrCreateSession(taskId, acpCmdArgs, configs, agentrqConfig, mcpBridge);
1961
+ // Checked again here as well as above: waiting for the turn ahead
1962
+ // of this one is another window in which a cancel can land.
1568
1963
  if (isTaskCancelled(taskId, queuedSeq)) {
1569
1964
  console.error(`[bridge] Task ${taskId} was cancelled during session setup, cancelling session`);
1570
1965
  await sessionInfo.acpClient.cancelTurn(sessionInfo.sessionId);
@@ -1581,7 +1976,7 @@ async function main() {
1581
1976
  catch (err) {
1582
1977
  console.error("[acp] Error during prompt execution:", err);
1583
1978
  }
1584
- }).catch((err) => {
1979
+ })).catch((err) => {
1585
1980
  console.error("[bridge] Error queuing task:", err);
1586
1981
  });
1587
1982
  });
@@ -1596,6 +1991,7 @@ async function main() {
1596
1991
  console.error("[bridge] Error handling model selection:", err);
1597
1992
  });
1598
1993
  });
1994
+ registerConcurrencyListeners(mcpBridge, taskQueue);
1599
1995
  // Everything above is listening; nothing below can be missed.
1600
1996
  //
1601
1997
  // The agent comes up before the workspace is told anything, so a task can
@@ -1616,6 +2012,11 @@ async function main() {
1616
2012
  process.exit(1);
1617
2013
  }
1618
2014
  await mcpBridge.connect();
2015
+ // Said before any task runs, because that is when a human looking at the
2016
+ // workspace wants to know how much work it will take at once — and because
2017
+ // the control cannot be rendered at all until the workspace knows both the
2018
+ // current limit and that this gateway is one that will act on a change.
2019
+ void reportConcurrency(mcpBridge, taskQueue);
1619
2020
  // Only when the agent has not spoken for itself. A session that came up
1620
2021
  // already reported the agent's own name, title and version from its
1621
2022
  // handshake, and the registry's entry is a coarser answer to the same
@@ -1719,12 +2120,15 @@ export async function checkForNextTask(mcpBridge, acpCmdArgsOrConnection, config
1719
2120
  await acpClientToUse.reportStopReason(sessionIdToUse, promptResult.stopReason);
1720
2121
  console.error(`\n[acp] Agent completed with: ${promptResult.stopReason}`);
1721
2122
  };
1722
- if (taskQueue) {
1723
- await taskQueue.run(runFn);
1724
- }
1725
- else {
1726
- await runFn();
1727
- }
2123
+ // Serialised against any turn already running for this task, for the
2124
+ // reason runTurnForTask records: this path and the push notification can
2125
+ // both be handed the same task, and word it differently enough that the
2126
+ // repetition guard drops neither.
2127
+ //
2128
+ // Outside the queue slot rather than inside it, so a delivery that is
2129
+ // only waiting for the turn ahead of it is not also holding a share of
2130
+ // the concurrency limit while it waits.
2131
+ await runTurnForTask(taskId, () => taskQueue ? taskQueue.run(runFn) : runFn());
1728
2132
  }
1729
2133
  else {
1730
2134
  console.error("[bridge] No pending tasks available.");