pi-radar 0.1.0 → 0.3.0

package/extension/generated-contracts.ts

@@ -19,6 +19,91 @@ export interface TaskLaneStatus {
   available: boolean;
   error: string | null;
 }
+/**
+ * Inputs for publishing an immutable handoff. The wire request ID carries the
+ * stable communication identity; the daemon derives the sender execution.
+ */
+export interface HandoffPublishParamsDeserialize {
+  content: string;
+  correlation_id?: string | null;
+  recipient_subject_id: string;
+  sender_agent_id: string;
+  summary: string;
+}
+/**
+ * A bounded inbox page by stable handoff ID. Payloads are fetched one at a
+ * time with `communication.get`, keeping each response within the wire bound.
+ */
+export interface HandoffInboxSerialize {
+  handoff_ids: string[];
+}
+/**
+ * Immutable handoff content. The request id is the stable communication id.
+ */
+export interface HandoffSerialize {
+  content: string;
+  correlation_id?: string | null;
+  id: string;
+  published_at_unix_ms: number;
+  recipient_subject_id: string;
+  sender: HandoffIdentity;
+  summary: string;
+  version: number;
+}
+/**
+ * The current managed Pi execution that published or received a handoff.
+ * `subject_id` is stable across verified successors; `execution_id` and
+ * generation identify the exact execution that took the action.
+ */
+export interface HandoffIdentity {
+  agent_id: string;
+  execution_generation: number;
+  execution_id: string;
+  session_id: string;
+  subject_id: string;
+}
+/**
+ * Durable recipient-consumer receipt, stored separately from immutable content.
+ */
+export interface HandoffReceiptSerialize {
+  handoff_id: string;
+  received_at_unix_ms: number;
+  recipient: HandoffIdentity;
+  version: number;
+}
+/**
+ * The current managed Pi execution that published or received a handoff.
+ * `subject_id` is stable across verified successors; `execution_id` and
+ * generation identify the exact execution that took the action.
+ */
+export interface HandoffIdentity {
+  agent_id: string;
+  execution_generation: number;
+  execution_id: string;
+  session_id: string;
+  subject_id: string;
+}
+/**
+ * Managed owner/parent metadata accepted with a spawn intent. Domain validation
+ * and parent-binding checks remain in the daemon handler.
+ */
+export interface ManagedLaunchMetadataDeserialize {
+  label?: string | null;
+  owner?: string | null;
+  parent_subject_id?: string | null;
+  role?: string | null;
+  run?: string | null;
+}
+/**
+ * A non-secret Pi-session breadcrumb issued by Radar. This is correlation
+ * evidence only and cannot establish lifecycle authority.
+ */
+export interface LaunchIdentityMarkerSerialize {
+  execution_generation: number;
+  launch_id: string;
+  subject_id: string;
+  version: number;
+}
 /**
  * The agent's own process facts. Self-authored by any Pi session, with no owner
  * or assignment, and kept separate from execution and assignment. Every field

package/extension/radar-client.ts

@@ -4,7 +4,13 @@ import { createConnection } from "node:net";
 import { dirname, join } from "node:path";
 import type {
 	DaemonPingSerialize,
+	LaunchIdentityMarkerSerialize,
 	FactsSnapshotDeserialize,
+	HandoffInboxSerialize,
+	HandoffReceiptSerialize,
+	HandoffPublishParamsDeserialize,
+	HandoffSerialize,
+	ManagedLaunchMetadataDeserialize,
 	SpawnExitObservationSerialize,
 } from "./generated-contracts.ts";
 
@@ -26,7 +32,7 @@ import type {
  */
 export const RADAR_PROTOCOL_VERSION = 2;
 /** The minimum daemon wire revision this client understands. */
-export const RADAR_MINIMUM_REVISION = 1;
+export const RADAR_MINIMUM_REVISION = 3;
 /** Public daemon contracts this client may preflight. */
 export const RADAR_REGISTRY_CONTRACT = "registry.v1";
 export const RADAR_REGISTRY_FACTS_CONTRACT = "registry.facts.v1";
