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.
- package/changelog.md +11 -0
- package/dist_serve/bundle.js +1 -1
- package/dist_serve/bundle.js.map +1 -1
- package/dist_ts/00_commitinfo_data.js +1 -1
- package/dist_ts/classes.mcpcallerregistry.d.ts +11 -9
- package/dist_ts/classes.mcpcallerregistry.js +10 -8
- package/dist_ts/classes.opencodesupervisor.d.ts +1 -0
- package/dist_ts/classes.opencodesupervisor.js +5 -1
- package/dist_ts/classes.subtreecallers.d.ts +3 -2
- package/dist_ts/classes.subtreecallers.js +6 -5
- package/dist_ts/classes.terminalmanager.d.ts +8 -1
- package/dist_ts/classes.terminalmanager.js +8 -4
- package/dist_ts/classes.workercallers.js +7 -6
- package/dist_ts/functions.workerprocessproof.d.ts +12 -1
- package/dist_ts/functions.workerprocessproof.js +19 -7
- package/dist_ts/interfaces.opencode.d.ts +6 -0
- package/package.json +1 -1
- package/readme.md +1 -1
- package/ts/00_commitinfo_data.ts +1 -1
- package/ts/classes.mcpcallerregistry.ts +16 -11
- package/ts/classes.opencodesupervisor.ts +3 -0
- package/ts/classes.subtreecallers.ts +7 -6
- package/ts/classes.terminalmanager.ts +12 -3
- package/ts/classes.workercallers.ts +5 -4
- package/ts/functions.workerprocessproof.ts +24 -7
- package/ts/interfaces.opencode.ts +6 -0
- package/ts_web/00_commitinfo_data.ts +1 -1
|
@@ -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
|
-
*
|
|
15
|
-
* records the process
|
|
16
|
-
* inherits the credential, a daemon that leaves its
|
|
17
|
-
* process that still descends from
|
|
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
|
|
66
|
-
*
|
|
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 =
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
|
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,
|
|
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).
|
|
24
|
-
*
|
|
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:
|
|
28
|
-
try { child = await
|
|
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
|
-
|
|
394
|
-
//
|
|
395
|
-
//
|
|
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
|
-
|
|
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
|
-
|
|
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>;
|