agl 43.2.0 → 43.3.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 (184) hide show
  1. package/changelog.md +20 -0
  2. package/dist_serve/bundle.js +2845 -2638
  3. package/dist_serve/bundle.js.map +2 -2
  4. package/dist_serve/bundle.js.third-party-notices.json +1 -1
  5. package/dist_serve/bundle.js.third-party-notices.txt +1 -1
  6. package/dist_ts/00_commitinfo_data.js +1 -1
  7. package/dist_ts/aglapi/aglapisurface.document.js +197 -17
  8. package/dist_ts/classes.accountsactions.d.ts +3 -1
  9. package/dist_ts/classes.accountsactions.js +21 -3
  10. package/dist_ts/classes.claudeharness.d.ts +16 -0
  11. package/dist_ts/classes.claudeharness.js +24 -2
  12. package/dist_ts/classes.codexclientadapter.d.ts +11 -0
  13. package/dist_ts/classes.codexclientadapter.js +14 -2
  14. package/dist_ts/classes.controller.d.ts +165 -11
  15. package/dist_ts/classes.controller.js +1095 -170
  16. package/dist_ts/classes.controllerdevices.d.ts +2 -0
  17. package/dist_ts/classes.controllerdevices.js +6 -1
  18. package/dist_ts/classes.inbox.d.ts +72 -0
  19. package/dist_ts/classes.inbox.js +231 -0
  20. package/dist_ts/classes.inferencerouter.d.ts +10 -0
  21. package/dist_ts/classes.inferencerouter.js +5 -3
  22. package/dist_ts/classes.inferenceservice.js +2 -2
  23. package/dist_ts/classes.mcpclient.d.ts +1 -1
  24. package/dist_ts/classes.mcpclient.js +24 -6
  25. package/dist_ts/classes.mcpcontrollerhost.js +3 -1
  26. package/dist_ts/classes.mcptools.js +13 -8
  27. package/dist_ts/classes.mcpvalidation.d.ts +5 -0
  28. package/dist_ts/classes.mcpvalidation.js +32 -2
  29. package/dist_ts/classes.nativesessions.d.ts +17 -4
  30. package/dist_ts/classes.nativesessions.js +41 -9
  31. package/dist_ts/classes.opencodeclient.d.ts +23 -2
  32. package/dist_ts/classes.opencodeclient.js +47 -3
  33. package/dist_ts/classes.publishedset.d.ts +38 -0
  34. package/dist_ts/classes.publishedset.js +50 -0
  35. package/dist_ts/classes.sessionfeed.d.ts +3 -3
  36. package/dist_ts/classes.sessionfeed.js +18 -26
  37. package/dist_ts/classes.systemmetricssampler.d.ts +6 -0
  38. package/dist_ts/classes.systemmetricssampler.js +15 -3
  39. package/dist_ts/classes.ticketstore.d.ts +50 -3
  40. package/dist_ts/classes.ticketstore.js +45 -8
  41. package/dist_ts/driver/classes.directreports.d.ts +14 -4
  42. package/dist_ts/driver/classes.directreports.js +25 -6
  43. package/dist_ts/driver/classes.driverservice.d.ts +44 -3
  44. package/dist_ts/driver/classes.driverservice.js +50 -16
  45. package/dist_ts/fleet/classes.claudeworkers.d.ts +21 -5
  46. package/dist_ts/fleet/classes.claudeworkers.js +142 -46
  47. package/dist_ts/fleet/classes.codexworkers.d.ts +16 -4
  48. package/dist_ts/fleet/classes.codexworkers.js +22 -5
  49. package/dist_ts/fleet/classes.workercommand.d.ts +6 -1
  50. package/dist_ts/fleet/classes.workercommand.js +15 -4
  51. package/dist_ts/fleet/classes.workers.d.ts +5 -1
  52. package/dist_ts/fleet/classes.workers.js +8 -2
  53. package/dist_ts/fleet/functions.unbounddrivers.js +2 -2
  54. package/dist_ts/fleet/functions.workervalidation.js +2 -2
  55. package/dist_ts/fleet/interfaces.workers.d.ts +21 -3
  56. package/dist_ts/fleet/interfaces.workers.js +1 -1
  57. package/dist_ts/functions.agentmessage.d.ts +3 -0
  58. package/dist_ts/functions.agentmessage.js +4 -1
  59. package/dist_ts/functions.deviceapi.d.ts +151 -4
  60. package/dist_ts/functions.deviceapi.js +893 -38
  61. package/dist_ts/functions.fleetworkercli.d.ts +1 -1
  62. package/dist_ts/functions.fleetworkercli.js +11 -8
  63. package/dist_ts/functions.inferencecli.js +3 -1
  64. package/dist_ts/functions.mcpfleetworkertools.js +2 -2
  65. package/dist_ts/functions.ticketvalidation.js +11 -2
  66. package/dist_ts/interfaces.auth.d.ts +1 -1
  67. package/dist_ts/interfaces.auth.js +9 -1
  68. package/dist_ts/plugins.d.ts +3 -1
  69. package/dist_ts/plugins.js +7 -2
  70. package/dist_ts_authswitch/authority-contract.d.ts +25 -0
  71. package/dist_ts_authswitch/authority-contract.js +1 -1
  72. package/dist_ts_authswitch/authority-overview.d.ts +8 -0
  73. package/dist_ts_authswitch/authority-overview.js +17 -6
  74. package/dist_ts_authswitch/authority-placement.d.ts +20 -16
  75. package/dist_ts_authswitch/authority-placement.js +17 -10
  76. package/dist_ts_authswitch/authority-renewal.d.ts +34 -0
  77. package/dist_ts_authswitch/authority-renewal.js +56 -0
  78. package/dist_ts_authswitch/classes.authoritybroker.d.ts +8 -0
  79. package/dist_ts_authswitch/classes.authoritybroker.js +35 -2
  80. package/dist_ts_authswitch/classes.authoritycli.d.ts +1 -0
  81. package/dist_ts_authswitch/classes.authoritycli.js +44 -3
  82. package/dist_ts_authswitch/classes.authorityclient.d.ts +6 -1
  83. package/dist_ts_authswitch/classes.authorityclient.js +12 -4
  84. package/dist_ts_authswitch/classes.authoritydaemon.js +8 -1
  85. package/dist_ts_authswitch/classes.authoritydatabase.js +6 -2
  86. package/dist_ts_authswitch/classes.authoritymodels.d.ts +7 -0
  87. package/dist_ts_authswitch/classes.authoritymodels.js +21 -5
  88. package/dist_ts_interfaces/devices.d.ts +1012 -5
  89. package/dist_ts_interfaces/devices.js +68 -2
  90. package/dist_ts_interfaces/fleetworkers.d.ts +5 -3
  91. package/dist_ts_interfaces/inbox.d.ts +234 -0
  92. package/dist_ts_interfaces/inbox.js +101 -0
  93. package/dist_ts_interfaces/index.d.ts +1 -0
  94. package/dist_ts_interfaces/index.js +2 -1
  95. package/dist_ts_interfaces/interfaces.d.ts +10 -3
  96. package/dist_ts_interfaces/interfaces.js +4 -2
  97. package/dist_ts_interfaces/mcprequests.d.ts +34 -4
  98. package/dist_ts_interfaces/mcprequests.js +11 -1
  99. package/dist_ts_interfaces/mcpworkspacerequests.d.ts +4 -1
  100. package/dist_ts_interfaces/mcpworkspacerequests.js +1 -1
  101. package/dist_ts_interfaces/nativesessions.d.ts +16 -3
  102. package/dist_ts_interfaces/plugins.d.ts +2 -1
  103. package/dist_ts_interfaces/plugins.js +4 -2
  104. package/dist_ts_interfaces/requests.accounts.d.ts +21 -0
  105. package/dist_ts_interfaces/requests.accounts.js +3 -1
  106. package/dist_ts_interfaces/requests.d.ts +3 -2
  107. package/dist_ts_interfaces/requests.js +1 -1
  108. package/docs/authswitch.md +20 -1
  109. package/package.json +3 -3
  110. package/readme.md +112 -26
  111. package/ts/00_commitinfo_data.ts +1 -1
  112. package/ts/aglapi/aglapisurface.document.ts +196 -16
  113. package/ts/classes.accountsactions.ts +30 -3
  114. package/ts/classes.claudeharness.ts +27 -1
  115. package/ts/classes.codexclientadapter.ts +14 -1
  116. package/ts/classes.controller.ts +1294 -246
  117. package/ts/classes.controllerdevices.ts +6 -0
  118. package/ts/classes.inbox.ts +239 -0
  119. package/ts/classes.inferencerouter.ts +15 -2
  120. package/ts/classes.inferenceservice.ts +1 -1
  121. package/ts/classes.mcpclient.ts +24 -3
  122. package/ts/classes.mcpcontrollerhost.ts +2 -0
  123. package/ts/classes.mcptools.ts +12 -7
  124. package/ts/classes.mcpvalidation.ts +27 -1
  125. package/ts/classes.nativesessions.ts +50 -12
  126. package/ts/classes.opencodeclient.ts +55 -4
  127. package/ts/classes.publishedset.ts +56 -0
  128. package/ts/classes.sessionfeed.ts +17 -20
  129. package/ts/classes.systemmetricssampler.ts +13 -2
  130. package/ts/classes.ticketstore.ts +73 -12
  131. package/ts/driver/classes.directreports.ts +25 -6
  132. package/ts/driver/classes.driverservice.ts +75 -14
  133. package/ts/fleet/classes.claudeworkers.ts +112 -39
  134. package/ts/fleet/classes.codexworkers.ts +21 -6
  135. package/ts/fleet/classes.workercommand.ts +14 -4
  136. package/ts/fleet/classes.workers.ts +9 -2
  137. package/ts/fleet/functions.unbounddrivers.ts +1 -1
  138. package/ts/fleet/functions.workervalidation.ts +1 -1
  139. package/ts/fleet/interfaces.workers.ts +20 -5
  140. package/ts/functions.agentmessage.ts +3 -0
  141. package/ts/functions.deviceapi.ts +1071 -34
  142. package/ts/functions.fleetworkercli.ts +10 -7
  143. package/ts/functions.inferencecli.ts +2 -0
  144. package/ts/functions.mcpfleetworkertools.ts +1 -1
  145. package/ts/functions.ticketvalidation.ts +11 -1
  146. package/ts/interfaces.auth.ts +8 -0
  147. package/ts/plugins.ts +7 -0
  148. package/ts_authswitch/authority-contract.ts +20 -0
  149. package/ts_authswitch/authority-overview.ts +28 -6
  150. package/ts_authswitch/authority-placement.ts +25 -17
  151. package/ts_authswitch/authority-renewal.ts +64 -0
  152. package/ts_authswitch/classes.authoritybroker.ts +34 -1
  153. package/ts_authswitch/classes.authoritycli.ts +49 -2
  154. package/ts_authswitch/classes.authorityclient.ts +14 -4
  155. package/ts_authswitch/classes.authoritydaemon.ts +9 -1
  156. package/ts_authswitch/classes.authoritydatabase.ts +5 -1
  157. package/ts_authswitch/classes.authoritymodels.ts +23 -3
  158. package/ts_authswitch/native-contracts.md +21 -0
  159. package/ts_authswitch/readme.md +1 -1
  160. package/ts_interfaces/devices.schema.json +3573 -603
  161. package/ts_interfaces/devices.ts +1093 -4
  162. package/ts_interfaces/fleetworkers.ts +5 -3
  163. package/ts_interfaces/inbox.ts +287 -0
  164. package/ts_interfaces/index.ts +1 -0
  165. package/ts_interfaces/interfaces.ts +9 -2
  166. package/ts_interfaces/mcprequests.ts +43 -4
  167. package/ts_interfaces/mcpworkspacerequests.ts +4 -2
  168. package/ts_interfaces/nativesessions.ts +17 -3
  169. package/ts_interfaces/plugins.ts +3 -1
  170. package/ts_interfaces/requests.accounts.ts +20 -0
  171. package/ts_interfaces/requests.ts +4 -0
  172. package/ts_web/00_commitinfo_data.ts +1 -1
  173. package/ts_web/accounts.plugins.ts +4 -2
  174. package/ts_web/classes.accountsreadmodel.ts +33 -0
  175. package/ts_web/classes.browserpresentation.ts +10 -5
  176. package/ts_web/classes.inboxfeed.ts +329 -0
  177. package/ts_web/classes.nativesessionstate.ts +9 -23
  178. package/ts_web/elements.accounts.ts +81 -0
  179. package/ts_web/elements.deployments.ts +66 -2
  180. package/ts_web/elements.harnesscontrollerapp.ts +107 -37
  181. package/ts_web/elements.inbox.ts +808 -0
  182. package/ts_web/functions.inbox.ts +95 -0
  183. package/ts_web/functions.sessioncards.ts +40 -0
  184. package/ts_web/plugins.ts +2 -0