@@ -34,6 +40,7 @@ export const RADAR_SPAWN_CONTRACT = "spawn.v1";
 export const RADAR_SPAWN_CLOSE_CONTRACT = "spawn.close.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";
 /** The default audit identity; callers can supply their own requester. */
 export const RADAR_REQUESTER = "pi-radar";
 /** The daemon's own line bound; nothing longer is sent or accepted. */
@@ -160,6 +167,9 @@ export type RadarBackgroundTask = NonNullable<
 	FactsSnapshotDeserialize["background_tasks"]
 >[number];
 export type RadarFactsSnapshot = FactsSnapshotDeserialize;
+export type RadarHandoff = HandoffSerialize;
+export type RadarHandoffInbox = HandoffInboxSerialize;
+export type RadarHandoffReceipt = HandoffReceiptSerialize;
 
 /**
  * The assignment channel's interim fields. `request` is the owner's active
@@ -194,6 +204,7 @@ export type RadarWriterBinding = {
  */
 export type RadarContextValue = {
 	session: string | null;
+	launch_identity?: LaunchIdentityMarkerSerialize;
 };
 
 /**
@@ -296,6 +307,10 @@ export type RadarSpawnEdge = {
  * no exit was observed.
  */
 export type RadarSpawnExitObservation = SpawnExitObservationSerialize;
+export type RadarLaunchIdentityMarker = LaunchIdentityMarkerSerialize;
+
+/** Durable Radar-owned metadata accepted with a managed launch intent. */
+export type RadarManagedLaunchMetadata = ManagedLaunchMetadataDeserialize;
 
 /**
  * One edge with what *that read* learned about the location it recorded.
@@ -501,6 +516,46 @@ function numberAt(value: unknown, field: string): number | undefined {
 		: undefined;
 }
 
+function handoffAt(value: unknown): HandoffSerialize | undefined {
+	const version = numberAt(value, "version");
+	const id = stringAt(value, "id");
+	const sender = recordAt(value, "sender");
+	const senderGeneration = numberAt(sender, "execution_generation");
+	const target = stringAt(value, "recipient_subject_id");
+	const summary = stringAt(value, "summary");
+	const content = stringAt(value, "content");
+	const published = numberAt(value, "published_at_unix_ms");
+	const correlation = typeof value === "object" && value !== null
+		? (value as Record<string, unknown>).correlation_id
+		: undefined;
+	if (
+		version !== 1 || !isUuid(id) || !isUuid(stringAt(sender, "agent_id")) ||
+		!isUuid(stringAt(sender, "session_id")) || !isUuid(stringAt(sender, "subject_id")) ||
+		!isUuid(stringAt(sender, "execution_id")) || !Number.isSafeInteger(senderGeneration) ||
+		(senderGeneration ?? 0) < 1 || !isUuid(target) || summary === undefined || content === undefined ||
+		published === undefined || !Number.isSafeInteger(published) || published < 0 ||
+		(correlation !== undefined && correlation !== null &&
+			(typeof correlation !== "string" || correlation.length === 0 ||
+				Buffer.byteLength(correlation, "utf8") > 256 || /\p{Cc}/u.test(correlation)))
+	) return undefined;
+	return value as HandoffSerialize;
+}
+
+function handoffReceiptAt(value: unknown): HandoffReceiptSerialize | undefined {
+	const version = numberAt(value, "version");
+	const handoffId = stringAt(value, "handoff_id");
+	const recipient = recordAt(value, "recipient");
+	const generation = numberAt(recipient, "execution_generation");
+	const received = numberAt(value, "received_at_unix_ms");
+	if (
+		version !== 1 || !isUuid(handoffId) || !isUuid(stringAt(recipient, "agent_id")) ||
+		!isUuid(stringAt(recipient, "session_id")) || !isUuid(stringAt(recipient, "subject_id")) ||
+		!isUuid(stringAt(recipient, "execution_id")) || !Number.isSafeInteger(generation) ||
+		(generation ?? 0) < 1 || received === undefined || !Number.isSafeInteger(received) || received < 0
+	) return undefined;
+	return value as HandoffReceiptSerialize;
+}
+
 /** A writer binding a channel or context reply hands back to its publisher. */
 function writerBinding(value: unknown): RadarWriterBinding | undefined {
 	const handle = stringAt(value, "handle");
@@ -651,6 +706,12 @@ function unresolvedOperation(requestId: string, detail: string): RadarResult<nev
 }
 
 export const RADAR_SPAWN_TOKEN_ENV = "PI_RADAR_SPAWN_TOKEN";
