pi-radar 0.7.0 → 0.10.0

package/extension/baseline.ts

@@ -1,6 +1,7 @@
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { createRadarClient } from "./radar-client.ts";
+import { createRadarChildren } from "./radar-children.ts";
 import { createRadarHandoffPort } from "./radar-communication.ts";
 import {
 	createRadarExecutionAdapter,
@@ -33,6 +34,7 @@ export default function registerPiRadar(pi: PiRadarHost): void {
 	const runtime = lazyRadarRuntime(async () => ({
 		publication: execution.publication,
 		communication: createRadarHandoffPort(client, execution.publication),
+		children: createRadarChildren(client, execution.publication),
 		execution,
 	}));
 	provideRadarRuntime(pi.events, runtime);

package/extension/generated-contracts.ts

@@ -911,7 +911,6 @@ export interface ManagedSubject {
   session: string | null;
   state: State;
   subject_id: string;
-  successor: string | null;
 }
 /**
  * Exact spawn-edge child identity required by `spawn.close`.
@@ -1323,7 +1322,6 @@ export interface LifecycleObservation {
   session: string | null;
   state: State;
   subject_id: string;
-  successor: string | null;
 }
 /**
  * A runtime pane: location plus optional display text.
@@ -1452,6 +1450,7 @@ export interface SpawnListPageSerializePublicSpawnTopology {
    * nothing to verify.
    */
   freshness?: SpawnListPageSerializeFreshness | null;
+  granted_at?: string | null;
   launched: SpawnListPageSerializeRequestOutcome;
   location?: SpawnListPageSerializeRegistryLocation | null;
   parent: string;
@@ -1461,6 +1460,7 @@ export interface SpawnListPageSerializePublicSpawnTopology {
   request_id: string;
   state: SpawnListPageSerializeSpawnState;
   version: number;
+  withdrawn?: SpawnListPageSerializeWithdrawn | null;
 }
 /**
  * The child a token bound: the registering incarnation's own registry identity.
@@ -1476,6 +1476,11 @@ export interface SpawnListPageSerializeBoundChild {
    */
   registration_id?: string | null;
   source: string;
+  /**
+   * The durable agent the bound child attaches as. Absent for an edge without
+   * a tracked launch and in records written before it was recorded.
+   */
+  subject_id?: string | null;
 }
 /**
  * Where an agent's incarnation lives on one backend, in that backend's own
@@ -1492,3 +1497,11 @@ export interface SpawnListPageSerializeRegistryLocation {
   tab?: string | null;
   workspace?: string | null;
 }
+/**
+ * Why and when a launch ended without ever presenting, so a reader never infers
+ * failure from absence.
+ */
+export interface SpawnListPageSerializeWithdrawn {
+  at: string;
+  reason: string;
+}

package/extension/radar-children.ts

@@ -0,0 +1,222 @@
+import { randomUUID } from "node:crypto";
+import type { RadarClient, RadarChannelSnapshot, RadarResult } from "./radar-client.ts";
+import type { SpawnListPageSerializePublicSpawnTopology as ListedEdge } from "./generated-contracts.ts";
+import { inspectRadarChild, type RadarInspection } from "./radar-inspection.ts";
+import { observeRadarChild, waitForChild, launchFailure, type RadarChildObservation, type RadarLaunchOutcome } from "./radar-launch.ts";
+import type { RadarPublication } from "./radar-publication.ts";
+
+const PAGE = 100;
+const MAX_PAGES = 20;
+
+/** One child of the caller, named by the agent that survives its restarts. */
+export type RadarChild = {
+	subject_id: string;
+	/** The launch that last bound this child. */
+	request_id: string;
+	pane_id?: string;
+	state: "unbound" | "bound" | "unresolved";
+	exited: boolean;
+};
+
+/** The assignment a child is held to: published again when its process is replaced. */
+export type RadarChildAssignment = {
+	update(snapshot: RadarChannelSnapshot): void;
+	retire(): void;
+};
+
+/** The program a restarted child runs as. */
+export type RadarChildProgram = {
+	executable: string;
+	argv: string[];
+	cwd?: string;
+	env?: Record<string, string>;
+};
+
+export type RadarChildren = {
+	list(): Promise<RadarResult<RadarChild[]>>;
+	/**
+	 * Replace this caller's live child with a new process in its own pane and
+	 * session, and wait for the daemon to grant it or withdraw the launch.
+	 */
+	restart(
+		subject: string,
+		program: RadarChildProgram,
+		options?: { pollMs?: number; signal?: AbortSignal },
+	): Promise<RadarLaunchOutcome>;
+	assignment(subject: string, owner: string): RadarChildAssignment;
+	retire(subject: string): void;
+	observe(
+		subject: string,
+		session_id: string | undefined,
+	): Promise<RadarChildObservation>;
+	inspect(subject: string, session_id?: string): Promise<RadarInspection>;
+};
+
+type Resolved = { child: RadarChild; registration_id: string };
+
+/**
+ * The caller's children, addressed by subject. A subject gains an edge per launch,
+ * so the newest bound edge is the current process; its registration is read per
+ * call and never remembered, because a remembered registration is the stale key
+ * this surface exists to hide. An edge bound without a subject is not addressable.
+ */
+export function createRadarChildren(
+	client: Pick<RadarClient, "spawnList" | "spawnGet" | "agentGet" | "output" | "processInfo" | "restart">,
+	publication: Pick<RadarPublication, "assignment" | "retireAssignment" | "subject">,
+): RadarChildren {
+	const held = new Map<
+		string,
+		{ writer: RadarChildAssignment; published?: string; publish?: (target: Resolved) => void }
+	>();
+
+	async function resolveAll(): Promise<RadarResult<Map<string, Resolved & { at: number }>>> {
+		const newest = new Map<string, Resolved & { at: number }>();
+		let after: string | undefined;
+		for (let page = 0; page < MAX_PAGES; page++) {
+			const read = await client.spawnList({ ...(after !== undefined ? { after } : {}), limit: PAGE });
+			if (read.ok === false) return read;
+			for (const edge of read.value.spawns as ListedEdge[]) {
+				const bound = edge.bound;
+				if (!bound?.subject_id || !bound.registration_id || edge.granted_at == null || edge.withdrawn != null) continue;
+				const at = Date.parse(bound.bound_at);
+				if (Number.isNaN(at)) continue;
+				const current = newest.get(bound.subject_id);
+				if (current !== undefined && current.at >= at) continue;
+				newest.set(bound.subject_id, {
+					at,
+					registration_id: bound.registration_id,
+					child: {
+						subject_id: bound.subject_id,
+						request_id: edge.request_id,
+						...(edge.location?.pane ? { pane_id: edge.location.pane } : {}),
+						state: edge.state,
+						exited: edge.exit_observation != null && edge.exit_observation.state !== "unknown",
+					},
+				});
+			}
+			if (!read.value.next) return { ok: true, value: newest };
+			after = read.value.next;
+		}
+		return { ok: false, code: "protocol", message: "the caller's launches exceed the readable pages" };
+	}
+
+	async function resolve(subject: string): Promise<Resolved | undefined> {
+		const all = await resolveAll();
+		return all.ok ? all.value.get(subject) : undefined;
+	}
+
+	async function resolveAndFollow(subject: string): Promise<Resolved | undefined> {
+		const all = await resolveAll();
+		if (!all.ok) return undefined;
+		follow(all.value);
+		return all.value.get(subject);
+	}
+
+	/**
+	 * A child replaced under its subject has a new process with no assignment. Each
+	 * read the caller already makes finds the new registration and moves the held
+	 * assignment onto it, so no caller has to notice a replacement.
+	 */
+	function follow(all: Map<string, Resolved>): void {
+		for (const [subject, entry] of held) {
+			const target = all.get(subject);
+			if (target !== undefined && entry.published !== target.registration_id)
+				entry.publish?.(target);
+		}
+	}
+
+	return {
+		async list() {
+			const all = await resolveAll();
+			if (!all.ok) return all;
+			follow(all.value);
+			return { ok: true, value: [...all.value.values()].map((entry) => entry.child) };
+		},
+		async restart(subject, program, options) {
+			const parent = await publication.subject();
+			if (parent?.subject_id === undefined)
+				return { kind: "failed", message: "this process has no Radar registration to restart a child under" };
+			const request_id = randomUUID();
+			const requested = await client.restart({
+				request_id,
+				parent: parent.registration_id,
+				subject_id: subject,
+				...program,
+			});
+			if (requested.ok === false)
+				return launchFailure(requested, request_id);
+			const bound = await waitForChild(client, requested.value.launch_request_id, {
+				pollMs: options?.pollMs ?? 250,
+				...(options?.signal !== undefined ? { signal: options.signal } : {}),
+			});
+			if (bound.kind !== "bound") return bound;
+			await resolveAndFollow(subject);
+			return {
+				kind: "ready",
+				value: {
+					request_id: requested.value.launch_request_id,
+					subject_id: bound.subject_id,
+					pane_id: bound.pane_id,
+				},
+			};
+		},
+		assignment(subject, owner) {
+			const existing = held.get(subject);
+			if (existing !== undefined) return existing.writer;
+			let latest: RadarChannelSnapshot | undefined;
+			const entry: {
+				writer: RadarChildAssignment;
+				published?: string;
+				publish?: (target: Resolved) => void;
+			} = { writer: undefined as unknown as RadarChildAssignment };
+			const send = (target: Resolved): void => {
+				if (latest === undefined) return;
+				if (entry.published !== undefined && entry.published !== target.registration_id)
+					publication.retireAssignment(entry.published);
+				entry.published = target.registration_id;
+				publication.assignment(target.registration_id, owner).update(latest);
+			};
+			entry.publish = send;
+			entry.writer = {
+				update(snapshot) {
+					latest = snapshot;
+					void resolve(subject).then((target) => {
+						if (target !== undefined) send(target);
+					});
+				},
+				retire() {
+					latest = undefined;
+					if (entry.published !== undefined) publication.retireAssignment(entry.published);
+					entry.published = undefined;
+				},
+			};
+			held.set(subject, entry);
+			return entry.writer;
+		},
+		retire(subject) {
+			held.get(subject)?.writer.retire();
+			held.delete(subject);
+		},
+		async observe(subject, session_id) {
+			const target = await resolveAndFollow(subject);
+			if (target === undefined)
+				return { kind: "unknown", diagnostic: "the daemon records no bound launch for this child" };
+			return observeRadarChild(client as RadarClient, {
+				request_id: target.child.request_id,
+				pane_id: target.child.pane_id,
+				registration_id: target.registration_id,
+				session_id,
+			});
+		},
+		async inspect(subject, session_id) {
+			const target = await resolveAndFollow(subject);
+			if (target?.child.pane_id === undefined)
+				throw new Error("Inspection target is not a bound child with a pane");
+			return inspectRadarChild(client as RadarClient, {
+				agentId: target.registration_id,
+				paneId: target.child.pane_id,
+				...(session_id !== undefined ? { session: session_id } : {}),
+			});
+		},
+	};
+}

package/extension/radar-client.ts

@@ -34,15 +34,18 @@ import type {
 export const RADAR_PROTOCOL_VERSION = 2;
 /**
  * Revision 5 names attempts by claim_id and requires exact-claim controls.
+ * Revision 7 starts every managed launch through `radar run --launch` and lets a
+ * parent continue or restart its own child by subject.
  * Earlier daemons expose different identity fields; require a coordinated update.
  */
-export const RADAR_MINIMUM_REVISION = 6;
+export const RADAR_MINIMUM_REVISION = 8;
 /** Public daemon contracts this client may preflight. */
 export const RADAR_REGISTRY_CONTRACT = "registry.v1";
 export const RADAR_REGISTRY_FACTS_CONTRACT = "registry.facts.v1";
 export const RADAR_SPAWN_CONTRACT = "spawn.v1";
 export const RADAR_SPAWN_LIST_CONTRACT = "spawn.list.v1";
 export const RADAR_SPAWN_CLOSE_CONTRACT = "spawn.close.v1";
+export const RADAR_LIFECYCLE_RESTART_CONTRACT = "lifecycle.restart.v1";
 export const RADAR_SPAWN_LAUNCH_CONTEXT_CONTRACT = "spawn.launch_context.v1";
 export const RADAR_EVENTS_CONTRACT = "events.v1";
 export const RADAR_COMMUNICATION_CONTRACT = "communication.handoff.v1";
@@ -304,8 +307,11 @@ export type RadarSpawnEdge = {
 	created: RadarEffectOutcome;
 	launched: RadarEffectOutcome;
 	location?: RadarLocation;
-	bound?: { source: string; incarnation: string; registration_id?: string };
+	bound?: { source: string; incarnation: string; registration_id?: string; subject_id?: string };
 	exit_observation?: RadarSpawnExitObservation;
+	/** Set when the daemon withdrew the launch before its process presented. */
+	withdrawn?: { at: string; reason: string };
+	granted_at?: string;
 };
 
 /**
@@ -825,7 +831,11 @@ function spawnEdge(value: unknown): RadarResult<RadarSpawnEdge> {
 	const source = stringAt(bound, "source");
 	const incarnation = stringAt(bound, "incarnation");
 	const agentId = stringAt(bound, "registration_id");
+	const subjectId = stringAt(bound, "subject_id");
 	const exit = exitAt(recordAt(value, "exit_observation"));
+	const withdrawnRecord = recordAt(value, "withdrawn");
+	const withdrawnAt = stringAt(withdrawnRecord, "at");
+	const withdrawnReason = stringAt(withdrawnRecord, "reason");
 	return {
 		ok: true,
 		value: {
@@ -840,10 +850,15 @@ function spawnEdge(value: unknown): RadarResult<RadarSpawnEdge> {
 							source,
 							incarnation,
 							...(isUuid(agentId) ? { registration_id: agentId } : {}),
+							...(isUuid(subjectId) ? { subject_id: subjectId } : {}),
 						},
 					}
 				: {}),
 			...(exit !== undefined ? { exit_observation: exit } : {}),
+			...(stringAt(value, "granted_at") !== undefined ? { granted_at: stringAt(value, "granted_at") } : {}),
+			...(withdrawnAt !== undefined && withdrawnReason !== undefined
+				? { withdrawn: { at: withdrawnAt, reason: withdrawnReason } }
+				: {}),
 		},
 	};
 }
@@ -959,9 +974,12 @@ function spawnRequestShape(request: {
 	cwd?: string;
 	env?: Record<string, string>;
 	managed?: RadarManagedLaunchMetadata;
+	continue_subject_id?: string;
 }): string | undefined {
 	if (!isUuid(request.request_id))
 		return "spawn requires a canonical request UUID";
+	if (request.continue_subject_id !== undefined && !isUuid(request.continue_subject_id))
+		return "continue_subject_id must be a canonical UUID";
 	if (!isUuid(request.parent))
 		return "spawn requires the parent's canonical agent UUID";
 	if (!isUuid(request.parent_session_id))
@@ -1100,7 +1118,23 @@ export type RadarClient = {
 		cwd?: string;
 		env?: Record<string, string>;
 		managed?: RadarManagedLaunchMetadata;
+		/** Start this released child agent again, in the session the daemon recorded for it. */
+		continue_subject_id?: string;
 	}): Promise<RadarResult<RadarSpawnEdge>>;
