@anhlp/alp-cli 0.0.0-beta.2 → 0.0.1-beta.10
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/THIRD-PARTY-NOTICES.txt +52 -2
- package/dist/acp/main.js +1 -1
- package/dist/acp.js +7802 -2239
- package/dist/alp-dashboard/THIRD-PARTY-NOTICES.txt +3256 -0
- package/dist/alp-dashboard/alp-boundary.json +16 -0
- package/dist/alp-dashboard/apple-touch-icon.png +0 -0
- package/dist/alp-dashboard/assets/TerminalPanel-D8HE9XBX.js +22 -0
- package/dist/alp-dashboard/assets/TerminalPanel-DLuoa74B.css +1 -0
- package/dist/alp-dashboard/assets/highlighter-BnicKQ_d.js +18 -0
- package/dist/alp-dashboard/assets/index-DwqDSiIi.css +1 -0
- package/dist/alp-dashboard/assets/index-YdtH3NBy.js +59 -0
- package/dist/alp-dashboard/favicon-attention.svg +6 -0
- package/dist/alp-dashboard/favicon-running.svg +6 -0
- package/dist/alp-dashboard/favicon.svg +5 -0
- package/dist/alp-dashboard/index.html +20 -0
- package/dist/alp-dashboard.js +10165 -0
- package/dist/alpd.js +39374 -17503
- package/dist/backup.js +2 -2
- package/dist/build-manifest.json +139 -3
- package/dist/cli.js +40 -6
- package/dist/daemon.d.ts +3 -3
- package/dist/daemon.js +16 -7
- package/dist/dashboard-migrate.d.ts +31 -0
- package/dist/dashboard-migrate.js +127 -0
- package/dist/dashboard-service.d.ts +69 -0
- package/dist/dashboard-service.js +141 -0
- package/dist/desktop.d.ts +56 -0
- package/dist/desktop.js +91 -0
- package/dist/interfaces.d.ts +23 -3
- package/dist/interfaces.js +277 -41
- package/dist/library.d.ts +16 -2
- package/dist/library.js +114 -7
- package/dist/paths.d.ts +6 -0
- package/dist/paths.js +4 -1
- package/dist/projects.js +2 -1
- package/dist/roles.d.ts +15 -0
- package/dist/roles.js +16 -0
- package/dist/schedules.d.ts +2 -0
- package/dist/schedules.js +45 -0
- package/dist/self-update.d.ts +151 -0
- package/dist/self-update.js +422 -0
- package/dist/sessions.d.ts +7 -2
- package/dist/sessions.js +44 -12
- package/dist/tasks.js +22 -8
- package/dist/terminal-native/README.md +201 -0
- package/dist/terminal-native/prebuilt/darwin-arm64/manifest.json +11 -0
- package/dist/terminal-native/prebuilt/darwin-arm64/terminal-owner +0 -0
- package/dist/terminal-native/prebuilt/darwin-x64/manifest.json +11 -0
- package/dist/terminal-native/prebuilt/darwin-x64/terminal-owner +0 -0
- package/dist/terminal-native/prebuilt/linux-arm64-glibc/manifest.json +10 -0
- package/dist/terminal-native/prebuilt/linux-arm64-glibc/terminal-owner +0 -0
- package/dist/terminal-native/prebuilt/linux-arm64-musl/manifest.json +10 -0
- package/dist/terminal-native/prebuilt/linux-arm64-musl/terminal-owner +0 -0
- package/dist/terminal-native/prebuilt/linux-x64-glibc/manifest.json +10 -0
- package/dist/terminal-native/prebuilt/linux-x64-glibc/terminal-owner +0 -0
- package/dist/terminal-native/prebuilt/linux-x64-musl/manifest.json +10 -0
- package/dist/terminal-native/prebuilt/linux-x64-musl/terminal-owner +0 -0
- package/dist/terminal-native/terminal-owner.c +389 -0
- package/dist/terminal.d.ts +13 -0
- package/dist/terminal.js +80 -0
- package/dist/usage.d.ts +1 -1
- package/dist/usage.js +31 -9
- package/package.json +11 -4
- package/src/backup.js +1 -1
- package/src/cli.js +51 -6
- package/src/daemon.js +18 -9
- package/src/dashboard-migrate.js +152 -0
- package/src/dashboard-service.js +192 -0
- package/src/desktop.js +122 -0
- package/src/interfaces.js +345 -38
- package/src/library.js +108 -9
- package/src/paths.js +9 -1
- package/src/projects.js +3 -1
- package/src/roles.js +26 -0
- package/src/schedules.js +38 -0
- package/src/self-update.js +443 -0
- package/src/sessions.js +44 -15
- package/src/tasks.js +22 -8
- package/src/terminal.js +78 -0
- package/src/usage.js +31 -9
package/dist/sessions.d.ts
CHANGED
|
@@ -7,9 +7,11 @@ export function answerer(client: any): {
|
|
|
7
7
|
close(): void;
|
|
8
8
|
};
|
|
9
9
|
/** Streams a tree until its root is idle; the first Ctrl-C interrupts it, the second detaches. */
|
|
10
|
-
export function follow(client: any, rootId: any, print: any, { untilIdle, interactive }: {
|
|
10
|
+
export function follow(client: any, rootId: any, print: any, { untilIdle, interactive, targetOnly, promptId }: {
|
|
11
11
|
untilIdle: any;
|
|
12
12
|
interactive?: boolean | undefined;
|
|
13
|
+
targetOnly?: boolean | undefined;
|
|
14
|
+
promptId: any;
|
|
13
15
|
}): Promise<any>;
|
|
14
16
|
export function run(args: any): Promise<void>;
|
|
15
17
|
export function ps(args: any): Promise<void>;
|
|
@@ -26,6 +28,8 @@ export function top(args: any): Promise<void>;
|
|
|
26
28
|
export function log(args: any): Promise<void>;
|
|
27
29
|
/** The project board every agent on the project shares: live claims, then decisions and findings. */
|
|
28
30
|
export function board(args: any): Promise<void>;
|
|
31
|
+
/** The models alpd offers now: the live catalog (t-e5ee); --refresh asks every provider again first. */
|
|
32
|
+
export function models(args: any): Promise<void>;
|
|
29
33
|
export function printPauses({ all, runtimes, parked }: {
|
|
30
34
|
all: any;
|
|
31
35
|
runtimes: any;
|
|
@@ -37,5 +41,6 @@ export function pause(args: any): Promise<void>;
|
|
|
37
41
|
export function resume(args: any): Promise<void>;
|
|
38
42
|
/** alp language: the language the user reads (ALPD §54); new sessions use it. */
|
|
39
43
|
export function recall(args: any): Promise<void>;
|
|
40
|
-
/** alp web: opens the web app alpd serves on 127.0.0.1, with the token in the address (ALPD §61). */
|
|
41
44
|
export function interrupt(args: any): Promise<void>;
|
|
45
|
+
/** alp compact <session>: compacts a root's context now, or at its next turn boundary (t-0e56). */
|
|
46
|
+
export function compact(args: any): Promise<void>;
|
package/dist/sessions.js
CHANGED
|
@@ -4,7 +4,7 @@ import path from "node:path";
|
|
|
4
4
|
import { createInterface } from "node:readline";
|
|
5
5
|
import { parseArgs } from "node:util";
|
|
6
6
|
import { ago, duration, renderLog, renderPs } from "@anhlp/alp-client/render";
|
|
7
|
-
import { isTaskId } from "@anhlp/alp-core/tasks";
|
|
7
|
+
import { AGENT_MARKER, isAgentProcess, isTaskId } from "@anhlp/alp-core/tasks";
|
|
8
8
|
import { connect } from "@anhlp/alp-client/index";
|
|
9
9
|
import { UsageError } from "./usage.js";
|
|
10
10
|
import { start, running, stop } from "./daemon.js";
|
|
@@ -121,7 +121,7 @@ function answerer(client) {
|
|
|
121
121
|
}
|
|
122
122
|
};
|
|
123
123
|
}
|
|
124
|
-
function follow(client, rootId, print, { untilIdle, interactive = false }) {
|
|
124
|
+
function follow(client, rootId, print, { untilIdle, interactive = false, targetOnly = false, promptId }) {
|
|
125
125
|
const answering = interactive ? answerer(client) : void 0;
|
|
126
126
|
const done = new Promise((resolve, reject) => {
|
|
127
127
|
let failed = false;
|
|
@@ -144,10 +144,13 @@ function follow(client, rootId, print, { untilIdle, interactive = false }) {
|
|
|
144
144
|
process.on("SIGINT", onSignal);
|
|
145
145
|
client.onClose((error) => {
|
|
146
146
|
process.off("SIGINT", onSignal);
|
|
147
|
+
answering?.close();
|
|
147
148
|
reject(error);
|
|
148
149
|
});
|
|
149
150
|
let rootEnded = false;
|
|
150
151
|
client.onEvent((envelope) => {
|
|
152
|
+
if (targetOnly && envelope.sessionId !== rootId) return;
|
|
153
|
+
if (promptId && envelope.event.type === "prompt.failed" && envelope.event.clientMessageId !== promptId) return;
|
|
151
154
|
print(envelope);
|
|
152
155
|
answering?.accept(envelope.event);
|
|
153
156
|
const { sessionId, event } = envelope;
|
|
@@ -234,28 +237,36 @@ async function attach(args) {
|
|
|
234
237
|
}
|
|
235
238
|
}
|
|
236
239
|
async function send(args) {
|
|
237
|
-
const { values, positionals: [sessionId, ...words] } = parseArgs({ args, allowPositionals: true, options: { json: { type: "boolean" } } });
|
|
240
|
+
const { values, positionals: [sessionId, ...words] } = parseArgs({ args, allowPositionals: true, options: { json: { type: "boolean" }, prompt: { type: "boolean" } } });
|
|
238
241
|
const text = words.join(" ").trim();
|
|
239
242
|
if (!sessionId || !text) throw new UsageError();
|
|
240
243
|
const client = await connect(await start(), { name: "alp-cli", version: "1" });
|
|
244
|
+
let subscriptionId;
|
|
241
245
|
try {
|
|
242
246
|
const { session } = await client.request("session.get", { sessionId });
|
|
243
|
-
if (session.parentId) {
|
|
247
|
+
if (session.parentId && !values.prompt) {
|
|
244
248
|
await client.request("session.message", { sessionId, text });
|
|
245
249
|
if (!values.json) console.error(`Sent to ${session.agent} as mail from the user`);
|
|
246
250
|
return;
|
|
247
251
|
}
|
|
248
|
-
const done = follow(client, sessionId, printer(values.json), { untilIdle: true, interactive: !values.json && process.stdin.isTTY });
|
|
249
252
|
const live = session.status === "idle" || session.status === "running";
|
|
250
|
-
if (live)
|
|
251
|
-
|
|
252
|
-
const
|
|
253
|
-
|
|
254
|
-
|
|
253
|
+
if (values.prompt && !live) throw new Error("Explicit prompts require a live session; use default alp send to reopen a root");
|
|
254
|
+
const clientMessageId = randomUUID();
|
|
255
|
+
const done = follow(client, sessionId, printer(values.json), { untilIdle: true, interactive: !values.json && process.stdin.isTTY, targetOnly: !!session.parentId, promptId: clientMessageId });
|
|
256
|
+
if (live) {
|
|
257
|
+
const attached = await client.request("session.attach", { sessionId, replay: false });
|
|
258
|
+
subscriptionId = attached.session.id;
|
|
259
|
+
} else {
|
|
260
|
+
await client.request("session.create", { sessionId, spec: { cwd: session.projectRoot } });
|
|
261
|
+
subscriptionId = sessionId;
|
|
262
|
+
}
|
|
263
|
+
const steer = !values.prompt && live && !!session.activeTurnId;
|
|
264
|
+
await client.request("session.prompt", { sessionId, clientMessageId, delivery: steer ? "steer" : "auto", content: [{ type: "text", text }] });
|
|
265
|
+
if (!values.json) console.error(values.prompt ? "Submitted an explicit prompt" : steer ? "Steered the running turn" : live ? "Started a turn" : "Resumed the session");
|
|
255
266
|
if (!await done) process.exitCode = 1;
|
|
256
|
-
await client.request("session.release", { sessionId }).catch(() => {
|
|
257
|
-
});
|
|
258
267
|
} finally {
|
|
268
|
+
if (subscriptionId) await client.request("session.release", { sessionId: subscriptionId }).catch(() => {
|
|
269
|
+
});
|
|
259
270
|
client.close();
|
|
260
271
|
}
|
|
261
272
|
}
|
|
@@ -282,6 +293,7 @@ async function answer(args) {
|
|
|
282
293
|
const { values, positionals: [questionId, ...words] } = parseArgs({ args, allowPositionals: true, options: { dismiss: { type: "boolean" }, reason: { type: "string" } } });
|
|
283
294
|
const text = words.join(" ").trim();
|
|
284
295
|
if (!questionId || (values.dismiss ? text : !text)) throw new UsageError();
|
|
296
|
+
if (isAgentProcess()) throw new Error(`Only the user answers a question; this process runs under an ALP agent (${AGENT_MARKER})`);
|
|
285
297
|
const client = await running();
|
|
286
298
|
const result = await client.request("question.answer", values.dismiss ? { questionId, dismiss: true, reason: values.reason } : { questionId, text }).finally(() => client.close());
|
|
287
299
|
console.log(`${values.dismiss ? "Dismissed" : "Answered"} ${result.questionId}`);
|
|
@@ -356,6 +368,18 @@ async function log(args) {
|
|
|
356
368
|
}
|
|
357
369
|
for (const line of renderLog(rootId, entries)) console.log(line);
|
|
358
370
|
}
|
|
371
|
+
async function models(args) {
|
|
372
|
+
const { values, positionals } = parseArgs({ args, allowPositionals: true, options: { refresh: { type: "boolean" }, json: { type: "boolean" } } });
|
|
373
|
+
if (positionals.length) throw new UsageError();
|
|
374
|
+
const client = await running();
|
|
375
|
+
const catalog = await client.request(values.refresh ? "catalog.refresh" : "catalog.get", {}).finally(() => client.close());
|
|
376
|
+
if (values.json) {
|
|
377
|
+
console.log(JSON.stringify(catalog));
|
|
378
|
+
return;
|
|
379
|
+
}
|
|
380
|
+
for (const [runtime, state] of Object.entries(catalog.providers ?? {})) console.log(`${runtime}: ${state.status}${state.fetchedAt ? ` (${state.fetchedAt})` : ""}${state.error ? ` \u2014 ${state.error}` : ""}`);
|
|
381
|
+
for (const model of catalog.models) console.log(`${model.id.padEnd(40)} ${model.label}`);
|
|
382
|
+
}
|
|
359
383
|
async function board(args) {
|
|
360
384
|
const { values, positionals } = parseArgs({ args, allowPositionals: true, options: { project: { type: "string" }, json: { type: "boolean" } } });
|
|
361
385
|
if (positionals.length) throw new UsageError();
|
|
@@ -424,14 +448,22 @@ async function interrupt(args) {
|
|
|
424
448
|
await client.request("session.interrupt", { sessionId: args[0] }).finally(() => client.close());
|
|
425
449
|
console.log("Interrupted");
|
|
426
450
|
}
|
|
451
|
+
async function compact(args) {
|
|
452
|
+
if (args.length !== 1) throw new UsageError();
|
|
453
|
+
const client = await running();
|
|
454
|
+
const { status } = await client.request("session.compact", { sessionId: args[0] }).finally(() => client.close());
|
|
455
|
+
console.log(status === "started" ? "Compacting: main writes a checkpoint, then its context is compacted" : status === "running" ? "A compaction is already running" : "Compaction queued for the next turn boundary");
|
|
456
|
+
}
|
|
427
457
|
export {
|
|
428
458
|
answer,
|
|
429
459
|
answerer,
|
|
430
460
|
attach,
|
|
431
461
|
board,
|
|
462
|
+
compact,
|
|
432
463
|
follow,
|
|
433
464
|
interrupt,
|
|
434
465
|
log,
|
|
466
|
+
models,
|
|
435
467
|
pause,
|
|
436
468
|
printPauses,
|
|
437
469
|
printer,
|
package/dist/tasks.js
CHANGED
|
@@ -6,9 +6,11 @@ import { parseArgs } from "node:util";
|
|
|
6
6
|
import { exportBeads, importBeads, parseJsonl } from "@anhlp/alp-core/beads";
|
|
7
7
|
import { findFormula, formulaDirs, listFormulas, pourFormula } from "@anhlp/alp-core/formulas";
|
|
8
8
|
import { describeVerification } from "@anhlp/alp-core/verify";
|
|
9
|
+
import { scriptCommand } from "@anhlp/alp-core/packaged";
|
|
9
10
|
import { ago } from "@anhlp/alp-client/render";
|
|
10
11
|
import { parse as toml } from "smol-toml";
|
|
11
|
-
import { addGate, blockersOf, checkGates, childrenOf, closeTask, compactTasks, createTask, describeGate, gateOpen, epicReport, gatesOf, linkTask, listTasks, loadTasks, readyTasks, reopenTask, resolveGate, summarize, TASKS_DIR, updateTask } from "@anhlp/alp-core/tasks";
|
|
12
|
+
import { addGate, blockersOf, checkGates, childrenOf, closeTask, compactTasks, createTask, describeGate, gateOpen, epicReport, gatesOf, linkTask, listTasks, loadTasks, readyTasks, rejectGate, reopenTask, resolveGate, summarize, TASKS_DIR, updateTask, isAgentProcess, AGENT_MARKER } from "@anhlp/alp-core/tasks";
|
|
13
|
+
import { AlpError } from "@anhlp/alp-core/errors";
|
|
12
14
|
import { alpHome } from "@anhlp/alp-client/index";
|
|
13
15
|
import { UsageError } from "./usage.js";
|
|
14
16
|
var STATUS_MARK = { open: "\u25CB", in_progress: "\u25D0", review: "\u25D1", closed: "\u25CF" };
|
|
@@ -62,7 +64,8 @@ async function tasksCommand(args) {
|
|
|
62
64
|
var gh = (args, { cwd }) => new Promise((resolve, reject) => {
|
|
63
65
|
const bin = process.env.ALP_GH_BIN ?? "gh";
|
|
64
66
|
const script = process.platform === "win32" && /\.[cm]?js$/i.test(bin);
|
|
65
|
-
const
|
|
67
|
+
const run = script ? scriptCommand(bin, args) : { command: bin, args };
|
|
68
|
+
const child = spawn(run.command, run.args, { cwd, ...run.env ? { env: { ...process.env, ...run.env } } : {}, stdio: ["ignore", "pipe", "pipe"] });
|
|
66
69
|
let stdout = "";
|
|
67
70
|
let stderr = "";
|
|
68
71
|
child.stdout.on("data", (chunk) => {
|
|
@@ -227,7 +230,9 @@ async function taskCommand([action, ...args]) {
|
|
|
227
230
|
human: { type: "string" },
|
|
228
231
|
timer: { type: "string" },
|
|
229
232
|
pr: { type: "string" },
|
|
230
|
-
run: { type: "string" }
|
|
233
|
+
run: { type: "string" },
|
|
234
|
+
option: repeated,
|
|
235
|
+
choice: { type: "string" }
|
|
231
236
|
} });
|
|
232
237
|
const root = await taskProject(values.project);
|
|
233
238
|
const fields = {
|
|
@@ -266,7 +271,7 @@ async function taskCommand([action, ...args]) {
|
|
|
266
271
|
task = await updateTask(root, positionals[0], { ...fields, ...values.title !== void 0 ? { title: values.title } : {}, note: values.message }, "user");
|
|
267
272
|
} else if (action === "close") {
|
|
268
273
|
if (positionals.length !== 1) throw new UsageError();
|
|
269
|
-
task = await closeTask(root, positionals[0], { reason: values.reason, summary: values.message, unverified: values.unverified }, "user");
|
|
274
|
+
task = await closeTask(root, positionals[0], { reason: values.reason, summary: values.message, unverified: values.unverified, agent: isAgentProcess(), channel: "cli" }, "user");
|
|
270
275
|
} else if (action === "reopen") {
|
|
271
276
|
if (positionals.length !== 1) throw new UsageError();
|
|
272
277
|
task = await reopenTask(root, positionals[0], { note: values.message }, "user");
|
|
@@ -278,11 +283,20 @@ async function taskCommand([action, ...args]) {
|
|
|
278
283
|
} else if (action === "gate") {
|
|
279
284
|
const [change, id, gate, ...rest] = positionals;
|
|
280
285
|
const kinds = ["human", "timer", "pr", "run"].filter((kind) => values[kind] !== void 0);
|
|
286
|
+
if (["clear", "reject", "rm"].includes(change) && id && gate && isAgentProcess()) {
|
|
287
|
+
const { tasks: current } = await loadTasks(root);
|
|
288
|
+
if (current.find((entry) => entry.id === id)?.gates.find((entry) => entry.id === gate)?.kind === "human") throw new AlpError("GATE_USER_ONLY", `Only the user clears a human gate; this process runs under an ALP agent (${AGENT_MARKER}). Ask the user to decide it`);
|
|
289
|
+
}
|
|
281
290
|
if (change === "add" && id && !gate && kinds.length === 1) {
|
|
282
291
|
const kind = kinds[0];
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
292
|
+
if (values.option && kind !== "human") throw new UsageError();
|
|
293
|
+
task = await addGate(root, id, kind === "human" ? { kind, note: values.human, ...values.option ? { options: values.option } : {} } : kind === "timer" ? { kind, until: values.timer } : { kind: `gh:${kind}`, ref: values[kind] }, "user");
|
|
294
|
+
} else if (change === "clear" && id && gate && !rest.length && !kinds.length && !values.option) {
|
|
295
|
+
task = await resolveGate(root, id, gate, { by: "user", note: values.message, channel: "cli", ...values.choice !== void 0 ? { choice: values.choice } : {} });
|
|
296
|
+
} else if (change === "reject" && id && gate && !rest.length && !kinds.length && !values.option && values.choice === void 0) {
|
|
297
|
+
task = await rejectGate(root, id, gate, { by: "user", reason: values.message, channel: "cli" });
|
|
298
|
+
} else if (change === "rm" && id && gate && !rest.length && !kinds.length && !values.option && values.choice === void 0) {
|
|
299
|
+
task = await resolveGate(root, id, gate, { by: "user", note: values.message, remove: true, channel: "cli" });
|
|
286
300
|
} else {
|
|
287
301
|
throw new UsageError();
|
|
288
302
|
}
|
|
@@ -314,7 +328,7 @@ function printTask(task, tasks) {
|
|
|
314
328
|
task.related.length && `related ${task.related.join(", ")}`
|
|
315
329
|
].filter(Boolean);
|
|
316
330
|
if (relations.length) console.log(` ${relations.join("; ")}`);
|
|
317
|
-
for (const gate of task.gates) console.log(` ${gateOpen(gate) ? "\u23F8" : "\u2713"} gate ${describeGate(gate)}${gate.resolved ? ` (cleared by ${gate.resolved.by}${gate.resolved.note ? `: ${gate.resolved.note}` : ""})` : ""}`);
|
|
331
|
+
for (const gate of task.gates) console.log(` ${gateOpen(gate) ? "\u23F8" : "\u2713"} gate ${describeGate(gate)}${gate.resolved ? ` (cleared by ${gate.resolved.by}${gate.resolved.choice ? ` with "${gate.resolved.choice}"` : ""}${gate.resolved.channel ? ` in ${gate.resolved.channel}` : ""}${gate.resolved.note ? `: ${gate.resolved.note}` : ""})` : gate.rejected ? ` (rejected by ${gate.rejected.by}${gate.rejected.reason ? `: ${gate.rejected.reason}` : ""})` : ""}${gateOpen(gate) && gate.options ? ` options: ${gate.options.join(" | ")}` : ""}${gate.tampered ? " \u26A0 changed outside ALP (a task file edit cleared or removed it); reopened for you to decide" : ""}`);
|
|
318
332
|
const inherited = gatesOf(task, tasks).filter((label) => label.startsWith("t-"));
|
|
319
333
|
if (task.status !== "closed" && inherited.length) console.log(` waits on its parent's gates: ${inherited.join("; ")}`);
|
|
320
334
|
if (task.compacted) console.log(` compacted ${task.compacted.at.slice(0, 10)} from ${task.compacted.chars} characters`);
|
|
@@ -0,0 +1,201 @@
|
|
|
1
|
+
# Terminal native owner — candidate, platform matrix incomplete
|
|
2
|
+
|
|
3
|
+
Task t-d71b. Production `src/terminals.ts` now uses this identity-bound owner,
|
|
4
|
+
with no node-pty fallback on macOS or Linux. Linux may use the best-effort root-only mode described below;
|
|
5
|
+
Windows has no protection helper and uses node-pty (ConPTY), best-effort (see "Windows" below). This candidate is NOT accepted for release:
|
|
6
|
+
actual Linux (beyond CI capability checks) and Windows evidence remain missing. Missing or
|
|
7
|
+
unverifiable backends refuse terminal capability explicitly (no plain-PTY fallback on Linux); on Linux a verified helper without full protection (any reason) offers root-only compatibility (best-effort, user decision 2026-10-29). No end-user compiler
|
|
8
|
+
is required. Existing session authentication and host/Paseo opt-ins still apply.
|
|
9
|
+
|
|
10
|
+
## Protocol and lifetime
|
|
11
|
+
|
|
12
|
+
One standalone C process owns forkpty, the startup gate, every signal and root
|
|
13
|
+
wait/reap. JS sends terminal input on stdin and resize (`R cols rows\n`) / cleanup
|
|
14
|
+
(`C\n`) on fd4. PTY output is stdout; fd3 contains bounded JSON ready, root-exit,
|
|
15
|
+
and cleanup records. Input/output queues and identity storage are bounded. Resizes coalesce behind
|
|
16
|
+
writable backpressure; cleanup closes the control pipe immediately. Native startup
|
|
17
|
+
polls the handshake/control descriptors with a 3s deadline; failure closes the
|
|
18
|
+
gate and attempts only identity-bound cleanup with a bounded nonblocking reap.
|
|
19
|
+
|
|
20
|
+
The child reports `getsid(0)==getpid()` before the parent releases its startup
|
|
21
|
+
gate. The owner acquires root identity before release, has default SIGCHLD and no
|
|
22
|
+
other reaper, and uses waitid(WNOWAIT) to observe natural exit. It retains the
|
|
23
|
+
root's live process or zombie until all discovery/signaling ends. This reserves
|
|
24
|
+
the root PID and prevents unrelated sessions reusing that session number. Only
|
|
25
|
+
processes proven to belong to that reserved session can be discovered. Observed
|
|
26
|
+
identities remain authorized if they subsequently leave the session. On the full-protection path there is no
|
|
27
|
+
marker, environment, age, PPid, parentuniqueid, TTY, numeric PID signal or numeric
|
|
28
|
+
group signal fallback. Never-observed children that immediately detach can be
|
|
29
|
+
missed (the approved g3 limit).
|
|
30
|
+
|
|
31
|
+
Linux opens a proc TGID directory with O_RDONLY|O_DIRECTORY (not O_PATH), reads
|
|
32
|
+
stat relative to that SAME descriptor, and uses pidfd_send_signal on that fd with
|
|
33
|
+
flags0/infoNULL. Capability probing checks kernel procfs and that /proc/self PID
|
|
34
|
+
and SID match the caller's namespace coordinates, and requires /proc/self/status
|
|
35
|
+
NSpid to have exactly one field equal to getpid() (proves the procfs PID namespace
|
|
36
|
+
is our active one without reading PID1, so it works for non-root users; missing
|
|
37
|
+
NSpid denies). A mount-privileged actor remounting /proc is outside this guarantee;
|
|
38
|
+
failure denies capability. Linux source has NOT been
|
|
39
|
+
compiled or executed here; permission/race/namespace/minimum-kernel evidence is
|
|
40
|
+
still required.
|
|
41
|
+
|
|
42
|
+
Darwin validates the complete private flavor17 56-byte struct and audit-token
|
|
43
|
+
version at runtime. Discovery uses U_before → reserved getsid → audit token →
|
|
44
|
+
U_after, requiring equal uniqueids and a matching token pidversion. Signals
|
|
45
|
+
refresh only a previously known uniqueid and use proc_signal_with_audittoken.
|
|
46
|
+
Unknown/changed identity never authorizes a numeric signal. Cleanup reports
|
|
47
|
+
observed/live/uncertain separately; it does not claim universal containment.
|
|
48
|
+
|
|
49
|
+
## Accepted finite-generation Darwin limit
|
|
50
|
+
|
|
51
|
+
The Darwin final syscall compares PID + **32-bit global pidversion**, not the
|
|
52
|
+
64-bit private uniqueid. Fork AND exec increment this global generation. If the
|
|
53
|
+
helper is suspended after its last identity check, enough global allocations can
|
|
54
|
+
wrap that generation and a recycled target PID can collide. Keeping a task-name
|
|
55
|
+
port or checking uniqueid again does not atomically bind the eventual syscall.
|
|
56
|
+
This is a source-derived limitation, not an executed 2^32-operation exploit.
|
|
57
|
+
The user explicitly accepted ONLY this residual in g4 (2026-10-29); ordinary PID
|
|
58
|
+
reuse protection, all native checks, packaging, platform tests and independent
|
|
59
|
+
review remain required. No blanket no-wrong-process waiver is inferred.
|
|
60
|
+
|
|
61
|
+
Kernel proof anchors (oracle 275c5e36, advice only; not implementation review):
|
|
62
|
+
|
|
63
|
+
- [XNU PID/zombie/session reservation and fork generations](https://github.com/apple-oss-distributions/xnu/blob/xnu-11215.1.10/bsd/kern/kern_fork.c#L877)
|
|
64
|
+
- [XNU WNOWAIT and reap hash removal](https://github.com/apple-oss-distributions/xnu/blob/xnu-11215.1.10/bsd/kern/kern_exit.c#L2457)
|
|
65
|
+
- [XNU setsid and cross-session restrictions](https://github.com/apple-oss-distributions/xnu/blob/xnu-11215.1.10/bsd/kern/kern_prot.c#L245)
|
|
66
|
+
- [XNU identity-info and final audit signal comparison](https://github.com/apple-oss-distributions/xnu/blob/xnu-11215.1.10/bsd/kern/proc_info.c#L3290)
|
|
67
|
+
- [XNU exec increments generation](https://github.com/apple-oss-distributions/xnu/blob/xnu-11215.1.10/bsd/kern/kern_exec.c#L6475)
|
|
68
|
+
- [Private ABI layout](https://github.com/apple-oss-distributions/xnu/blob/xnu-12377.1.9/bsd/sys/proc_info_private.h#L41)
|
|
69
|
+
- [Linux stored proc-directory identity](https://github.com/torvalds/linux/blob/v6.12/fs/proc/base.c#L3244)
|
|
70
|
+
- [Linux procdirfd signal dispatch](https://github.com/torvalds/linux/blob/v6.12/kernel/signal.c#L3647)
|
|
71
|
+
- [Linux stat session coordinates](https://github.com/torvalds/linux/blob/v6.12/fs/proc/array.c#L505)
|
|
72
|
+
|
|
73
|
+
## Build, distribution and remaining platform evidence
|
|
74
|
+
|
|
75
|
+
`node scripts/build-terminal-native.mjs` is an EXPLICIT developer build, never
|
|
76
|
+
terminal startup or postinstall. Darwin also accepts `--arch=x64`/`--arch=arm64`
|
|
77
|
+
using the existing Apple compiler and ad-hoc codesign; capability execution must
|
|
78
|
+
succeed before a manifest is written. Hashes bind protocol, source and binary.
|
|
79
|
+
`node scripts/terminal-native-assets.mjs --require-matrix` and release pack-check
|
|
80
|
+
FAIL until all six slots exist: Darwin arm64/x64, Linux arm64/x64 × glibc/musl.
|
|
81
|
+
Builds copy only verified prebuilt assets beside root, daemon, CLI and Paseo bundles;
|
|
82
|
+
source-package daemon consumers also carry native source/hash manifests. They do
|
|
83
|
+
not invoke a compiler. A rebuild replaces the generated asset directory wholesale.
|
|
84
|
+
|
|
85
|
+
### Committed prebuilts and the rebuild procedure (t-08cf)
|
|
86
|
+
|
|
87
|
+
All six slots are committed under `prebuilt/<slot>/` (binary with its exec bit, plus
|
|
88
|
+
`manifest.json` binding protocol, `terminal-owner.c` SHA-256 and binary SHA-256), so a
|
|
89
|
+
clean checkout passes `--require-matrix`, pack-check and the release clean-tree gate.
|
|
90
|
+
CI and releases ship the committed binaries; nothing is compiled during build or release.
|
|
91
|
+
|
|
92
|
+
The four Linux slots come from `.github/workflows/terminal-native.yml` (glibc on the
|
|
93
|
+
manylinux_2_28 floor image, musl on Alpine 3.20, each executed non-root in its own libc;
|
|
94
|
+
glibc also in fresh/ancestor PID namespaces). On every CI run that job rebuilds each slot
|
|
95
|
+
from the checked-out source, then requires the COMMITTED slot's manifest to record the
|
|
96
|
+
same source hash as the fresh build, its binary to match its manifest hash, and the
|
|
97
|
+
committed binary to pass the same execution checks. Builds are not byte-reproducible, so
|
|
98
|
+
binary hashes are NOT compared across builds: CI enforces source binding and execution,
|
|
99
|
+
not bit-for-bit provenance.
|
|
100
|
+
|
|
101
|
+
When `terminal-owner.c` changes, rebuild ALL six slots in the same commit:
|
|
102
|
+
|
|
103
|
+
1. Darwin: on macOS, `node scripts/build-terminal-native.mjs --arch=arm64` and
|
|
104
|
+
`--arch=x64` (x64 capability executes through Rosetta).
|
|
105
|
+
2. Linux: push the source change; the terminal-native jobs fail as stale but still upload
|
|
106
|
+
`terminal-native-<slot>` artifacts built from that exact revision. Download them into
|
|
107
|
+
an empty directory (`gh run download <run-id> -p 'terminal-native-*' -D <dir>`; each
|
|
108
|
+
lands as `<dir>/terminal-native-<slot>/<slot>.tar`) and extract each with
|
|
109
|
+
`tar -C packages/daemon/native/prebuilt -xpf <tar>` (tar keeps the exec bit).
|
|
110
|
+
3. `node scripts/terminal-native-assets.mjs --require-matrix`, commit all six slots, and
|
|
111
|
+
check the next CI run is green.
|
|
112
|
+
|
|
113
|
+
Current artifacts: Darwin arm64 executed on macOS27, Darwin x64 capability executed
|
|
114
|
+
through existing Rosetta on that same host. Both target macOS11.0 (LC_BUILD_VERSION),
|
|
115
|
+
matching [Node22's macOS floor](https://github.com/nodejs/node/blob/v22.23.0/BUILDING.md#platform-list).
|
|
116
|
+
This deployment target is NOT proof of runtime compatibility on macOS11 or physical
|
|
117
|
+
x64 hardware. Private-ABI capability validation still fails closed. Linux builds
|
|
118
|
+
must retain the existing libc support baseline (Node22 glibc2.28). The committed Linux
|
|
119
|
+
artifacts were built and capability-executed by CI run 40857935251 (GitHub-hosted
|
|
120
|
+
Ubuntu 24.04 kernels); minimum-kernel execution has not been proved. pidfd_send_signal (Linux5.1 syscall baseline) selects full protection. Without it
|
|
121
|
+
Linux runs the best-effort root-only mode described below, disclosed with a non-blocking notice.
|
|
122
|
+
No permission denial or artifact failure silently selects compatibility.
|
|
123
|
+
|
|
124
|
+
Async startup reserves request IDs and quota before native readiness. Revoke,
|
|
125
|
+
shutdown and host optout cancel startup and await native cleanup before returning;
|
|
126
|
+
late readiness cannot publish an orphan terminal. Root exit is delivered after
|
|
127
|
+
stdio drains. The helper reads the PTY to EOF and advances partial output writes
|
|
128
|
+
for up to one further second; an undrained tail reports explicit uncertainty. Cleanup reports observed/live/uncertain, and uncertain/live results
|
|
129
|
+
refuse success and stop further terminal admission. The existing real PTY cleanup
|
|
130
|
+
scenarios now execute through the native owner (including exec, same-session
|
|
131
|
+
orphans and a late child). Never-observed immediate-setsid escapes remain the
|
|
132
|
+
approved g3 discovery limit. Actual Linux/Windows browser keyboard and Linux
|
|
133
|
+
namespace/proc permissions/races remain NOT_CHECKED.
|
|
134
|
+
|
|
135
|
+
Explicit developer regressions (require a local C compiler, not end-user startup):
|
|
136
|
+
`node --test packages/daemon/native/tests/lifecycle.mjs` exercises delayed native
|
|
137
|
+
startup and a real stalled control reader. `ALP_NATIVE_BASELINE=8ed11fd` runs the
|
|
138
|
+
same checks against the committed pre-correction C/TS in isolated scratch space.
|
|
139
|
+
This mode does not change the checkout. Both cases fail on that baseline and pass
|
|
140
|
+
on the correction. Ordinary lifecycle tests run separately from daemon/tests.
|
|
141
|
+
|
|
142
|
+
## Linux root-only compatibility candidate (g5)
|
|
143
|
+
|
|
144
|
+
Linux is best-effort (user decision 2026-10-29; only macOS is guaranteed). A verified
|
|
145
|
+
helper that fails full protection for ANY reason (ENOSYS, EPERM/EACCES, procfs or
|
|
146
|
+
PID-namespace mismatch) advertises `alp-terminal-owner:1:root-only`; root-only mode
|
|
147
|
+
only signals the unreaped session root and, after the startup capability probe, does not use procfs or pidfd, so
|
|
148
|
+
background jobs may survive close. A corrupt/missing binary or manifest, timeout,
|
|
149
|
+
crash or malformed record still refuses capability (no unverified code runs).
|
|
150
|
+
The owner revalidates immediately before fork; a mode change refuses before shell
|
|
151
|
+
launch, and alpd probes the helper again for the next create.
|
|
152
|
+
|
|
153
|
+
Root-only terminals open directly: no acknowledgment is required (user decision
|
|
154
|
+
2026-10-29, Linux and Windows are best-effort like Orca/Paseo). The deprecated
|
|
155
|
+
`protectionAcknowledgment: "linux-root-only-v1"` parameter is still accepted on
|
|
156
|
+
`terminal.create`/`terminal.attach` for compatibility and ignored. Terminal records
|
|
157
|
+
carry `protection: "root-only"`, so clients disclose the limit: ALP Web shows one
|
|
158
|
+
non-blocking notice ("Limited protection on this Linux host: closing the terminal may
|
|
159
|
+
not stop background processes."), and the terminal stays usable. Paseo's terminal
|
|
160
|
+
protocol has no notice field, so the ALP bridge writes the same notice once as a
|
|
161
|
+
dim line into each Paseo client's view of the terminal (never into alpd's output).
|
|
162
|
+
|
|
163
|
+
Compatibility never scans or explicitly signals descendants or process groups.
|
|
164
|
+
Only its own direct root is signaled, before final reap, with SIGCHLD explicitly
|
|
165
|
+
SIG_DFL and SA_NOCLDWAIT cleared by checked sigaction. A living child or WNOWAIT
|
|
166
|
+
zombie continuously reserves its PID; an unexpected ECHILD permanently retires
|
|
167
|
+
numeric authority. Final reap is checked. This is spawn ownership, not a snapshot
|
|
168
|
+
or a numeric PID-reuse heuristic; helper compromise invalidates that premise.
|
|
169
|
+
Kernel PTY hangup and line-discipline signals may naturally affect foreground jobs.
|
|
170
|
+
|
|
171
|
+
Known reduced coverage is `coverage: "root-only"`; successful cleanup establishes
|
|
172
|
+
only the shell's exit. Unmanaged jobs can survive close/revoke/optout/shutdown and
|
|
173
|
+
keep the PTY open (`outputOpen: true` after bounded draining). This accepted known
|
|
174
|
+
coverage limit alone does not lock admission. Root live/lost ownership, queued
|
|
175
|
+
bytes not delivered, protocol loss or sticky adapter failure remain uncertainty
|
|
176
|
+
and retain the admission lock. No delayed signals occur after root reap.
|
|
177
|
+
|
|
178
|
+
Advice/source proof: oracle18a20d0e examined [Linux5.1 wait/ptrace reap](https://github.com/torvalds/linux/blob/v5.1/kernel/exit.c)
|
|
179
|
+
and [original procdirfd signal dispatch](https://github.com/torvalds/linux/blob/v5.1/kernel/signal.c).
|
|
180
|
+
Actual Linux compilation/execution (old and supported kernel, namespace/permission,
|
|
181
|
+
ptrace/exec/reuse/race) remains NOT_CHECKED here; the four shipped Linux artifacts are committed and CI capability-checked.
|
|
182
|
+
Darwin author regressions validate the unchanged full path only; no seam/mock or
|
|
183
|
+
Rosetta execution is claimed as Linux or physical-x64/minimum-macOS proof.
|
|
184
|
+
|
|
185
|
+
## Windows (best-effort, no protection helper)
|
|
186
|
+
|
|
187
|
+
There is no Windows native owner and pack-check requires no Windows slot. On win32,
|
|
188
|
+
`src/terminals.ts` spawns the shell (`%ComSpec%`, else `cmd.exe`) through node-pty
|
|
189
|
+
(ConPTY), the same platform PTY Paseo uses; node-pty is an optional dependency, and
|
|
190
|
+
when it cannot load, terminals refuse with `terminal_unsupported`. Terminals report
|
|
191
|
+
`protection: "none"`, and clients show a "not guaranteed on Windows" notice. Closing,
|
|
192
|
+
revoking or turning off terminals calls node-pty `kill()` (best-effort): the shell
|
|
193
|
+
ends, but processes it started may keep running. This is the only production use of
|
|
194
|
+
node-pty. Windows behavior has NOT been executed here; only injected-owner unit tests ran.
|
|
195
|
+
|
|
196
|
+
## Termination signals
|
|
197
|
+
|
|
198
|
+
SIGTERM, SIGINT and SIGHUP sent to the owner (for example to the daemon's process group)
|
|
199
|
+
start the same bound cleanup as closing its control pipe, on every platform including
|
|
200
|
+
macOS (deliberate: previously such a signal killed the owner before cleanup). The shell
|
|
201
|
+
child resets them to default before exec.
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
{
|
|
2
|
+
"protocol": 1,
|
|
3
|
+
"slot": "darwin-arm64",
|
|
4
|
+
"source": "d2fa72ce0b083e60cddbe76839365beaa80b891451b45987d968b805154d0636",
|
|
5
|
+
"sha256": "354f50aea9e8d5113fc9fb4fd90ccb417d8aad74b89473fdcb711c6d1253f367",
|
|
6
|
+
"buildHost": "v22.23.4",
|
|
7
|
+
"deploymentTarget": "11.0",
|
|
8
|
+
"executionChecked": true,
|
|
9
|
+
"executionProtection": "identity-bound",
|
|
10
|
+
"executionHost": "darwin-arm64"
|
|
11
|
+
}
|
|
Binary file
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
{
|
|
2
|
+
"protocol": 1,
|
|
3
|
+
"slot": "darwin-x64",
|
|
4
|
+
"source": "d2fa72ce0b083e60cddbe76839365beaa80b891451b45987d968b805154d0636",
|
|
5
|
+
"sha256": "606a0bd9a0ae76550156d343c89efa69d97215b8bf95c6aadbf38b6468a041e5",
|
|
6
|
+
"buildHost": "v22.23.4",
|
|
7
|
+
"deploymentTarget": "11.0",
|
|
8
|
+
"executionChecked": true,
|
|
9
|
+
"executionProtection": "identity-bound",
|
|
10
|
+
"executionHost": "darwin-arm64"
|
|
11
|
+
}
|
|
Binary file
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
{
|
|
2
|
+
"protocol": 1,
|
|
3
|
+
"slot": "linux-arm64-glibc",
|
|
4
|
+
"source": "d2fa72ce0b083e60cddbe76839365beaa80b891451b45987d968b805154d0636",
|
|
5
|
+
"sha256": "fa6e8b66f8e449d6fa294518c7f7d107e0707d2048623cc4952031b9580c31e3",
|
|
6
|
+
"buildHost": "v22.23.4",
|
|
7
|
+
"executionChecked": true,
|
|
8
|
+
"executionProtection": "identity-bound",
|
|
9
|
+
"executionHost": "linux-arm64"
|
|
10
|
+
}
|
|
Binary file
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
{
|
|
2
|
+
"protocol": 1,
|
|
3
|
+
"slot": "linux-arm64-musl",
|
|
4
|
+
"source": "d2fa72ce0b083e60cddbe76839365beaa80b891451b45987d968b805154d0636",
|
|
5
|
+
"sha256": "e6935d27c14c626b3207ea8edecd4a56b6bf13c8634b97a7480928e4bd22e9d6",
|
|
6
|
+
"buildHost": "v20.15.1",
|
|
7
|
+
"executionChecked": true,
|
|
8
|
+
"executionProtection": "identity-bound",
|
|
9
|
+
"executionHost": "linux-arm64"
|
|
10
|
+
}
|
|
Binary file
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
{
|
|
2
|
+
"protocol": 1,
|
|
3
|
+
"slot": "linux-x64-glibc",
|
|
4
|
+
"source": "d2fa72ce0b083e60cddbe76839365beaa80b891451b45987d968b805154d0636",
|
|
5
|
+
"sha256": "4746db2e0b89ffd81f9ab14da871a8a8a59b39d219ab9612bb86faa8d8db35b7",
|
|
6
|
+
"buildHost": "v22.23.4",
|
|
7
|
+
"executionChecked": true,
|
|
8
|
+
"executionProtection": "identity-bound",
|
|
9
|
+
"executionHost": "linux-x64"
|
|
10
|
+
}
|
|
Binary file
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
{
|
|
2
|
+
"protocol": 1,
|
|
3
|
+
"slot": "linux-x64-musl",
|
|
4
|
+
"source": "d2fa72ce0b083e60cddbe76839365beaa80b891451b45987d968b805154d0636",
|
|
5
|
+
"sha256": "5d3e964057212ce231ab920426012ede944057138613712f0cf52a81f1397c2d",
|
|
6
|
+
"buildHost": "v20.15.1",
|
|
7
|
+
"executionChecked": true,
|
|
8
|
+
"executionProtection": "identity-bound",
|
|
9
|
+
"executionHost": "linux-x64"
|
|
10
|
+
}
|
|
Binary file
|