+const RADAR_MANAGED_IDENTITY_ENV = new Set([
+	"PI_RADAR_MANAGED_SUBJECT_ID",
+	"PI_RADAR_MANAGED_LAUNCH_ID",
+	"PI_RADAR_MANAGED_EXECUTION_GENERATION",
+	"PI_RADAR_MANAGED_PARENT_SUBJECT_ID",
+]);
 
 /**
  * A spawn this process may still have caused.
@@ -857,6 +918,7 @@ function spawnRequestShape(request: {
 	argv: string[];
 	cwd?: string;
 	env?: Record<string, string>;
+	managed?: RadarManagedLaunchMetadata;
 }): string | undefined {
 	if (!isUuid(request.request_id))
 		return "spawn requires a canonical request UUID";
@@ -875,9 +937,26 @@ function spawnRequestShape(request: {
 	for (const [name, value] of env) {
 		if (name === RADAR_SPAWN_TOKEN_ENV)
 			return `spawn env cannot set the reserved ${RADAR_SPAWN_TOKEN_ENV}`;
+		if (RADAR_MANAGED_IDENTITY_ENV.has(name))
+			return `spawn env cannot set Radar-issued identity variable ${name}`;
 		if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name) || /\p{Cc}/u.test(value))
 			return `spawn env contains an invalid name or value: ${name}`;
 	}
+	if (request.managed !== undefined) {
+		if (typeof request.managed !== "object" || request.managed === null)
+			return "managed launch metadata must be an object";
+		for (const [name, value] of Object.entries(request.managed)) {
+			if (!["owner", "run", "label", "role", "parent_subject_id"].includes(name))
+				return `unknown managed launch metadata field: ${name}`;
+			if (value != null && (typeof value !== "string" || value.trim() === "" || new TextEncoder().encode(value).length > 256 || /\p{Cc}/u.test(value)))
+				return `managed launch ${name} must be non-empty, control-free, and at most 256 UTF-8 bytes`;
+		}
+		if (
+			request.managed.parent_subject_id != null &&
+			!isUuid(request.managed.parent_subject_id)
+		)
+			return "managed parent_subject_id must be a canonical UUID";
+	}
 	return undefined;
 }
 
@@ -978,12 +1057,19 @@ export type RadarClient = {
 		argv: string[];
 		cwd?: string;
 		env?: Record<string, string>;
+		managed?: RadarManagedLaunchMetadata;
 	}): Promise<RadarResult<RadarSpawnEdge>>;
 	spawnGet(request_id: string): Promise<RadarResult<RadarSpawnTopology>>;
 	/** The registered child's process verdict, read from its immutable claim. */
 	agentGet(agent_id: string): Promise<RadarResult<RadarAgentProcess>>;
 	observe(): Promise<RadarResult<RadarInventory>>;
 	/** Read the durable event journal after `after`, waiting at most `wait_ms`. */
+	communicationPublish(request: HandoffPublishParamsDeserialize & {
+		request_id: string;
+	}): Promise<RadarResult<{ handoff: HandoffSerialize; created: boolean }>>;
+	communicationInbox(request: { agent_id: string }): Promise<RadarResult<HandoffInboxSerialize>>;
+	communicationGet(request: { agent_id: string; handoff_id: string }): Promise<RadarResult<{ handoff: HandoffSerialize; receipt: HandoffReceiptSerialize | null }>>;
+	communicationAck(request: { agent_id: string; handoff_id: string }): Promise<RadarResult<{ receipt: HandoffReceiptSerialize; created: boolean }>>;
 	events(request: {
 		after: number;
 		epoch?: string;
@@ -1513,6 +1599,9 @@ export function createRadarClient(options: RadarClientOptions = {}): RadarClient
 								...(carriesContext && request.env !== undefined
 									? { env: request.env }
 									: {}),
+								...(request.managed !== undefined
+									? { managed: request.managed }
+									: {}),
 							},
 							requester,
 						},