+	/**
+	 * Restart this caller's own live child under a new program. The daemon finds the
+	 * child's current process from the subject and replaces it in its own pane and
+	 * session; a program with a bare argument that may be a message is refused.
+	 */
+	restart(request: {
+		request_id: string;
+		parent: string;
+		subject_id: string;
+		executable: string;
+		argv: string[];
+		cwd?: string;
+		env?: Record<string, string>;
+	}): Promise<RadarResult<{ request_id: string; launch_request_id: string }>>;
 	/** List launches owned by this client's registered process. */
 	spawnList(request: Pick<SpawnListParamsDeserialize, "after" | "limit">): Promise<RadarResult<SpawnListPageSerialize>>;
 	spawnGet(request_id: string): Promise<RadarResult<RadarSpawnTopology>>;
@@ -1671,6 +1705,9 @@ export function createRadarClient(options: RadarClientOptions = {}): RadarClient
 								...(request.managed !== undefined
 									? { managed: request.managed }
 									: {}),
+								...(request.continue_subject_id !== undefined
+									? { continue_subject_id: request.continue_subject_id }
+									: {}),
 							},
 							requester,
 						},
@@ -1706,6 +1743,37 @@ export function createRadarClient(options: RadarClientOptions = {}): RadarClient
 				},
 			);
 		},
