agl 43.12.0 → 43.13.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.
@@ -11,10 +11,11 @@ import {
11
11
  * process is a controller child — terminals, the OpenCode server — so no credential can outlive
12
12
  * the controller generation that minted it, and nothing here belongs in persistence.
13
13
  *
14
- * A credential delivered through a spawn's environment (a terminal's, the OpenCode runtime's) also
15
- * records the process that spawn started once it runs (`bindProcess`): every process started under it
16
- * inherits the credential, a daemon that leaves its tree as well, so admission honours it only for a
17
- * process that still descends from it (AGL-1891, AGL-1972).
14
+ * Every credential `mint` makes is bound to a process subtree: the spawn that carries it in its
15
+ * environment (a terminal's, the OpenCode runtime's) records the process it started once it runs
16
+ * (`bindProcess`), every process started under it inherits the credential, a daemon that leaves its
17
+ * tree as well, and admission honours it only for a process that still descends from that record
18
+ * (AGL-1891, AGL-1972, AGL-1976). Only a fleet worker's credential (`mintWorker`) is proved otherwise.
18
19
  *
19
20
  * A credential is secret material. It never reaches audit records, error text, responses or logs:
20
21
  * only the derived {@link IControllerMcpCaller.auditPeerId} does, and that is a one-way digest.
@@ -62,13 +63,16 @@ export interface IControllerMcpCallerProcess {
62
63
  }
63
64
 
64
65
  /**
65
- * The subjects whose credential AGL writes into the environment of a process it spawns: a terminal's PTY child, the
66
- * OpenCode server. Every process started under that process inherits it, so it is bound to that process's subtree.
66
+ * The subjects a credential is bound to a process subtree for: every subject but the anonymous caller and a fleet
67
+ * worker, whose launch is proved against its own job. AGL writes such a credential into the environment of a process it
68
+ * spawns (today a terminal's PTY child and the OpenCode server), every process started under it inherits it, so it is
69
+ * honoured only inside that process's tree. A subject kind added later is bound so too unless it is excluded here
70
+ * (AGL-1976).
67
71
  */
68
- export type TControllerMcpSubtreeSubject = Extract<TControllerMcpSubject, { kind: 'terminal' | 'runtime' }>;
72
+ export type TControllerMcpSubtreeSubject = Exclude<TControllerMcpSubject, { kind: 'anonymous' | 'worker_launch' }>;
69
73
 
70
74
  export const isControllerMcpSubtreeSubject = (subjectArg: TControllerMcpSubject): subjectArg is TControllerMcpSubtreeSubject => (
71
- subjectArg.kind === 'terminal' || subjectArg.kind === 'runtime'
75
+ subjectArg.kind !== 'anonymous' && subjectArg.kind !== 'worker_launch'
72
76
  );
73
77
 
74
78
  interface ICallerEntry {
@@ -81,7 +85,8 @@ interface ICallerEntry {
81
85
  export class ControllerMcpCallerRegistry {
82
86
  private readonly callersByCredentialKey = new Map<string, ICallerEntry>();
83
87
 
84
- public mint(subjectArg: Exclude<TControllerMcpSubject, { kind: 'anonymous' | 'worker_launch' }>): string {
88
+ /** A credential honoured only inside the process subtree its spawn records with `bindProcess`, and for no process until then. */
89
+ public mint(subjectArg: TControllerMcpSubtreeSubject): string {
85
90
  return this.store(subjectArg);
86
91
  }
87
92
 
@@ -110,7 +115,7 @@ export class ControllerMcpCallerRegistry {
110
115
  /**
111
116
  * Records the process a spawn started with `credentialArg` in its environment (a terminal's PTY child, the OpenCode
112
117
  * server) as the root of the tree that credential is honoured inside (AGL-1891, AGL-1972). Until it is made, the
113
- * credential is honoured for no process; a revoked credential, or one of any other subject, records nothing.
118
+ * credential is honoured for no process; a revoked credential, or a fleet worker's, records nothing.
114
119
  */
115
120
  public bindProcess(credentialArg: string, processArg: IControllerMcpCallerProcess): void {
116
121
  const entry = this.callersByCredentialKey.get(credentialKey(credentialArg));
@@ -118,7 +123,7 @@ export class ControllerMcpCallerRegistry {
118
123
  entry.process = Object.freeze({ pid: processArg.pid, startTicks: processArg.startTicks });
119
124
  }
120
125
 
121
- /** The root process a subtree subject's credential is honoured inside, once its spawn recorded it; nothing for any other credential. */
126
+ /** The root process a subtree subject's credential is honoured inside, once its spawn recorded it; nothing for a fleet worker's or a revoked one. */
122
127
  public boundProcess(credentialArg: string): IControllerMcpCallerProcess | undefined {
123
128
  const entry = this.callersByCredentialKey.get(credentialKey(credentialArg));
124
129
  return entry && isControllerMcpSubtreeSubject(entry.caller.subject) ? entry.process : undefined;
@@ -610,6 +610,7 @@ export class OpenCodeSupervisor {
610
610
  private readonly onChildExitObserved?: () => void;
611
611
  private readonly mintCallerCredential?: () => string | undefined;
612
612
  private readonly recordCallerProcess?: IOpenCodeSupervisorOptions['recordCallerProcess'];
613
+ private readonly log: (lineArg: string) => void;
613
614
  private readonly onChildExit?: () => void;
614
615
 
615
616
  private state: IOpenCodeSupervisorStatus['state'] = 'stopped';
@@ -709,6 +710,7 @@ export class OpenCodeSupervisor {
709
710
  this.onChildExitObserved = options.onChildExitObserved;
710
711
  this.mintCallerCredential = options.mintCallerCredential;
711
712
  this.recordCallerProcess = options.recordCallerProcess;
713
+ this.log = options.log ?? ((lineArg) => console.warn(lineArg));
712
714
  this.onChildExit = options.onChildExit;
713
715
  this.password = plugins.crypto.randomBytes(32).toString('base64url');
714
716
  this.executablePath = this.resolveExecutablePath();
@@ -924,6 +926,7 @@ export class OpenCodeSupervisor {
924
926
  // Read right after the spawn, only as this controller's own child; a server that already exited records nothing.
925
927
  const server = await readControllerChildProcess(child.pid);
926
928
  if (server) this.recordCallerProcess({ credential: callerCredential, process: server });
929
+ else this.log(`The OpenCode server (PID ${child.pid}) could not be recorded as this controller's own child: its MCP calls are anonymous until its next start.`);
927
930
  }
928
931
 
929
932
  const deadline = Date.now() + this.startupTimeoutMs;
@@ -2,8 +2,8 @@ import {
2
2
  anonymousControllerMcpCaller, type ControllerMcpCallerRegistry, type IControllerMcpCallerProcess,
3
3
  } from './classes.mcpcallerregistry.js';
4
4
  import {
5
- isWorkerCallerProofRefusal, readWorkerProcessSnapshot, type proveConnectionProcessAncestry, type IWorkerCallerConnection,
6
- type IWorkerProcessSnapshot,
5
+ isWorkerCallerProofRefusal, readWorkerProcessIdentity, type proveConnectionProcessAncestry, type IWorkerCallerConnection,
6
+ type IWorkerProcessIdentity, type IWorkerProcessSnapshot,
7
7
  } from './functions.workerprocessproof.js';
8
8
  import type { IControllerMcpCaller } from '../ts_interfaces/index.js';
9
9
 
@@ -20,12 +20,13 @@ const sameProcess = (leftArg: IControllerMcpCallerProcess, rightArg: IController
20
20
  /**
21
21
  * The process a spawn whose environment carries a caller credential just started, read from the kernel right after the
22
22
  * spawn, only while it is this controller's own child: the root of the tree that credential is honoured inside
23
- * (AGL-1891, AGL-1972). Nothing for a child that already exited, or for a process another one started. Only an
24
- * unexpected failure to read it throws.
23
+ * (AGL-1891, AGL-1972). It is read by what `exec` leaves unchanged (PID, parent, start), never by its arguments or
24
+ * executable, which a PTY child may still be replacing when it is read (AGL-1995). Nothing for a child that already
25
+ * exited, or for a process another one started. Only an unexpected failure to read it throws.
25
26
  */
26
27
  export const readControllerChildProcess = async (pidArg: number): Promise<IControllerMcpCallerProcess | undefined> => {
27
- let child: IWorkerProcessSnapshot;
28
- try { child = await readWorkerProcessSnapshot(pidArg); } catch (errorArg) {
28
+ let child: IWorkerProcessIdentity;
29
+ try { child = await readWorkerProcessIdentity(pidArg); } catch (errorArg) {
29
30
  if (isWorkerCallerProofRefusal(errorArg)) return undefined;
30
31
  throw errorArg;
31
32
  }
@@ -143,6 +143,12 @@ export interface IControllerTerminalManagerOptions {
143
143
  credential: string;
144
144
  process: IControllerMcpCallerProcess;
145
145
  }) => void;
146
+ /**
147
+ * Takes the manager's own diagnostic lines (never terminal output): one when a start minted a caller credential but
148
+ * could not record its PTY child, so every MCP call through that credential is anonymous until the terminal starts
149
+ * again (AGL-1976). `console.warn` by default.
150
+ */
151
+ log?: (lineArg: string) => void;
146
152
  /**
147
153
  * Starts a Claude chat's use of the provider pool it runs on (`IControllerTerminalAgentMetadata.provider`) through
148
154
  * AGL's inference proxy. Without it, a chat on a pool does not start.
@@ -442,6 +448,7 @@ export class ControllerTerminalManager {
442
448
  private readonly ptySpawner: IControllerPtySpawner;
443
449
  private readonly resolveShell: () => Promise<IControllerTerminalShell>;
444
450
  private readonly cleanupTimeoutMs: number;
451
+ private readonly log: (lineArg: string) => void;
445
452
  private readonly outputRetryBackoffMs: readonly number[];
446
453
  private readonly entries = new Map<string, ITerminalEntry>();
447
454
  private readonly projectStates = new Map<string, IProjectAdmissionState>();
@@ -462,6 +469,7 @@ export class ControllerTerminalManager {
462
469
  });
463
470
  this.resolveShell = options.resolveShell ?? (() => resolveControllerTerminalShell());
464
471
  this.cleanupTimeoutMs = options.cleanupTimeoutMs ?? defaultCleanupTimeoutMs;
472
+ this.log = options.log ?? ((lineArg) => console.warn(lineArg));
465
473
  if (
466
474
  !Number.isSafeInteger(this.cleanupTimeoutMs)
467
475
  || this.cleanupTimeoutMs < 1
@@ -835,7 +843,7 @@ export class ControllerTerminalManager {
835
843
  }
836
844
  if (callerCredential !== undefined) {
837
845
  try {
838
- await this.recordCallerProcess(callerCredential, execution.ptyProcess.pid);
846
+ await this.recordCallerProcess(callerCredential, execution.ptyProcess.pid, inputArg.terminalNativeId);
839
847
  } catch (errorArg) {
840
848
  await this.closeEntry(createdEntry, Date.now() + this.cleanupTimeoutMs);
841
849
  throw errorArg;
@@ -848,12 +856,13 @@ export class ControllerTerminalManager {
848
856
  /**
849
857
  * Records this start's PTY child as the process its caller credential `credentialArg` is honoured inside (AGL-1891):
850
858
  * read once from the kernel right after the spawn, and only while it is this controller's own child. A child that
851
- * already exited is not recorded, which leaves the credential honoured for no process.
859
+ * already exited is not recorded, which leaves the credential honoured for no process, and says so in one line.
852
860
  */
853
- private async recordCallerProcess(credentialArg: string, pidArg: number): Promise<void> {
861
+ private async recordCallerProcess(credentialArg: string, pidArg: number, terminalNativeIdArg: string): Promise<void> {
854
862
  if (!this.options.recordCallerProcess) return;
855
863
  const child = await readControllerChildProcess(pidArg);
856
864
  if (child) this.options.recordCallerProcess({ credential: credentialArg, process: child });
865
+ else this.log(`The PTY child (PID ${pidArg}) of terminal ${terminalNativeIdArg} could not be recorded as this controller's own child: its MCP calls are anonymous until the terminal starts again.`);
857
866
  }
858
867
 
859
868
  /** OSC titles are untrusted display metadata: bounded, coalesced and never persisted. */
@@ -390,13 +390,14 @@ export class ControllerWorkerCallers implements IFleetWorkerCallerHooks {
390
390
  public async admit(wireArg: IControllerMcpWireCaller | undefined, connectionArg?: IWorkerCallerConnection): Promise<IWorkerCallerLease> {
391
391
  const caller = this.options.registry.resolve(wireArg?.credential);
392
392
  const release = () => undefined;
393
- // A terminal's or the OpenCode runtime's credential is inherited by every process started under the process its spawn
394
- // started, daemons that leave that tree too: it is honoured only for a bridge that runs inside the tree, proved for
395
- // this call (AGL-1891, AGL-1972).
393
+ if (caller.subject.kind === 'anonymous') return { caller: anonymousControllerMcpCaller, release };
394
+ // Every credential but a fleet worker's (a terminal's, the OpenCode runtime's, any kind added later) is inherited by
395
+ // every process started under the process its spawn started, daemons that leave that tree too: it is honoured only for
396
+ // a bridge that runs inside the tree, proved for this call, and never on the credential alone (AGL-1891, AGL-1972,
397
+ // AGL-1976).
396
398
  if (isControllerMcpSubtreeSubject(caller.subject)) {
397
399
  return { caller: wireArg ? await this.subtrees.admit(wireArg.credential, caller, connectionArg) : anonymousControllerMcpCaller, release };
398
400
  }
399
- if (caller.subject.kind !== 'worker_launch') return { caller, release };
400
401
  const subject = caller.subject;
401
402
  const record = this.launches.get(subject.launchId);
402
403
  const registered = record && [...record.credentials.values()].find(value => value.credential === wireArg?.credential);
@@ -19,10 +19,14 @@ export interface IWorkerCallerConnection {
19
19
  encrypted: boolean;
20
20
  }
21
21
 
22
- export interface IWorkerProcessSnapshot {
22
+ /** A process as `exec` leaves it: its PID, its parent and its start time in clock ticks. */
23
+ export interface IWorkerProcessIdentity {
23
24
  pid: number;
24
25
  parentPid: number;
25
26
  startTicks: string;
27
+ }
28
+
29
+ export interface IWorkerProcessSnapshot extends IWorkerProcessIdentity {
26
30
  executable: string;
27
31
  arguments: string[];
28
32
  }
@@ -33,7 +37,14 @@ export interface IWorkerBridgeCommand {
33
37
  arguments: string[];
34
38
  }
35
39
 
36
- export const readWorkerProcessSnapshot = async (pidArg: number): Promise<IWorkerProcessSnapshot> => {
40
+ /**
41
+ * A live process of the controller user, by what stays the same across `exec`: its PID, parent and start. Unlike
42
+ * {@link readWorkerProcessSnapshot} it reads no arguments, so it answers for a process in the middle of an `exec` too: from
43
+ * the moment the kernel installs the new program's memory until it has laid out that program's arguments,
44
+ * `/proc/<pid>/cmdline` reads empty. A child `forkpty` just started is often in exactly that window, because its parent
45
+ * returns without waiting for the `exec` (`child_process.spawn` waits for it) (AGL-1995).
46
+ */
47
+ export const readWorkerProcessIdentity = async (pidArg: number): Promise<IWorkerProcessIdentity> => {
37
48
  if (process.platform !== 'linux' || !Number.isSafeInteger(pidArg) || pidArg < 1) {
38
49
  throw new WorkerCallerProofError('Worker process attestation requires a live Linux process.');
39
50
  }
@@ -43,16 +54,22 @@ export const readWorkerProcessSnapshot = async (pidArg: number): Promise<IWorker
43
54
  if (['Z', 'X', 'x'].includes(fields[0]) || !/^\d+$/u.test(fields[19] ?? '')) {
44
55
  throw new WorkerCallerProofError('Worker process attestation failed.');
45
56
  }
46
- const argumentsBuffer = await plugins.fs.promises.readFile(`${root}/cmdline`);
47
- if (argumentsBuffer.length === 0 || argumentsBuffer.length > 256 * 1024) {
48
- throw new WorkerCallerProofError('Worker process arguments are unavailable.');
49
- }
50
57
  const status = await plugins.fs.promises.readFile(`${root}/status`, 'utf8');
51
58
  const user = /^Uid:\s+(\d+)\s+(\d+)/mu.exec(status);
52
59
  if (!user || Number(user[1]) !== process.getuid?.() || Number(user[2]) !== process.getuid?.()) {
53
60
  throw new WorkerCallerProofError('Worker process does not belong to the controller user.');
54
61
  }
55
- return { pid: pidArg, parentPid: Number(fields[1]), startTicks: fields[19],
62
+ return { pid: pidArg, parentPid: Number(fields[1]), startTicks: fields[19] };
63
+ };
64
+
65
+ export const readWorkerProcessSnapshot = async (pidArg: number): Promise<IWorkerProcessSnapshot> => {
66
+ const identity = await readWorkerProcessIdentity(pidArg);
67
+ const root = `/proc/${pidArg}`;
68
+ const argumentsBuffer = await plugins.fs.promises.readFile(`${root}/cmdline`);
69
+ if (argumentsBuffer.length === 0 || argumentsBuffer.length > 256 * 1024) {
70
+ throw new WorkerCallerProofError('Worker process arguments are unavailable.');
71
+ }
72
+ return { ...identity,
56
73
  executable: await plugins.fs.promises.readlink(`${root}/exe`),
57
74
  arguments: argumentsBuffer.toString('utf8').split('\0').filter(Boolean) };
58
75
  };
@@ -89,6 +89,12 @@ export interface IOpenCodeSupervisorOptions {
89
89
  credential: string;
90
90
  process: IControllerMcpCallerProcess;
91
91
  }) => void;
92
+ /**
93
+ * Takes the supervisor's own diagnostic lines (never the server's output, which `getLogSnapshot` keeps): one when a start
94
+ * minted a caller credential but could not record its server, so every MCP call through that credential is anonymous
95
+ * until the next start (AGL-1976). `console.warn` by default.
96
+ */
97
+ log?: (lineArg: string) => void;
92
98
  }
93
99
 
94
100
  export type TOpenCodeSdkClient = ReturnType<typeof plugins.opencodeSdk.createOpencodeClient>;
@@ -3,6 +3,6 @@
3
3
  */
4
4
  export const commitinfo = {
5
5
  name: 'agl',
6
- version: '43.12.0',
6
+ version: '43.13.0',
7
7
  description: 'Agent Gateway Layer for OpenCode, FlexHarness, and Codex sessions'
8
8
  }