@@ -200,6 +200,12 @@ export class ControllerDevices {
200
200
  .map((recordArg) => this.view(recordArg));
201
201
  }
202
202
 
203
+ /** One paired device, while it is paired. */
204
+ public get(deviceIdArg: string): IControllerDevice | undefined {
205
+ const record = this.records.get(deviceIdArg);
206
+ return record === undefined ? undefined : this.view(record);
207
+ }
208
+
203
209
  private view(recordArg: IControllerDeviceDocument): IControllerDevice {
204
210
  return {
205
211
  id: recordArg.id,
@@ -0,0 +1,239 @@
1
+ import {
2
+ compareControllerInboxItems,
3
+ controllerInboxLimits,
4
+ type IControllerEvent,
5
+ type IControllerInboxSnapshot,
6
+ type TControllerInboxDelta,
7
+ type TControllerInboxItem,
8
+ } from '../ts_interfaces/index.js';
9
+ import { PublishedSet } from './classes.publishedset.js';
10
+
11
+ /**
12
+ * Where the Inbox's items come from, each read as a unit: the requests the Claude Code and Codex harnesses hold (their
13
+ * conversations' and the native sessions' AGL runs turns in), the OpenCode and Flex conversations' requests, the waits
14
+ * harnesses show in their own clients, the driver's `needs input:` turn, and the board's open questions.
15
+ */
16
+ export type TInboxSource = 'claude' | 'codex' | 'opencode' | 'flex' | 'native_waits' | 'driver' | 'tickets';
17
+ export const inboxSources: readonly TInboxSource[] = ['claude', 'codex', 'opencode', 'flex', 'native_waits', 'driver', 'tickets'];
18
+ const sessionSources: readonly TInboxSource[] = ['claude', 'codex', 'opencode', 'flex', 'native_waits'];
19
+
20
+ /** The reads the Inbox merges; the controller binds them to its harnesses, session feed, driver and board. */
21
+ export interface IInboxSources {
22
+ /**
23
+ * The items `sourceArg` holds now. `previousArg` are the source's items of the last read, for a source that keeps
24
+ * the part of them a failed partial read could not renew. A read that fails keeps the source's previous items.
25
+ */
26
+ read(sourceArg: TInboxSource, previousArg: readonly TControllerInboxItem[], signalArg: AbortSignal): Promise<TControllerInboxItem[]>;
27
+ /** Whether a browser or a device receives controller events; without one the Inbox only marks its sources stale. */
28
+ hasViewers(): Promise<boolean>;
29
+ publish(deltaArg: TControllerInboxDelta): void;
30
+ reportError(messageArg: string, errorArg: unknown): void;
31
+ }
32
+
33
+ export interface IInboxOptions {
34
+ /** Event bursts coalesce: a pass reads `debounceMs` after the newest event, at most `maxDebounceMs` after the first. */
35
+ debounceMs?: number;
36
+ maxDebounceMs?: number;
37
+ }
38
+
39
+ /** One line of at most `controllerInboxLimits.titleChars` characters, its end marked when it was cut. */
40
+ export const inboxTitle = (textArg: string): string => {
41
+ const line = textArg.replace(/\s+/gu, ' ').trim();
42
+ const characters = [...line];
43
+ return characters.length <= controllerInboxLimits.titleChars
44
+ ? line
45
+ : `${characters.slice(0, controllerInboxLimits.titleChars - 1).join('').trimEnd()}…`;
46
+ };
47
+
48
+ const itemBytes = (itemArg: TControllerInboxItem): number => Buffer.byteLength(JSON.stringify(itemArg), 'utf8');
49
+
50
+ /**
51
+ * An item within `controllerInboxLimits.itemBytes`: one over it keeps its place, kind, title and where it lives, and
52
+ * leaves its payload out with the marker `omitted`; it is then answered only where it lives. Nothing is cut short.
53
+ */
54
+ export const boundInboxItem = (itemArg: TControllerInboxItem): TControllerInboxItem => {
55
+ const bytes = itemBytes(itemArg);
56
+ if (bytes <= controllerInboxLimits.itemBytes) return itemArg;
57
+ const omitted = { reason: 'oversize' as const, bytes };
58
+ switch (itemArg.kind) {
59
+ case 'permission': { const { permission: _payload, ...item } = itemArg; return { ...item, answer: 'none', omitted }; }
60
+ case 'question': { const { question: _payload, ...item } = itemArg; return { ...item, answer: 'none', omitted }; }
61
+ case 'elicitation': { const { elicitation: _payload, ...item } = itemArg; return { ...item, answer: 'none', omitted }; }
62
+ case 'driver': { const { line: _payload, ...item } = itemArg; return { ...item, answer: 'none', omitted }; }
63
+ case 'deploy_go': { const { question: _payload, ...item } = itemArg; return { ...item, answer: 'none', omitted }; }
64
+ case 'window_go': { const { question: _payload, ...item } = itemArg; return { ...item, answer: 'none', omitted }; }
65
+ case 'ticket_question': { const { question: _payload, ...item } = itemArg; return { ...item, answer: 'none', omitted }; }
66
+ case 'native_wait': return { ...itemArg, omitted };
67
+ }
68
+ };
69
+
70
+ /**
71
+ * The Inbox (AGL-1635): one list of what waits for the owner, kept in memory and published to browsers and devices as
72
+ * deltas. Nothing is stored: every item is read from the component that owns it, so an answer anywhere removes it.
73
+ *
74
+ * Events mark the sources they concern stale; a pass reads only the stale ones, coalesced, and only while a browser
75
+ * or a device is connected. `list()` reads every stale source first.
76
+ */
77
+ export class ControllerInbox {
78
+ private readonly abort = new AbortController();
79
+ private readonly published = new PublishedSet<TControllerInboxItem>(controllerInboxLimits.deltaItems);
80
+ private readonly items = new Map<TInboxSource, TControllerInboxItem[]>();
81
+ private readonly stale = new Set<TInboxSource>(inboxSources);
82
+ private readonly debounceMs: number;
83
+ private readonly maxDebounceMs: number;
84
+ private total = 0;
85
+ private limited = false;
86
+ /** The last failure each source reported, so a lasting one is reported once. */
87
+ private readonly errors = new Map<TInboxSource, string>();
88
+ private timer?: ReturnType<typeof setTimeout>;
89
+ private firstPendingAt?: number;
90
+ /** Passes run one at a time, in order; a pass reads the sources stale when it starts. */
91
+ private tail: Promise<void> = Promise.resolve();
92
+
93
+ constructor(private readonly sources: IInboxSources, optionsArg: IInboxOptions = {}) {
94
+ this.debounceMs = optionsArg.debounceMs ?? 100;
95
+ this.maxDebounceMs = optionsArg.maxDebounceMs ?? 1_000;
96
+ }
97
+
98
+ /** The Inbox after reading every stale source. */
99
+ public async list(): Promise<IControllerInboxSnapshot> {
100
+ this.abort.signal.throwIfAborted();
101
+ await this.enqueuePass();
102
+ return { epoch: this.published.epoch, revision: this.published.revision, items: this.published.values(), total: this.total, limited: this.limited };
103
+ }
104
+
105
+ /** Called for every controller event: the ones that change what waits mark their sources stale. */
106
+ public observe(eventArg: IControllerEvent): void {
107
+ if (this.abort.signal.aborted) return;
108
+ switch (eventArg.type) {
109
+ case 'permissions.changed': {
110
+ const harness = eventArg.harnessId;
111
+ this.markStale(...(harness === 'claude' || harness === 'codex' || harness === 'opencode' || harness === 'flex' ? [harness] : sessionSources));
112
+ return;
113
+ }
114
+ case 'sessions.changed':
115
+ case 'harness.changed':
116
+ case 'projects.changed':
117
+ this.markStale(...sessionSources);
118
+ return;
119
+ // A feed row's group and name are what session items name and where they wait: the rows' harnesses read again.
120
+ case 'sessionfeed.changed': {
121
+ const delta = eventArg.sessionFeed;
122
+ if (!delta || 'reset' in delta) {
123
+ this.markStale(...sessionSources);
124
+ return;
125
+ }
126
+ const harnesses = new Set<string>([...delta.upserts.map((rowArg) => rowArg.harness),
127
+ ...delta.removed.map((rowIdArg) => rowIdArg.slice(0, rowIdArg.indexOf(':')))]);
128
+ this.markStale('native_waits', ...sessionSources.filter((sourceArg) => harnesses.has(sourceArg)));
129
+ return;
130
+ }
131
+ case 'driver.changed':
132
+ // The driver's own prompts are Flex permissions.
133
+ this.markStale('driver', 'flex');
134
+ return;
135
+ case 'tickets.changed':
136
+ case 'deployments.changed':
137
+ this.markStale('tickets');
138
+ return;
139
+ default:
140
+ return;
141
+ }
142
+ }
143
+
144
+ /** The requests a harness holds for a native session came or went (no controller event names those sessions). */
145
+ public nativeAttentionChanged(harnessArg: 'claude' | 'codex'): void {
146
+ this.markStale(harnessArg);
147
+ }
148
+
149
+ public markStale(...sourcesArg: TInboxSource[]): void {
150
+ if (this.abort.signal.aborted) return;
151
+ for (const source of sourcesArg) this.stale.add(source);
152
+ this.schedule();
153
+ }
154
+
155
+ /** Stops the timer and waits for the pass in flight, which sees the abort. */
156
+ public async close(): Promise<void> {
157
+ this.abort.abort();
158
+ if (this.timer) clearTimeout(this.timer);
159
+ this.timer = undefined;
160
+ await this.tail;
161
+ }
162
+
163
+ private schedule(): void {
164
+ const now = Date.now();
165
+ this.firstPendingAt ??= now;
166
+ const due = Math.min(now + this.debounceMs, this.firstPendingAt + this.maxDebounceMs);
167
+ if (this.timer) clearTimeout(this.timer);
168
+ this.timer = setTimeout(() => {
169
+ this.timer = undefined;
170
+ this.firstPendingAt = undefined;
171
+ void this.passIfViewed();
172
+ }, Math.max(0, due - now));
173
+ this.timer.unref?.();
174
+ }
175
+
176
+ /** A scheduled pass runs only while someone receives its changes; otherwise its sources stay stale for `list()`. */
177
+ private async passIfViewed(): Promise<void> {
178
+ let viewed: boolean;
179
+ try {
180
+ viewed = await this.sources.hasViewers();
181
+ } catch (errorArg) {
182
+ this.sources.reportError('Checking for Inbox viewers failed.', errorArg);
183
+ return;
184
+ }
185
+ if (viewed && !this.abort.signal.aborted) await this.enqueuePass();
186
+ }
187
+
188
+ private enqueuePass(): Promise<void> {
189
+ const pass = this.tail.then(() => this.pass());
190
+ this.tail = pass.catch((errorArg) => {
191
+ if (!this.abort.signal.aborted) this.sources.reportError('An Inbox pass failed.', errorArg);
192
+ });
193
+ return pass;
194
+ }
195
+
196
+ private async pass(): Promise<void> {
197
+ const signal = this.abort.signal;
198
+ signal.throwIfAborted();
199
+ const sources = inboxSources.filter((sourceArg) => this.stale.has(sourceArg));
200
+ for (const source of sources) this.stale.delete(source);
201
+ await Promise.all(sources.map(async (sourceArg) => {
202
+ try {
203
+ this.items.set(sourceArg, await this.sources.read(sourceArg, this.items.get(sourceArg) ?? [], signal));
204
+ this.errors.delete(sourceArg);
205
+ } catch (errorArg) {
206
+ signal.throwIfAborted();
207
+ // The source keeps what it held; its next change reads it again.
208
+ const message = errorArg instanceof Error ? errorArg.message : String(errorArg);
209
+ if (this.errors.get(sourceArg) === message) return;
210
+ this.errors.set(sourceArg, message);
211
+ this.sources.reportError(`Inbox: reading ${sourceArg} failed.`, errorArg);
212
+ }
213
+ }));
214
+ signal.throwIfAborted();
215
+ this.publish();
216
+ }
217
+
218
+ private publish(): void {
219
+ const unique = new Map<string, TControllerInboxItem>();
220
+ for (const item of [...this.items.values()].flat()) if (!unique.has(item.id)) unique.set(item.id, boundInboxItem(item));
221
+ const all = [...unique.values()].sort(compareControllerInboxItems);
222
+ const shown: TControllerInboxItem[] = [];
223
+ let bytes = 0;
224
+ for (const item of all) {
225
+ const size = itemBytes(item);
226
+ if (shown.length >= controllerInboxLimits.items || bytes + size > controllerInboxLimits.listBytes) break;
227
+ shown.push(item);
228
+ bytes += size;
229
+ }
230
+ const total = all.length;
231
+ const limited = shown.length < total;
232
+ const countsChanged = total !== this.total || limited !== this.limited;
233
+ this.total = total;
234
+ this.limited = limited;
235
+ const delta = this.published.publish(shown, countsChanged);
236
+ if (!delta) return;
237
+ this.sources.publish('reset' in delta ? delta : { ...delta, order: shown.map((itemArg) => itemArg.id), total, limited });
238
+ }
239
+ }
@@ -78,6 +78,11 @@ export interface IInferenceAccount {
78
78
  reserveLiftUntil: string | null;
79
79
  /** When the account's subscription ends (`IAuthSwitchAccount.lapsesAt`); `null` while it renews. */
80
80
  lapsesAt: string | null;
81
+ /**
82
+ * The anchor of a Claude sign-in's monthly renewal as its owner set it (`IAuthSwitchAccount.renewsAt`); `null`
83
+ * without one. Placement only: a window's usage counts as spent by the next renewal (`authSwitchPlacement`).
84
+ */
85
+ renewsAt: string | null;
81
86
  /**
82
87
  * An API key's monthly spend limit in micro-dollars (`IAuthSwitchAccount.spendLimitMicroUsd`); `null` without one,
83
88
  * and for a sign-in. It decides only whether a key whose spend the proxy holds no reading of may take work: one with
@@ -702,6 +707,11 @@ export interface IInferenceAccountStatus {
702
707
  lifecycle: plugins.authswitchPlacement.TAuthSwitchAccountLifecycle;
703
708
  /** When the account's subscription ends, or `null` while it renews. */
704
709
  lapsesAt: string | null;
710
+ /**
711
+ * The account's next renewal (`IInferenceAccount.renewsAt` rolled forward to the first one after now), or `null`
712
+ * without one. Placement ignores it while the account has a lapse date. A proxy of an earlier AGL reports none.
713
+ */
714
+ renewal?: plugins.authswitchRenewal.IAuthSwitchRenewal | null;
705
715
  /** The account's placement score in percent per hour (`IAuthSwitchPlacement.score`); `null` without a counted window. */
706
716
  placementScore: number | null;
707
717
  /**
@@ -933,7 +943,8 @@ const emptySelection = (accountsArg: number, pinnedArg: boolean): ISelectionStat
933
943
  /** An account's placement by the shared rule, on the reading the router holds for it. */
934
944
  const accountPlacement = (readingArg: plugins.authswitchAuthority.IAuthSwitchUsageSnapshot['reading'],
935
945
  accountArg: IInferenceAccount, nowArg: number): plugins.authswitchPlacement.IAuthSwitchPlacement =>
936
- plugins.authswitchPlacement.authSwitchPlacement(readingArg, accountArg.maxUsagePercent, accountArg.lapsesAt, nowArg, accountArg.reserveLiftUntil);
946
+ plugins.authswitchPlacement.authSwitchPlacement(readingArg, accountArg.maxUsagePercent, accountArg.lapsesAt,
947
+ accountArg.renewsAt, nowArg, accountArg.reserveLiftUntil);
937
948
 
938
949
  /** Model-preserving account selection. Refresh grants and native sign-ins remain the authority's. */
939
950
  export class InferenceRouter {
@@ -1954,7 +1965,9 @@ export class InferenceRouter {
1954
1965
  const placement = accountPlacement(limits?.limit ? held!.reading : null, account, now);
1955
1966
  const base = { id: account.id, label: account.label, provider: account.providerId, credential: account.credential,
1956
1967
  maxUsagePercent: account.maxUsagePercent, reserveLiftUntil: account.reserveLiftUntil, inFlight: this.active.get(account.id) ?? 0,
1957
- lifecycle: placement.lifecycle, lapsesAt: account.lapsesAt, placementScore: placement.score, placementRank: null,
1968
+ lifecycle: placement.lifecycle, lapsesAt: account.lapsesAt,
1969
+ renewal: plugins.authswitchRenewal.authSwitchRenewal(account.renewsAt, now),
1970
+ placementScore: placement.score, placementRank: null,
1958
1971
  lastResort: placement.eligibility === 'last_resort', claudeCode: account.claudeCode,
1959
1972
  readingSource: held?.observation ? 'headers' as const : held?.reading ? 'poll' as const : null,
1960
1973
  readingObservedAt: held?.reading ? held.observedAt : null,
@@ -159,7 +159,7 @@ export class InferenceService {
159
159
  const login = findAuthorityGatewayLogin(projection, account.id);
160
160
  return pool ? [{ id: account.id, label: account.label, revision: String(account.revision), providerId: pool.provider,
161
161
  credential: pool.credential, maxUsagePercent: account.maxUsagePercent, reserveLiftUntil: account.reserveLiftUntil, lapsesAt: account.lapsesAt,
162
- spendLimitMicroUsd: account.spendLimitMicroUsd, claudeCode: account.claudeCode, loginId: typeof login === 'string' ? null : login.id }] : [];
162
+ renewsAt: account.renewsAt, spendLimitMicroUsd: account.spendLimitMicroUsd, claudeCode: account.claudeCode, loginId: typeof login === 'string' ? null : login.id }] : [];
163
163
  });
164
164
  }
165
165
 
@@ -14,6 +14,7 @@ import type { IFleetDeployOperations, TFleetDeployOperation } from '../ts_interf
14
14
  import type { IReq_ControllerMcpSessionFeedAcknowledge, IReq_ControllerMcpSessionFeedList } from '../ts_interfaces/sessionfeed.js';
15
15
  import { isProxyCapacityAnswer, type IProxyCapacityAnswer, type IProxyCapacityRequest } from '../ts_interfaces/proxycapacity.js';
16
16
  import {
17
+ controllerMcpNativeDeliveries,
17
18
  controllerMcpSessionDetailFields,
18
19
  controllerMcpTypedResponseMaximumBytes,
19
20
  controllerPackageName,
@@ -67,6 +68,7 @@ import { compareUpgradeSemver } from './classes.upgradecoordinator.js';
67
68
  import {
68
69
  assertControllerMcpExactKeys,
69
70
  assertControllerMcpModelChoice,
71
+ assertControllerMcpNativeSession,
70
72
  assertControllerMcpResponseFields,
71
73
  assertControllerMcpRuntimeId,
72
74
  controllerMcpValueIsRecord,
@@ -98,6 +100,7 @@ export type TControllerMcpClientErrorCode =
98
100
  | 'CONCURRENT_CHANGE'
99
101
  | 'PROJECT_NOT_FOUND'
100
102
  | 'SESSION_NOT_FOUND'
103
+ | 'SESSION_READ_ONLY'
101
104
  | 'AMBIGUOUS_SESSION'
102
105
  | 'MODEL_NOT_FOUND'
103
106
  | 'JOB_NOT_FOUND'
@@ -376,8 +379,12 @@ const assertResponsePayload = (
376
379
  return;
377
380
  }
378
381
  if (methodArg === 'agl.mcp.sessions.list') {
379
- assertControllerMcpExactKeys(valueArg, ['sessions']);
380
- if (!Array.isArray(valueArg.sessions)) throw new Error('invalid');
382
+ assertControllerMcpExactKeys(valueArg, ['sessions', 'nativeSessions'], ['nativeSessionsTruncated', 'nativeSessionsError']);
383
+ if (!Array.isArray(valueArg.sessions) || !Array.isArray(valueArg.nativeSessions)
384
+ || (valueArg.nativeSessionsTruncated !== undefined && valueArg.nativeSessionsTruncated !== true)
385
+ || (valueArg.nativeSessionsError !== undefined && (typeof valueArg.nativeSessionsError !== 'string'
386
+ || valueArg.nativeSessions.length > 0 || valueArg.nativeSessionsTruncated !== undefined))) throw new Error('invalid');
387
+ valueArg.nativeSessions.forEach(assertControllerMcpNativeSession);
381
388
  return;
382
389
  }
383
390
  if (methodArg === 'agl.mcp.session.send') {
@@ -386,10 +393,15 @@ const assertResponsePayload = (
386
393
  return;
387
394
  }
388
395
  if (methodArg === 'agl.mcp.session.message') {
389
- assertControllerMcpExactKeys(valueArg, ['accepted', 'delivery'], ['turnId']);
396
+ assertControllerMcpExactKeys(valueArg, ['accepted', 'delivery'], ['turnId', 'native']);
390
397
  if (
391
398
  valueArg.accepted !== true
392
399
  || !['steer', 'next-turn', 'queue'].includes(valueArg.delivery as string)
400
+ || (valueArg.native !== undefined && (
401
+ (valueArg.native !== 'wake' && valueArg.native !== 'inbox')
402
+ || valueArg.delivery !== controllerMcpNativeDeliveries[valueArg.native]
403
+ || valueArg.turnId !== undefined
404
+ ))
393
405
  || (valueArg.turnId !== undefined && (
394
406
  typeof valueArg.turnId !== 'string'
395
407
  || valueArg.turnId.length === 0
@@ -406,6 +418,14 @@ const assertResponsePayload = (
406
418
  assertScratchpadResponse(valueArg.scratchpad);
407
419
  return;
408
420
  }
421
+ if (valueArg.kind === 'native') {
422
+ // A Claude Code session outside AGL: the session, its transcript page and its scratchpad.
423
+ assertControllerMcpExactKeys(valueArg, ['kind', 'session', 'messagePage', 'scratchpad']);
424
+ assertControllerMcpNativeSession(valueArg.session);
425
+ if (!controllerMcpValueIsRecord(valueArg.messagePage) || !Array.isArray(valueArg.messagePage.bundles)) throw new Error('invalid');
426
+ assertScratchpadResponse(valueArg.scratchpad);
427
+ return;
428
+ }
409
429
  assertControllerMcpResponseFields(valueArg, controllerMcpSessionDetailFields);
410
430
  if (!controllerMcpValueIsRecord(valueArg.session)) throw new Error('invalid');
411
431
  const sessionId = assertControllerMcpRuntimeId(valueArg.session.id);
@@ -986,6 +1006,7 @@ export class ControllerMcpClient {
986
1006
  if (serverCode === 'concurrent_change') code = 'CONCURRENT_CHANGE';
987
1007
  if (serverCode === 'project_not_found') code = 'PROJECT_NOT_FOUND';
988
1008
  if (serverCode === 'session_not_found') code = 'SESSION_NOT_FOUND';
1009
+ if (serverCode === 'session_read_only') code = 'SESSION_READ_ONLY';
989
1010
  if (serverCode === 'ambiguous_session') code = 'AMBIGUOUS_SESSION';
990
1011
  if (serverCode === 'model_not_found') code = 'MODEL_NOT_FOUND';
991
1012
  if (serverCode === 'outcome_unknown') code = 'OUTCOME_UNKNOWN';
@@ -315,6 +315,8 @@ const safeTypedResponseError = (
315
315
  rate_limited: 'The authenticated operation rate limit was reached.',
316
316
  project_not_found: 'The requested project is unavailable.',
317
317
  session_not_found: 'The requested session is unavailable.',
318
+ session_read_only: 'The session takes no message now; session_read names why.',
319
+ native_session_failed: 'The Claude Code session could not be reached, and nothing was sent; read the session before acting again.',
318
320
  ambiguous_session: 'The native ID exists on multiple connections; select its qualified AGL ID.',
319
321
  model_not_found: 'The selected model is unavailable.',
320
322
  browser_image_limit: 'The screenshot exceeds 512 KiB; request JPEG with lower quality.',
@@ -230,7 +230,7 @@ const workspaceToolDefinitions: IWorkspaceToolDefinition[] = [
230
230
  path: plugins.z.string().max(controllerWorkspaceMaximumPathBytes) }).strict(),
231
231
  readOnly: false, destructive: false },
232
232
  { name: 'context_resolve', method: 'agl.mcp.context.resolve',
233
- description: "Resolve an absolute project directory and optionally an existing native task. Accepts a raw Codex thread ID only when it uniquely resolves; returns the qualified AGL session ID. Does not take over a running task.",
233
+ description: "Resolve an absolute project directory and optionally an existing native task. Accepts a raw Codex thread ID only when it uniquely resolves; returns the qualified AGL session ID. A Claude Code session outside AGL in the project folder answers as nativeSession and is recorded nowhere. Does not take over a running task.",
234
234
  inputSchema: plugins.z.object({ directory: boundedNonblankString(4096, 'directory'), sessionId: runtimeIdSchema.optional() }).strict(), readOnly: false, destructive: false },
235
235
  { name: 'project_add', method: 'agl.mcp.project.create',
236
236
  description: "Register an existing project directory. Does not create directories.",
@@ -290,6 +290,7 @@ const safeClientMessages: Record<ControllerMcpClientError['code'], string> = {
290
290
  CONCURRENT_CHANGE: 'The task, resource or scratchpad changed; read its current state before acting again.',
291
291
  PROJECT_NOT_FOUND: 'The project is unavailable. Use projects_list or register its directory with project_add.',
292
292
  SESSION_NOT_FOUND: 'The task is unavailable in this project. Use sessions_list to select an active task.',
293
+ SESSION_READ_ONLY: 'The Claude Code session takes no message now; session_read names why (readOnly). Nothing was sent.',
293
294
  AMBIGUOUS_SESSION: 'The native ID exists on multiple connections. Use sessions_list and select its qualified AGL ID.',
294
295
  MODEL_NOT_FOUND: 'The selected model is unavailable. Use models_list for this task.',
295
296
  JOB_NOT_FOUND: 'The job is unavailable. Use jobs_list for this project.',
@@ -307,7 +308,7 @@ const safeClientMessages: Record<ControllerMcpClientError['code'], string> = {
307
308
  TURN_ENDED: 'The turn the message was to steer has ended; nothing was sent. Read the task before sending again.',
308
309
  AGENT_MESSAGES_DISABLED: 'The owner does not accept agent messages for this project.',
309
310
  MESSAGE_RATE_LIMITED: 'Too many messages to this task; wait at least a minute before sending another.',
310
- DELIVERY_UNSUPPORTED: 'The task cannot take this delivery: OpenCode cannot be steered, expectedTurnId applies only to a Codex steer, and steering a turn another Codex client runs requires expectedTurnId.',
311
+ DELIVERY_UNSUPPORTED: 'The task cannot take this delivery: OpenCode cannot be steered, expectedTurnId applies only to a Codex steer (never to a Claude Code session outside AGL), and steering a turn another Codex client runs requires expectedTurnId.',
311
312
  OUTCOME_UNKNOWN: 'The operation outcome is unknown; inspect current state before acting again.',
312
313
  PROXY_UNAVAILABLE: 'The AGL inference proxy is not running; its owner starts it with agl proxy service start.',
313
314
  PROXY_OUTDATED: 'The AGL inference proxy runs an older AGL release and does not answer capacity; its owner restarts it onto the installed AGL with agl proxy service stop, then agl proxy service start.',
@@ -468,7 +469,7 @@ export class AglMcpTools {
468
469
  {
469
470
  title: 'List project sessions',
470
471
  annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
471
- description: 'Discover OpenCode, Flex and Codex tasks from the project folder and configured connections, including tasks created outside AGL.',
472
+ description: 'Discover OpenCode, Flex and Codex tasks and AGL\'s own Claude Code conversations from the project folder and configured connections, including tasks created outside AGL (sessions), and the Claude Code sessions of the host\'s own Claude Code home that run in the project folder itself (nativeSessions: running ones first, all of them, then at most 50 settled ones, nativeSessionsTruncated when more may exist; nativeSessionsError when the Claude Code inventory could not be read). A native session names why it takes no message (readOnly) or how a background job takes one (jobDelivery: wake or inbox). Read or message it with sessionId { harnessId: claude, nativeId }.',
472
473
  inputSchema: plugins.z.object({
473
474
  projectId: boundedNonblankString(maximumIdentifierBytes, 'projectId'),
474
475
  }).strict(),
@@ -482,7 +483,7 @@ export class AglMcpTools {
482
483
  {
483
484
  title: 'Read an AGL session',
484
485
  annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
485
- description: 'Read the bounded current detail for one qualified AGL session.',
486
+ description: 'Read the bounded current detail for one qualified AGL session. A Claude Code session outside AGL (sessions_list nativeSessions) answers with kind native: the session with readOnly or jobDelivery, its newest transcript page and its scratchpad.',
486
487
  inputSchema: plugins.z.object({
487
488
  projectId: boundedNonblankString(maximumIdentifierBytes, 'projectId'),
488
489
  sessionId: runtimeIdSchema,
@@ -540,9 +541,13 @@ export class AglMcpTools {
540
541
  + 'next-turn makes it the next turn\'s input, queue runs it after every earlier message; each '
541
542
  + 'starts a turn when nothing runs. OpenCode cannot be steered. To steer a Codex turn, pass '
542
543
  + 'expectedTurnId from session_read codexActivity.turnId; steering a turn another Codex '
543
- + 'client runs requires it, and such a turn takes steers only. The result says how the '
544
- + 'message was delivered. The owner can refuse agent messages for a project, and sending '
545
- + 'is rate-limited. An OUTCOME_UNKNOWN result must not be retried automatically.',
544
+ + 'client runs requires it, and such a turn takes steers only. A Claude Code background '
545
+ + 'job outside AGL (sessions_list nativeSessions) takes it through Claude Code itself, '
546
+ + 'whatever the delivery: a settled job is woken with it (native wake, delivery next-turn), '
547
+ + 'a running one gets it in its inbox, accepted and queued, not yet read (native inbox, '
548
+ + 'delivery queue); a session with readOnly is refused with SESSION_READ_ONLY. The result '
549
+ + 'says how the message was delivered. The owner can refuse agent messages for a project, '
550
+ + 'and sending is rate-limited. An OUTCOME_UNKNOWN result must not be retried automatically.',
546
551
  inputSchema: plugins.z.object({
547
552
  projectId: boundedNonblankString(maximumIdentifierBytes, 'projectId'),
548
553
  sessionId: runtimeIdSchema,
@@ -354,6 +354,30 @@ export const assertControllerMcpWireCaller = (
354
354
 
355
355
  export const controllerMcpValueIsRecord = isRecord;
356
356
 
357
+ const nativeReadOnlyReasons = new Set(['running', 'unaddressable', 'notBackgroundJob', 'profileHome', 'directoryMissing',
358
+ 'projectConversation', 'fleetWorker', 'jobFailed', 'jobHeld']);
359
+ /**
360
+ * Holds a Claude Code session outside AGL as the MCP routes answer it (`IControllerNativeSession`): a host session, no
361
+ * profile, its directory, title and status, and either why it takes no message or how a background job takes one.
362
+ */
363
+ export const assertControllerMcpNativeSession = (valueArg: unknown): void => {
364
+ if (!isRecord(valueArg)) throw new Error('Invalid native session.');
365
+ assertExactKeys(valueArg, ['harness', 'nativeId', 'cwd', 'title', 'status'],
366
+ ['updatedAt', 'workerName', 'model', 'effort', 'readOnly', 'jobDelivery']);
367
+ if (valueArg.harness !== 'claude' || typeof valueArg.nativeId !== 'string' || valueArg.nativeId.length === 0
368
+ || typeof valueArg.cwd !== 'string' || typeof valueArg.title !== 'string'
369
+ || !['busy', 'idle', 'error'].includes(valueArg.status as string)
370
+ || (valueArg.updatedAt !== undefined && (typeof valueArg.updatedAt !== 'number' || !Number.isFinite(valueArg.updatedAt)))
371
+ || [valueArg.workerName, valueArg.model, valueArg.effort].some((field) => field !== undefined && typeof field !== 'string')
372
+ || (valueArg.jobDelivery !== undefined && valueArg.jobDelivery !== 'wake' && valueArg.jobDelivery !== 'inbox')
373
+ || (valueArg.readOnly !== undefined && valueArg.jobDelivery !== undefined)) throw new Error('Invalid native session.');
374
+ if (valueArg.readOnly !== undefined) {
375
+ if (!isRecord(valueArg.readOnly)) throw new Error('Invalid native session.');
376
+ assertExactKeys(valueArg.readOnly, ['reason', 'message']);
377
+ if (!nativeReadOnlyReasons.has(valueArg.readOnly.reason as string) || typeof valueArg.readOnly.message !== 'string') throw new Error('Invalid native session.');
378
+ }
379
+ };
380
+
357
381
  export const assertControllerMcpExactKeys = assertExactKeys;
358
382
 
359
383
  const fieldKindMatchers: Record<TControllerMcpFieldKind, (valueArg: unknown) => boolean> = {
@@ -497,13 +521,15 @@ export const assertControllerMcpWorkspaceResponse = (
497
521
  plugins.browserRuntime.validateAgentActionResult(valueArg.result);
498
522
  }
499
523
  } else if (methodArg === 'agl.mcp.context.resolve' || methodArg === 'agl.mcp.project.create') {
500
- assertExactKeys(valueArg, ['project'], methodArg === 'agl.mcp.context.resolve' ? ['session'] : []);
524
+ assertExactKeys(valueArg, ['project'], methodArg === 'agl.mcp.context.resolve' ? ['session', 'nativeSession'] : []);
501
525
  if (!isRecord(valueArg.project) || typeof valueArg.project.id !== 'string'
502
526
  || typeof valueArg.project.directory !== 'string') throw new Error('Invalid project response.');
527
+ if (valueArg.session !== undefined && valueArg.nativeSession !== undefined) throw new Error('Invalid session response.');
503
528
  if (valueArg.session !== undefined) {
504
529
  if (!isRecord(valueArg.session)) throw new Error('Invalid session response.');
505
530
  assertControllerMcpRuntimeId(valueArg.session.id);
506
531
  }
532
+ if (valueArg.nativeSession !== undefined) assertControllerMcpNativeSession(valueArg.nativeSession);
507
533
  } else if (methodArg === 'agl.mcp.model.list') {
508
534
  assertExactKeys(valueArg, ['models', 'defaults', 'flexAccountPlacement'], ['codexContext']);
509
535
  if (!Array.isArray(valueArg.models) || !Array.isArray(valueArg.defaults)
@@ -3,6 +3,7 @@ import type { IFleetWorker } from '../ts_interfaces/fleetworkers.js';
3
3
  import type {
4
4
  IControllerNativeSession,
5
5
  IControllerNativeSessionRef,
6
+ TControllerNativeJobDelivery,
6
7
  TControllerNativeSessionReadOnlyReason,
7
8
  } from '../ts_interfaces/index.js';
8
9
  import type { IFleetNativeAgent, IFleetNativeSession, IFleetNativeThread } from './fleet/interfaces.workers.js';
@@ -34,14 +35,21 @@ export interface IResolvedNativeSession {
34
35
  scope: { profileId: string | null };
35
36
  worker?: IFleetWorker;
36
37
  /**
37
- * A Claude Code background job holds the session: a send wakes the job through Claude Code itself, never AGL's own
38
- * Claude Code, so the job stays its owner.
38
+ * A Claude Code background job holds the session: a send reaches the job through Claude Code itself, never AGL's own
39
+ * Claude Code, so the job stays its owner. It wakes a settled job, and goes into a running job's inbox.
39
40
  */
40
- claudeJob?: true;
41
+ claudeJob?: TControllerNativeJobDelivery;
42
+ /**
43
+ * For a running job's inbox: the fleet profile homes apart from the host's own, whose running sessions SendMessage
44
+ * reaches by name too; the send checks the job's name against them again at dispatch (`IFleetNativeSession.peerHomes`).
45
+ */
46
+ peerHomes?: string[];
41
47
  }
42
48
 
43
- const readOnlyMessages: Record<TControllerNativeSessionReadOnlyReason, string> = {
49
+ export const nativeSessionReadOnlyMessages: Record<TControllerNativeSessionReadOnlyReason, string> = {
44
50
  running: 'Another Claude Code process runs this session. AGL never becomes its second writer; the composer unlocks once it settles.',
51
+ unaddressable: 'This Claude Code background job runs, and Claude Code\'s SendMessage reaches a running job only by a session name no other running session shares; this one has no name or shares it. The composer unlocks once it settles.',
52
+ notBackgroundJob: 'This Claude Code session is no background job (`claude --bg`): agents reach only background jobs. The owner sends to it from its native session view in AGL.',
45
53
  profileHome: 'This session lives in a fleet profile\'s Claude Code home, which AGL\'s own Claude Code does not resume. It stays read-only here.',
46
54
  directoryMissing: 'The session\'s directory is missing, so nothing can resume it. It stays read-only.',
47
55
  projectConversation: 'An AGL project conversation holds this Claude Code session. Send to it from its project.',
@@ -124,11 +132,16 @@ export class NativeSessions {
124
132
  const cwd = agent?.cwd ?? boundWorker!.cwd;
125
133
  const own = home === undefined || samePath(home, this.sources.ownClaudeHome());
126
134
  const held = this.sources.claudeHeld(refArg.nativeId);
127
- const running = held === undefined && agent !== undefined
128
- && (agent.pid !== undefined || agent.state === 'working' || agent.status === 'busy');
129
135
  const job = agent?.kind === 'background';
130
- // A failed job is not woken unverified; one AGL's own Claude Code holds would be woken as a copy.
131
- const jobReason = !job ? undefined : agent.state === 'failed' ? 'jobFailed' as const : held ? 'jobHeld' as const : undefined;
136
+ // A running background job takes a message in its inbox, through Claude Code's own SendMessage: no second writer.
137
+ const inbox = job && held === undefined && agent.pid !== undefined && agent.status !== undefined
138
+ && agent.state !== 'failed' && agent.state !== 'stopped';
139
+ const running = held === undefined && agent !== undefined && !inbox
140
+ && (agent.pid !== undefined || agent.state === 'working' || agent.status === 'busy');
141
+ // A failed job is not woken unverified; one AGL's own Claude Code holds would be woken as a copy; SendMessage
142
+ // addresses a running job by a name no other running session of any listed home shares, never by a guess.
143
+ const jobReason = !job ? undefined : agent.state === 'failed' ? 'jobFailed' as const : held ? 'jobHeld' as const
144
+ : inbox && !await this.uniquelyNamed(agent, profiles) ? 'unaddressable' as const : undefined;
132
145
  const reason = await this.readOnlyReason(cwd, boundWorker, !own, running,
133
146
  own && await this.sources.claudeProjectConversation(refArg.nativeId), jobReason);
134
147
  const status: IControllerNativeSession['status'] = held
@@ -146,15 +159,40 @@ export class NativeSessions {
146
159
  status,
147
160
  ...(agent?.startedAt === undefined ? {} : { updatedAt: agent.startedAt }),
148
161
  ...this.workerFields(boundWorker),
149
- ...(reason === undefined ? {} : { readOnly: { reason, message: readOnlyMessages[reason] } }),
162
+ ...(reason === undefined ? {} : { readOnly: { reason, message: nativeSessionReadOnlyMessages[reason] } }),
163
+ ...(job && reason === undefined ? { jobDelivery: inbox ? 'inbox' as const : 'wake' as const } : {}),
150
164
  },
151
165
  native: { nativeId: refArg.nativeId, cwd, ...(own ? {} : { home }) },
152
166
  scope: { profileId: own ? null : scopeProfile ?? null },
153
167
  ...(boundWorker ? { worker: boundWorker } : {}),
154
- ...(job ? { claudeJob: true as const } : {}),
168
+ ...(job ? { claudeJob: inbox ? 'inbox' as const : 'wake' as const } : {}),
169
+ // A profile home's job is read-only (`profileHome`), so only an inbox of the host's own home is ever addressed.
170
+ ...(own && inbox ? { peerHomes: this.peerHomes(profiles) } : {}),
155
171
  };
156
172
  }
157
173
 
174
+ /**
175
+ * Whether the running session `agentArg` is the only running session of that name in the host's inventory and every
176
+ * fleet profile home's: Claude Code's SendMessage resolves a recipient by its name among the sessions it can reach.
177
+ */
178
+ private async uniquelyNamed(agentArg: IFleetNativeAgent, profilesArg: Array<{ profileId: string; home: string }>): Promise<boolean> {
179
+ if (!agentArg.name) return false;
180
+ let named = 0;
181
+ for (const home of [undefined, ...this.peerHomes(profilesArg)]) {
182
+ named += (await this.sources.claudeAgents(home)).filter((entry) => entry.pid !== undefined && entry.name === agentArg.name).length;
183
+ }
184
+ return named === 1;
185
+ }
186
+
187
+ /** The fleet profile homes apart from the host's own, each once. */
188
+ private peerHomes(profilesArg: Array<{ profileId: string; home: string }>): string[] {
189
+ const own = this.sources.ownClaudeHome(), homes: string[] = [];
190
+ for (const { home } of profilesArg) {
191
+ if (!samePath(home, own) && !homes.some((entry) => samePath(entry, home))) homes.push(home);
192
+ }
193
+ return homes;
194
+ }
195
+
158
196
  private async resolveCodex(refArg: IControllerNativeSessionRef): Promise<IResolvedNativeSession> {
159
197
  if (refArg.profileId !== undefined) throw nativeSessionNotFound();
160
198
  const [threads, worker] = await Promise.all([
@@ -174,7 +212,7 @@ export class NativeSessions {
174
212
  status: thread === undefined ? 'idle' : thread.status === 'busy' || thread.status === 'waiting' ? 'busy' : thread.status,
175
213
  ...(thread === undefined ? {} : { updatedAt: thread.updatedAt }),
176
214
  ...this.workerFields(worker),
177
- ...(reason === undefined ? {} : { readOnly: { reason, message: readOnlyMessages[reason] } }),
215
+ ...(reason === undefined ? {} : { readOnly: { reason, message: nativeSessionReadOnlyMessages[reason] } }),
178
216
  },
179
217
  native: { nativeId: refArg.nativeId, cwd },
180
218
  scope: { profileId: null },
@@ -193,7 +231,7 @@ export class NativeSessions {
193
231
  profileHomeArg: boolean,
194
232
  runningArg: boolean,
195
233
  projectConversationArg: boolean,
196
- jobArg?: 'jobFailed' | 'jobHeld',
234
+ jobArg?: 'jobFailed' | 'jobHeld' | 'unaddressable',
197
235
  ): Promise<TControllerNativeSessionReadOnlyReason | undefined> {
198
236
  if (!await this.sources.directoryExists(cwdArg)) return 'directoryMissing';
199
237
  if (projectConversationArg) return 'projectConversation';