pi-radar 0.2.0 → 0.3.0

package/README.md

@@ -9,7 +9,7 @@ const radar = client.createRadarClient();
 const handshake = await radar.ping();
 ```
 
-Focused subpaths are also exported: `pi-radar/client`, `pi-radar/execution`, `pi-radar/publication`, `pi-radar/runtime`, `pi-radar/launch`, `pi-radar/location`, and `pi-radar/inspection`. The runtime subpath provides a versioned `pi.events` request/reply handoff so multiple extensions can consume one baseline publication without sharing bundled module singletons. `extension/radar-session-marker.ts` provides the versioned Pi custom-session-entry codec; it is correlation evidence only, not lifecycle authority. Existing extension deep imports under `pi-radar/extension/` remain exported.
+Focused subpaths are also exported: `pi-radar/client`, `pi-radar/communication`, `pi-radar/execution`, `pi-radar/publication`, `pi-radar/runtime`, `pi-radar/launch`, `pi-radar/location`, and `pi-radar/inspection`. The shared `runtime` handle exposes `services.communication`, a handoff port bound to the baseline's existing client, this process's current registration, and the managed parent injected by Radar. Callers do not choose sender or recipient identity; `communication.createRadarHandoffPort` is the underlying SDK factory. The runtime subpath provides a versioned `pi.events` request/reply handoff so multiple extensions can consume one baseline publication without sharing bundled module singletons. `extension/radar-session-marker.ts` provides the versioned Pi custom-session-entry codec; it is correlation evidence only, not lifecycle authority. Existing extension deep imports under `pi-radar/extension/` remain exported.
 
 ## Pi baseline extension
 
@@ -17,15 +17,19 @@ Installing `pi-radar` directly as a Pi package loads `extension/baseline.ts`, wh
 
 ## Daemon contract
 
-The client speaks protocol 2 and requires wire revision 3 or newer. Revision 3 makes lifecycle `subject_id` a stable logical identity and exposes the exact current `execution_id` and `u32` generation separately; the generation remains exactly representable as a JSON number. Clients that control managed executions must not target the legacy per-execution ID semantics. It reads `revision` and the public `contracts` list from `daemon.ping`, preserves unfamiliar contract names, and preflights only contracts needed for a multi-step or versioned operation. Backend `mux.*` primitives are private to the daemon; direct mux methods are dispatched and return the daemon's backend refusal when unavailable.
+The client speaks protocol 2 and requires wire revision 3 or newer for its existing lifecycle operations. Revision 3 made lifecycle `subject_id` a stable logical identity and exposed the exact current `execution_id` and `u32` generation separately. Handoff methods additionally require the independently negotiated `communication.handoff.v1` contract introduced at wire revision 4; its timestamps remain exactly representable as JSON numbers. Clients that control managed executions must not target the legacy per-execution ID semantics. It reads `revision` and the public `contracts` list from `daemon.ping`, preserves unfamiliar contract names, and preflights only contracts needed for a multi-step or versioned operation. Backend `mux.*` primitives are private to the daemon; direct mux methods are dispatched and return the daemon's backend refusal when unavailable.
 
-The client uses `registry.v1` for registry operations and additionally requires `registry.facts.v1` for the facts channel and assignment extensions. Managed children require `spawn.v1`, child-pane removal requires `spawn.close.v1`, and event reads require `events.v1`. The expected wire examples are maintained in this repository's `docs/control-plane.fixture.jsonl` and `docs/agent-registration.fixture.jsonl` and are exercised by the package tests.
+The client uses `registry.v1` for registry operations and additionally requires `registry.facts.v1` for the facts channel and assignment extensions. Managed children require `spawn.v1`, child-pane removal requires `spawn.close.v1`, event reads require `events.v1`, and handoff operations require `communication.handoff.v1`. The expected wire examples are maintained in this repository's `docs/control-plane.fixture.jsonl` and `docs/agent-registration.fixture.jsonl` and are exercised by the package tests.
 
 `RadarFactsSnapshot` matches the daemon facts channel: optional model/provider/thinking/session name, `context_window: { tokens, window }`, typed `background_tasks: { id, phase }[]`, and `background_started_unix_ms`. Context counts and the timestamp are JSON numbers bounded by JavaScript's safe-integer limit. The old text `context_usage` field is not accepted; Rust retains cross-field validation such as a positive window and tokens not exceeding it.
 
+## Durable handoffs
+
+The handoff API stores immutable bounded content separately from the recipient receipt. `inbox()` returns pending IDs only; retrieve each payload with `get()` and persist it before `ack()`, so a batch cannot exceed the RPC response bound. A worker's first Herdsman handoff is addressed only to the stable `parent_subject_id` recorded by Radar for its accepted managed launch. The parent gets its stable subject ID from `RadarSubject` and supplies it as `RadarWorkerLaunch.parent.subject_id`; `launchRadarWorker` forwards it as `managed.parent_subject_id`, and Radar injects the accepted value into the worker as `PI_RADAR_MANAGED_PARENT_SUBJECT_ID`. The handoff port reads that process context; callers cannot choose a destination. The daemon checks it against the durable parent record. Do not substitute a registration ID, Pi session, owner-session field, pane, or inferred lineage; unmanaged/session routing is deferred. The owner must durably capture the payload locally before calling `ack`; acknowledgement does not settle Herdsman assignment state or authorize worker closure. Pending inbox scans recover work after daemon restart or missed pointer events, and acknowledged content remains retrievable during the retention window. See `docs/control-plane.md` for wire shapes, bounds and recovery semantics.
+
 ## Generated protocol contracts
 
-The selected Rust wire DTOs are the source for the draft 2020-12 schemas in `schema/public/v1/`, shipped and exported under `pi-radar/schema/`. Serialize and deserialize schemas are separate because Serde defaults, null handling and omission differ by direction. The SDK's ping, managed-launch-metadata input, facts-input and spawn-exit types are generated into `extension/generated-contracts.ts`; do not edit that file by hand.
+The selected Rust wire DTOs are the source for the draft 2020-12 schemas in `schema/public/v1/`, shipped and exported under `pi-radar/schema/`. Serialize and deserialize schemas are separate because Serde defaults, null handling and omission differ by direction. The SDK's ping, handoff inbox, publication-parameter, immutable handoff, receipt, managed-launch-metadata input, facts-input and spawn-exit types are generated into `extension/generated-contracts.ts`; do not edit that file by hand.
 
 From the repository checkout, run `npm run generate:contracts` in this directory to regenerate schemas and TypeScript declarations. `npm test` checks the generated artifacts are current, typechecks the public SDK aliases, validates canonical wire fixtures and integer bounds against the schemas, and runs the package tests. Generation uses the locked Schemars crate plus pinned `json-schema-to-typescript` and TypeScript development dependencies; it adds no runtime package dependency.
 

package/dist/extension/baseline.js

@@ -15,6 +15,7 @@ var RADAR_SPAWN_CONTRACT = "spawn.v1";
 var RADAR_SPAWN_CLOSE_CONTRACT = "spawn.close.v1";
 var RADAR_SPAWN_LAUNCH_CONTEXT_CONTRACT = "spawn.launch_context.v1";
 var RADAR_EVENTS_CONTRACT = "events.v1";
+var RADAR_COMMUNICATION_CONTRACT = "communication.handoff.v1";
 var RADAR_REQUESTER = "pi-radar";
 var RADAR_MAX_LINE_BYTES = 1024 * 1024;
 var RADAR_CALL_TIMEOUT_MS = 2e3;
@@ -122,6 +123,28 @@ function numberAt(value, field) {
   const found = value[field];
   return typeof found === "number" && Number.isFinite(found) ? found : void 0;
 }
+function handoffAt(value) {
+  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.correlation_id : void 0;
+  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 === void 0 || content === void 0 || published === void 0 || !Number.isSafeInteger(published) || published < 0 || correlation !== void 0 && correlation !== null && (typeof correlation !== "string" || correlation.length === 0 || Buffer.byteLength(correlation, "utf8") > 256 || new RegExp("\\p{Cc}", "u").test(correlation))) return void 0;
+  return value;
+}
+function handoffReceiptAt(value) {
+  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 === void 0 || !Number.isSafeInteger(received) || received < 0) return void 0;
+  return value;
+}
 function writerBinding(value) {
   const handle = stringAt(value, "handle");
   const source = stringAt(value, "source");
@@ -227,7 +250,8 @@ var RADAR_SPAWN_TOKEN_ENV = "PI_RADAR_SPAWN_TOKEN";
 var RADAR_MANAGED_IDENTITY_ENV = /* @__PURE__ */ new Set([
   "PI_RADAR_MANAGED_SUBJECT_ID",
   "PI_RADAR_MANAGED_LAUNCH_ID",
-  "PI_RADAR_MANAGED_EXECUTION_GENERATION"
+  "PI_RADAR_MANAGED_EXECUTION_GENERATION",
+  "PI_RADAR_MANAGED_PARENT_SUBJECT_ID"
 ]);
 function unresolvedSpawn(requestId, detail) {
   return {
@@ -843,6 +867,56 @@ function createRadarClient(options = {}) {
         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 !== void 0 ? { 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 === void 0 || 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 };
+      });
+    },
+    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 === void 0 || receiptValue !== null && receipt === void 0)
+          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 === void 0 || 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) || request.after < 0 || !Number.isSafeInteger(request.wait_ms) || request.wait_ms < 0 || request.wait_ms > RADAR_EVENT_WAIT_MS)
         return {
@@ -1063,6 +1137,43 @@ function boundedRadarSnapshot(snapshot) {
   };
 }
 
+// extension/radar-communication.ts
+function createRadarHandoffPort(client, publication, parentSubjectId = () => process.env.PI_RADAR_MANAGED_PARENT_SUBJECT_ID) {
+  async function agentId() {
+    const subject = await publication.subject();
+    return subject === void 0 ? { 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 === void 0)
+        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 });
+    }
+  };
+}
+
 // extension/radar-publication.ts
 import { createHash, randomUUID as randomUUID2 } from "node:crypto";
 import {
@@ -2190,8 +2301,10 @@ function createRadarPublicationInner(options) {
       const record = await ensureRegistration();
       if (record === void 0) return void 0;
       const location = record.registration.location;
+      const subjectId = process.env.PI_RADAR_MANAGED_SUBJECT_ID;
       return {
         agent_id: agentId2,
+        ...subjectId !== void 0 ? { subject_id: subjectId } : {},
         ...location !== void 0 ? { location } : {}
       };
     },
@@ -2589,7 +2702,7 @@ async function resolveRadarProcessLocation(client, env = process.env) {
 
 // extension/radar-runtime.ts
 var RADAR_RUNTIME_REQUEST = "pi-radar/runtime-request";
-var RADAR_RUNTIME_VERSION = 1;
+var RADAR_RUNTIME_VERSION = 2;
 function lazyRadarRuntime(start) {
   let pending;
   return {
@@ -2617,6 +2730,7 @@ function registerPiRadar(pi) {
   });
   const runtime = lazyRadarRuntime(async () => ({
     publication: execution.publication,
+    communication: createRadarHandoffPort(client, execution.publication),
     execution
   }));
   provideRadarRuntime(pi.events, runtime);

package/dist/extension/radar-client.js

@@ -11,6 +11,7 @@ var RADAR_SPAWN_CONTRACT = "spawn.v1";
 var RADAR_SPAWN_CLOSE_CONTRACT = "spawn.close.v1";
 var RADAR_SPAWN_LAUNCH_CONTEXT_CONTRACT = "spawn.launch_context.v1";
 var RADAR_EVENTS_CONTRACT = "events.v1";
+var RADAR_COMMUNICATION_CONTRACT = "communication.handoff.v1";
 var RADAR_REQUESTER = "pi-radar";
 var RADAR_MAX_LINE_BYTES = 1024 * 1024;
 var RADAR_CALL_TIMEOUT_MS = 2e3;
@@ -118,6 +119,28 @@ function numberAt(value, field) {
   const found = value[field];
   return typeof found === "number" && Number.isFinite(found) ? found : void 0;
 }
+function handoffAt(value) {
+  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.correlation_id : void 0;
+  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 === void 0 || content === void 0 || published === void 0 || !Number.isSafeInteger(published) || published < 0 || correlation !== void 0 && correlation !== null && (typeof correlation !== "string" || correlation.length === 0 || Buffer.byteLength(correlation, "utf8") > 256 || new RegExp("\\p{Cc}", "u").test(correlation))) return void 0;
+  return value;
+}
+function handoffReceiptAt(value) {
+  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 === void 0 || !Number.isSafeInteger(received) || received < 0) return void 0;
+  return value;
+}
 function writerBinding(value) {
   const handle = stringAt(value, "handle");
   const source = stringAt(value, "source");
@@ -227,7 +250,8 @@ var RADAR_SPAWN_TOKEN_ENV = "PI_RADAR_SPAWN_TOKEN";
 var RADAR_MANAGED_IDENTITY_ENV = /* @__PURE__ */ new Set([
   "PI_RADAR_MANAGED_SUBJECT_ID",
   "PI_RADAR_MANAGED_LAUNCH_ID",
-  "PI_RADAR_MANAGED_EXECUTION_GENERATION"
+  "PI_RADAR_MANAGED_EXECUTION_GENERATION",
+  "PI_RADAR_MANAGED_PARENT_SUBJECT_ID"
 ]);
 function unresolvedSpawn(requestId, detail) {
   return {
@@ -901,6 +925,56 @@ function createRadarClient(options = {}) {
         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 !== void 0 ? { 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 === void 0 || 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 };
+      });
+    },
+    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 === void 0 || receiptValue !== null && receipt === void 0)
+          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 === void 0 || 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) || request.after < 0 || !Number.isSafeInteger(request.wait_ms) || request.wait_ms < 0 || request.wait_ms > RADAR_EVENT_WAIT_MS)
         return {
@@ -1122,6 +1196,7 @@ function boundedRadarSnapshot(snapshot) {
 }
 export {
   RADAR_CALL_TIMEOUT_MS,
+  RADAR_COMMUNICATION_CONTRACT,
   RADAR_EVENTS_CONTRACT,
   RADAR_EVENT_RETRY_MS,
   RADAR_MAX_AWAITED,

package/dist/extension/radar-communication.js

@@ -0,0 +1,39 @@
+// extension/radar-communication.ts
+function createRadarHandoffPort(client, publication, parentSubjectId = () => process.env.PI_RADAR_MANAGED_PARENT_SUBJECT_ID) {
+  async function agentId() {
+    const subject = await publication.subject();
+    return subject === void 0 ? { 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 === void 0)
+        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 });
+    }
+  };
+}
+export {
+  createRadarHandoffPort
+};

package/dist/extension/radar-execution.js

@@ -1221,8 +1221,10 @@ function createRadarPublicationInner(options) {
       const record = await ensureRegistration();
       if (record === void 0) return void 0;
       const location = record.registration.location;
+      const subjectId = process.env.PI_RADAR_MANAGED_SUBJECT_ID;
       return {
         agent_id: agentId2,
+        ...subjectId !== void 0 ? { subject_id: subjectId } : {},
         ...location !== void 0 ? { location } : {}
       };
     },

package/dist/extension/radar-launch.js

@@ -146,6 +146,10 @@ async function launchRadarWorker(options) {
     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"
+    );
   if (pane === void 0 || pane === "")
     return refusedLaunch(
       "this process's Radar registration names no pane, so it cannot be a spawn parent"
@@ -155,6 +159,7 @@ async function launchRadarWorker(options) {
     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/dist/extension/radar-publication.js

@@ -1176,8 +1176,10 @@ function createRadarPublicationInner(options) {
       const record = await ensureRegistration();
       if (record === void 0) return void 0;
       const location = record.registration.location;
+      const subjectId = process.env.PI_RADAR_MANAGED_SUBJECT_ID;
       return {
         agent_id: agentId2,
+        ...subjectId !== void 0 ? { subject_id: subjectId } : {},
         ...location !== void 0 ? { location } : {}
       };
     },

package/dist/extension/radar-runtime.js

@@ -1,6 +1,6 @@
 // extension/radar-runtime.ts
 var RADAR_RUNTIME_REQUEST = "pi-radar/runtime-request";
-var RADAR_RUNTIME_VERSION = 1;
+var RADAR_RUNTIME_VERSION = 2;
 function lazyRadarRuntime(start) {
   let pending;
   return {

package/dist/index.js

@@ -8,6 +8,7 @@ var __export = (target, all) => {
 var radar_client_exports = {};
 __export(radar_client_exports, {
   RADAR_CALL_TIMEOUT_MS: () => RADAR_CALL_TIMEOUT_MS,
+  RADAR_COMMUNICATION_CONTRACT: () => RADAR_COMMUNICATION_CONTRACT,
   RADAR_EVENTS_CONTRACT: () => RADAR_EVENTS_CONTRACT,
   RADAR_EVENT_RETRY_MS: () => RADAR_EVENT_RETRY_MS,
   RADAR_MAX_AWAITED: () => RADAR_MAX_AWAITED,
@@ -45,6 +46,7 @@ var RADAR_SPAWN_CONTRACT = "spawn.v1";
 var RADAR_SPAWN_CLOSE_CONTRACT = "spawn.close.v1";
 var RADAR_SPAWN_LAUNCH_CONTEXT_CONTRACT = "spawn.launch_context.v1";
 var RADAR_EVENTS_CONTRACT = "events.v1";
+var RADAR_COMMUNICATION_CONTRACT = "communication.handoff.v1";
 var RADAR_REQUESTER = "pi-radar";
 var RADAR_MAX_LINE_BYTES = 1024 * 1024;
 var RADAR_CALL_TIMEOUT_MS = 2e3;
@@ -152,6 +154,28 @@ function numberAt(value, field) {
   const found = value[field];
   return typeof found === "number" && Number.isFinite(found) ? found : void 0;
 }
+function handoffAt(value) {
+  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.correlation_id : void 0;
+  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 === void 0 || content === void 0 || published === void 0 || !Number.isSafeInteger(published) || published < 0 || correlation !== void 0 && correlation !== null && (typeof correlation !== "string" || correlation.length === 0 || Buffer.byteLength(correlation, "utf8") > 256 || new RegExp("\\p{Cc}", "u").test(correlation))) return void 0;
+  return value;
+}
+function handoffReceiptAt(value) {
+  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 === void 0 || !Number.isSafeInteger(received) || received < 0) return void 0;
+  return value;
+}
 function writerBinding(value) {
   const handle = stringAt(value, "handle");
   const source = stringAt(value, "source");
@@ -261,7 +285,8 @@ var RADAR_SPAWN_TOKEN_ENV = "PI_RADAR_SPAWN_TOKEN";
 var RADAR_MANAGED_IDENTITY_ENV = /* @__PURE__ */ new Set([
   "PI_RADAR_MANAGED_SUBJECT_ID",
   "PI_RADAR_MANAGED_LAUNCH_ID",
-  "PI_RADAR_MANAGED_EXECUTION_GENERATION"
+  "PI_RADAR_MANAGED_EXECUTION_GENERATION",
+  "PI_RADAR_MANAGED_PARENT_SUBJECT_ID"
 ]);
 function unresolvedSpawn(requestId, detail) {
   return {
@@ -935,6 +960,56 @@ function createRadarClient(options = {}) {
         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 !== void 0 ? { 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 === void 0 || 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 };
+      });
+    },
+    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 === void 0 || receiptValue !== null && receipt === void 0)
+          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 === void 0 || 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) || request.after < 0 || !Number.isSafeInteger(request.wait_ms) || request.wait_ms < 0 || request.wait_ms > RADAR_EVENT_WAIT_MS)
         return {
@@ -1155,6 +1230,47 @@ function boundedRadarSnapshot(snapshot) {
   };
 }
 
+// extension/radar-communication.ts
+var radar_communication_exports = {};
+__export(radar_communication_exports, {
+  createRadarHandoffPort: () => createRadarHandoffPort
+});
+function createRadarHandoffPort(client, publication, parentSubjectId = () => process.env.PI_RADAR_MANAGED_PARENT_SUBJECT_ID) {
+  async function agentId() {
+    const subject = await publication.subject();
+    return subject === void 0 ? { 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 === void 0)
+        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 });
+    }
+  };
+}
+
 // extension/radar-execution.ts
 var radar_execution_exports = {};
 __export(radar_execution_exports, {
@@ -2307,8 +2423,10 @@ function createRadarPublicationInner(options) {
       const record = await ensureRegistration();
       if (record === void 0) return void 0;
       const location = record.registration.location;
+      const subjectId = process.env.PI_RADAR_MANAGED_SUBJECT_ID;
       return {
         agent_id: agentId2,
+        ...subjectId !== void 0 ? { subject_id: subjectId } : {},
         ...location !== void 0 ? { location } : {}
       };
     },
@@ -2910,6 +3028,10 @@ async function launchRadarWorker(options) {
     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"
+    );
   if (pane === void 0 || pane === "")
     return refusedLaunch(
       "this process's Radar registration names no pane, so it cannot be a spawn parent"
@@ -2919,6 +3041,7 @@ async function launchRadarWorker(options) {
     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 } : {}
@@ -3056,7 +3179,7 @@ __export(radar_runtime_exports, {
   requestRadarRuntime: () => requestRadarRuntime
 });
 var RADAR_RUNTIME_REQUEST = "pi-radar/runtime-request";
-var RADAR_RUNTIME_VERSION = 1;
+var RADAR_RUNTIME_VERSION = 2;
 function lazyRadarRuntime(start) {
   let pending;
   return {
@@ -3091,6 +3214,7 @@ function isRadarRuntimeHandle(value) {
 }
 export {
   radar_client_exports as client,
+  radar_communication_exports as communication,
   radar_execution_exports as execution,
   radar_inspection_exports as inspection,
   radar_launch_exports as launch,

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 { createRadarHandoffPort } from "./radar-communication.ts";
 import {
 	createRadarExecutionAdapter,
 	type RadarExecutionEventApi,
@@ -31,6 +32,7 @@ export default function registerPiRadar(pi: PiRadarHost): void {
 	});
 	const runtime = lazyRadarRuntime(async () => ({
 		publication: execution.publication,
+		communication: createRadarHandoffPort(client, execution.publication),
 		execution,
 	}));
 	provideRadarRuntime(pi.events, runtime);