+		async restart(request) {
+			if (!isUuid(request.request_id) || !isUuid(request.parent) || !isUuid(request.subject_id))
+				return {
+					ok: false,
+					code: "bad_params",
+					message: "restart requires canonical request, parent and subject UUIDs",
+				};
+			return withContract(RADAR_LIFECYCLE_RESTART_CONTRACT, async () => {
+				const answer = await call(
+					"lifecycle.restart",
+					{
+						request: {
+							subject_id: request.subject_id,
+							parent: request.parent,
+							executable: request.executable,
+							argv: request.argv,
+							...(request.cwd !== undefined ? { cwd: request.cwd } : {}),
+							...(request.env !== undefined ? { env: request.env } : {}),
+						},
+						requester,
+					},
+					request.request_id,
+				);
+				if (answer.ok === false) return answer;
+				const settled = focusOutcome(recordAt(answer.value, "request"), request.request_id);
+				if (settled.ok === false) return settled;
+				const launch = recordAt(recordAt(answer.value, "request"), "launch_request_id");
+				if (!isUuid(launch)) return protocol("lifecycle.restart reply names no launch");
+				return { ok: true, value: { ...settled.value, launch_request_id: launch } };
+			});
+		},
 		async spawnList(request) {
 			const registrationId = processRegistrationId;
 			if (registrationId === undefined)