@@ -1632,6 +1721,56 @@ export function createRadarClient(options: RadarClientOptions = {}): RadarClient
 				return protocol("spawn.close reply carries no close outcome");
 			});
 		},
+		async communicationPublish(request) {
+			return withContract(RADAR_COMMUNICATION_CONTRACT, async () => {
+				const answer = await call("communication.publish", {
+					sender_agent_id: request.sender_agent_id,
+					recipient_subject_id: request.recipient_subject_id,
+					...(request.correlation_id !== undefined ? { correlation_id: request.correlation_id } : {}),
+					summary: request.summary,
+					content: request.content,
+				}, request.request_id);
+				if (answer.ok === false) return answer;
+				const handoff = handoffAt(recordAt(answer.value, "handoff"));
+				const created = recordAt(answer.value, "created");
+				if (handoff === undefined || typeof created !== "boolean")
+					return protocol("communication.publish reply carries no handoff");
+				return { ok: true, value: { handoff, created } };
+			});
+		},
+		async communicationInbox(request) {
+			return withContract(RADAR_COMMUNICATION_CONTRACT, async () => {
+				const answer = await call("communication.inbox", request);
+				if (answer.ok === false) return answer;
+				const handoffIds = recordAt(answer.value, "handoff_ids");
+				if (!Array.isArray(handoffIds) || handoffIds.some((id) => !isUuid(id)))
+					return protocol("communication.inbox reply carries malformed handoff IDs");
+				return { ok: true, value: answer.value as HandoffInboxSerialize };
+			});
+		},
+		async communicationGet(request) {
+			return withContract(RADAR_COMMUNICATION_CONTRACT, async () => {
+				const answer = await call("communication.get", request);
+				if (answer.ok === false) return answer;
+				const handoff = handoffAt(recordAt(answer.value, "handoff"));
+				const receiptValue = recordAt(answer.value, "receipt");
+				const receipt = receiptValue === null ? null : handoffReceiptAt(receiptValue);
+				if (handoff === undefined || (receiptValue !== null && receipt === undefined))
+					return protocol("communication.get reply carries malformed content or receipt");
+				return { ok: true, value: { handoff, receipt: receipt ?? null } };
+			});
+		},
+		async communicationAck(request) {
+			return withContract(RADAR_COMMUNICATION_CONTRACT, async () => {
+				const answer = await call("communication.ack", request);
+				if (answer.ok === false) return answer;
+				const receipt = handoffReceiptAt(recordAt(answer.value, "receipt"));
+				const created = recordAt(answer.value, "created");
+				if (receipt === undefined || typeof created !== "boolean")
+					return protocol("communication.ack reply carries no receipt");
+				return { ok: true, value: { receipt, created } };
+			});
+		},
 		async events(request) {
 			if (
 				!Number.isSafeInteger(request.after) ||

package/extension/radar-communication.ts

@@ -0,0 +1,66 @@
+import type { HandoffInboxSerialize, HandoffSerialize, HandoffReceiptSerialize } from "./generated-contracts.ts";
+import type { RadarClient, RadarResult } from "./radar-client.ts";
+import type { RadarPublication } from "./radar-publication.ts";
+
+export type RadarHandoffPort = {
+	/** Publish to this managed execution's Radar-recorded parent. Retry an uncertain result with the same ID and bytes. */
+	publish(request: {
+		request_id: string;
+		correlation_id?: string;
+		summary: string;
+		content: string;
+	}): Promise<RadarResult<{ handoff: HandoffSerialize; created: boolean }>>;
+	/** Durable inbox scan for this process's managed subject. Notifications are hints; callers can always rescan. */
+	inbox(): Promise<RadarResult<HandoffInboxSerialize>>;
+	/** Retrieve the full immutable content even after it has been acknowledged. */
+	get(handoff_id: string): Promise<RadarResult<{ handoff: HandoffSerialize; receipt: HandoffReceiptSerialize | null }>>;
+	/** Call only after the consumer durably recorded the retrieved payload. */
+	ack(handoff_id: string): Promise<RadarResult<{ receipt: HandoffReceiptSerialize; created: boolean }>>;
+};
+
+/**
+ * Bind handoff operations to this Pi process's Radar registration and the
+ * parent subject injected from its accepted managed-launch metadata.
+ */
+export function createRadarHandoffPort(
+	client: RadarClient,
+	publication: Pick<RadarPublication, "subject">,
+	parentSubjectId: () => string | undefined = () => process.env.PI_RADAR_MANAGED_PARENT_SUBJECT_ID,
+): RadarHandoffPort {
+	async function agentId(): Promise<RadarResult<string>> {
+		const subject = await publication.subject();
+		return subject === undefined
+			? { ok: false, code: "absent", message: "this process has no current Radar registration" }
+			: { ok: true, value: subject.agent_id };
+	}
+
+	return {
+		async publish(request) {
+			const identity = await agentId();
+			if (identity.ok === false) return identity;
+			const parent = parentSubjectId();
+			if (parent === undefined)
+				return { ok: false, code: "absent", message: "this managed execution has no Radar parent subject" };
+			return client.communicationPublish({
+				...request,
+				sender_agent_id: identity.value,
+				recipient_subject_id: parent,
+			});
+		},
+		async inbox() {
+			const identity = await agentId();
+			if (identity.ok === false) return identity;
+			return client.communicationInbox({ agent_id: identity.value });
+		},
+		async get(handoff_id) {
+			const identity = await agentId();
+			if (identity.ok === false) return identity;
+			return client.communicationGet({ agent_id: identity.value, handoff_id });
+		},
+		async ack(handoff_id) {
+			const identity = await agentId();
+			if (identity.ok === false) return identity;
+			return client.communicationAck({ agent_id: identity.value, handoff_id });
+		},
+	};
+}

package/extension/radar-execution.ts

@@ -3,6 +3,7 @@ import {
 	isUuid,
 	type RadarScheduler,
 	type RadarSnapshot,
+	type RadarLaunchIdentityMarker,
 } from "./radar-client.ts";
 import type { RadarLocationResolution } from "./radar-location.ts";
 import type { RadarFactsSnapshot } from "./radar-client.ts";
@@ -19,6 +20,11 @@ import {
 	type RadarPublication,
 	type RadarChannelWriter,
 } from "./radar-publication.ts";
+import {
+	activeRadarLaunchMarker,
+	persistRadarLaunchMarker,
+	radarLaunchMarkerFromEnvironment,
+} from "./radar-session-marker.ts";
 
 /**
  * The minimal Pi surface this adapter uses. It is declared structurally so the
@@ -26,6 +32,7 @@ import {
  * be lifted into its own extension without touching this module.
  */
 export type RadarExecutionEventApi = {
+	appendEntry?: (customType: string, data?: unknown) => void;
 	on(name: string, handler: (event: any, context: any) => unknown): unknown;
 	events?: {
 		on(name: string, handler: (event: any) => unknown): unknown;
@@ -63,6 +70,10 @@ export type RadarExecutionOptions = {
 	 * where no such event exists.
 	 */
 	questionnaireEvent?: string;
+	/** Best-effort diagnostic for durable session marker failures. */
+	diagnostic?: (message: string) => void;
+	/** Injectable only for tests; production reads the daemon-issued process env. */
+	markerEnvironment?: Record<string, string | undefined>;
 };
 
 export type RadarExecutionAdapter = {
@@ -258,11 +269,14 @@ export function createRadarExecutionAdapter(
 	 * canonical UUID is left unreported: absent context is unknown, and publishing
 	 * the explicit null would claim there is no session at all.
 	 */
-	function reportSession(context: any): void {
+	function reportSession(
+		context: any,
+		launchIdentity?: RadarLaunchIdentityMarker,
+	): void {
 		const session = context?.sessionManager?.getSessionId?.();
 		if (!isUuid(session)) return;
 		try {
-			publication.context.update(session);
+			publication.context.update(session, launchIdentity);
 		} catch {
 			// Optional publication must not interfere with Pi's lifecycle handler.
 		}
@@ -346,10 +360,49 @@ export function createRadarExecutionAdapter(
 		);
 
 	on("session_start", (_event, context) => {
+		const sessionHost = {
+			appendEntry: pi.appendEntry
+				? (customType: string, data?: unknown) => pi.appendEntry?.(customType, data)
+				: undefined,
+			sessionManager: context?.sessionManager,
+		};
+		let launchIdentity: RadarLaunchIdentityMarker | undefined;
+		try {
+			const result = persistRadarLaunchMarker(
+				sessionHost,
+				options.markerEnvironment,
+			);
+			if (result === "written" || result === "unchanged") {
+				const expected = radarLaunchMarkerFromEnvironment(options.markerEnvironment);
+				const activeMarker = activeRadarLaunchMarker(sessionHost);
+				if (
+					expected &&
+					activeMarker.status === "valid" &&
+					JSON.stringify(activeMarker.marker) === JSON.stringify(expected)
+				) {
+					launchIdentity = activeMarker.marker;
+				} else {
+					options.diagnostic?.("Radar launch marker was not visible on the active Pi session branch");
+				}
+			} else if (result === "unsupported") {
+				options.diagnostic?.("Pi host does not support Radar launch identity session entries");
+			} else if (
+				options.markerEnvironment &&
+				[
+					"PI_RADAR_MANAGED_SUBJECT_ID",
+					"PI_RADAR_MANAGED_LAUNCH_ID",
+					"PI_RADAR_MANAGED_EXECUTION_GENERATION",
+				].some((key) => options.markerEnvironment?.[key] !== undefined)
+			) {
+				options.diagnostic?.("incomplete or invalid Radar launch identity environment");
+			}
+		} catch (error) {
+			options.diagnostic?.(`could not persist Radar launch marker: ${String(error)}`);
+		}
 		rootSession = true;
 		// The session comes first: re-arming the publication must renew the session
 		// this process is in now, never the one a previous session left behind.
-		reportSession(context);
+		reportSession(context, launchIdentity);
 		// Facts follow the root flag, so they are published only after it is set.
 		publishFacts(context);
 		// A process can replace or resume its session without a new process, so the

package/extension/radar-launch.ts

@@ -64,9 +64,11 @@ export type LaunchMailbox<State extends LaunchState> = {
  * different leaves the launch unresolved rather than placed.
  */
 
-/** The exact parent this launch may use, and nothing inferred about it. */
+/** The exact managed parent this launch may use, and nothing inferred about it. */
 export type RadarLaunchParent = {
 	agent_id: string;
+	/** Stable subject from this process's current Radar registration. */
+	subject_id: string;
 	location?: RadarLocation;
 };
 
@@ -395,6 +397,10 @@ export async function launchRadarWorker<State extends LaunchState>(
 		return refusedLaunch(
 			"the launch has no exact parent registration to spawn under",
 		);
+	if (!isUuid(launch.parent.subject_id))
+		return refusedLaunch(
+			"the launch has no managed Radar subject for its parent",
+		);
 	// A spawn is created under the pane its parent registered, and this port
 	// registers no location it was not given: without one there is nothing to
 	// place the child beside, and a name or session lookup is not a substitute.
@@ -408,6 +414,7 @@ export async function launchRadarWorker<State extends LaunchState>(
 		parent: launch.parent.agent_id,
 		parent_session_id: launch.parent_session_id,
 		executable: launch.executable,
+		managed: { parent_subject_id: launch.parent.subject_id },
 		argv: launch.argv,
 		...(launch.cwd !== "" ? { cwd: launch.cwd } : {}),
 		...(Object.keys(launch.env).length > 0 ? { env: launch.env } : {}),

package/extension/radar-location.ts

@@ -153,7 +153,8 @@ export async function resolveRadarProcessLocation(
 	const backend = ready.value.backend;
 	if (backend === undefined || backend === "none")
 		return { state: "absent", reason: "the daemon serves no physical backend" };
-	const own = qualifiedOwnPane(env, backend, ready.value.instance);
+	const instance = ready.value.instance ?? undefined;
+	const own = qualifiedOwnPane(env, backend, instance);
 	if ("absent" in own) return { state: "absent", reason: own.absent };
 	if ("pending" in own) return { state: "pending", reason: own.pending };
 	const paneId = own.pane;
@@ -186,7 +187,6 @@ export async function resolveRadarProcessLocation(
 	if ("ambiguous" in containment)
 		return { state: "pending", reason: containment.ambiguous };
 	const row = containment.pane;
-	const instance = ready.value.instance;
 	return {
 		state: "resolved",
 		location: {