pi-radar 0.7.0 → 0.10.0

package/README.md

@@ -35,6 +35,18 @@ The client uses `registry.v1` for registry operations and additionally requires
 
 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.
 
+## Launching a worker
+
+`launchRadarWorker` takes the parent from the caller's own `publication`, so a consumer passes the pane it splits and no registration or subject for the parent. The result names the child by its `subject_id`, the key that stays the same when the child restarts or resumes; keep that as the child's identifier. A received handoff carries its sender's `subject_id`; match children by it.
+
+To start a released child again, pass `continues: subject_id`: the daemon takes the session from its own record, so no session id or path is sent, and it refuses a child that is not yours or is still running. `client.restart` replaces your own live child under a new program. Both need Radar 0.4.0 or newer.
+
+A launch is ready when the daemon grants the child's first presence, and `failed` when the daemon withdraws it. The daemon owns a 30-second deadline and records the withdrawal on the launch, so `failed` means the launch is already cleaned up and a retry is safe. `launchRadarWorker` has no timeout of its own; pass a `signal` to stop waiting. `unresolved` is left for a launch whose outcome cannot be read at all. `children.restart(subject, program)` replaces a live child in its own pane and waits on the same outcome.
+
+## Addressing children by subject
+
+The runtime's `children` service (`RADAR_RUNTIME_VERSION` 4) is the surface for everything after a launch. `list()` returns the caller's children as `{ subject_id, request_id, pane_id, state, exited }`; `observe`, `inspect`, `assignment` and `retire` take the subject. pi-radar resolves a subject to its newest bound launch on every call and never remembers the process, so a child replaced under the same subject is reached by the same key. A held assignment follows a replaced child: the next `list`, `observe` or `inspect` finds the new process and moves the assignment onto it, retiring it from the old one. Consumers need no registration or claim id.
+
 ## 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/`. They are this package's contract of record: a daemon change lands as a schema regeneration, and the method-to-schema index lives in `docs/agent-registration.md` in the Radar repository. Serialize and deserialize schemas are separate because Serde defaults, null handling and omission differ by direction. The SDK's ping, Pi presence report/answer/release, handoff inbox, publication-parameter, immutable handoff, receipt, managed-launch-metadata input, facts-input, spawn-exit, and observation request/snapshot/response types are generated into `extension/generated-contracts.ts`; do not edit that file by hand.

package/dist/extension/baseline.js

@@ -8,12 +8,13 @@ import { lstatSync } from "node:fs";
 import { createConnection } from "node:net";
 import { dirname, join } from "node:path";
 var RADAR_PROTOCOL_VERSION = 2;
-var RADAR_MINIMUM_REVISION = 6;
+var RADAR_MINIMUM_REVISION = 8;
 var RADAR_REGISTRY_CONTRACT = "registry.v1";
 var RADAR_REGISTRY_FACTS_CONTRACT = "registry.facts.v1";
 var RADAR_SPAWN_CONTRACT = "spawn.v1";
 var RADAR_SPAWN_LIST_CONTRACT = "spawn.list.v1";
 var RADAR_SPAWN_CLOSE_CONTRACT = "spawn.close.v1";
+var RADAR_LIFECYCLE_RESTART_CONTRACT = "lifecycle.restart.v1";
 var RADAR_SPAWN_LAUNCH_CONTEXT_CONTRACT = "spawn.launch_context.v1";
 var RADAR_EVENTS_CONTRACT = "events.v1";
 var RADAR_COMMUNICATION_CONTRACT = "communication.handoff.v1";
@@ -315,7 +316,11 @@ function spawnEdge(value) {
   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: {
@@ -328,10 +333,13 @@ function spawnEdge(value) {
         bound: {
           source,
           incarnation,
-          ...isUuid(agentId) ? { registration_id: agentId } : {}
+          ...isUuid(agentId) ? { registration_id: agentId } : {},
+          ...isUuid(subjectId) ? { subject_id: subjectId } : {}
         }
       } : {},
-      ...exit !== void 0 ? { exit_observation: exit } : {}
+      ...exit !== void 0 ? { exit_observation: exit } : {},
+      ...stringAt(value, "granted_at") !== void 0 ? { granted_at: stringAt(value, "granted_at") } : {},
+      ...withdrawnAt !== void 0 && withdrawnReason !== void 0 ? { withdrawn: { at: withdrawnAt, reason: withdrawnReason } } : {}
     }
   };
 }
@@ -400,6 +408,8 @@ function spawnTopology(value) {
 function spawnRequestShape(request) {
   if (!isUuid(request.request_id))
     return "spawn requires a canonical request UUID";
+  if (request.continue_subject_id !== void 0 && !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))
@@ -808,7 +818,8 @@ function createRadarClient(options = {}) {
                 argv: request.argv,
                 ...request.cwd !== void 0 ? { cwd: request.cwd } : {},
                 ...carriesContext && request.env !== void 0 ? { env: request.env } : {},
-                ...request.managed !== void 0 ? { managed: request.managed } : {}
+                ...request.managed !== void 0 ? { managed: request.managed } : {},
+                ...request.continue_subject_id !== void 0 ? { continue_subject_id: request.continue_subject_id } : {}
               },
               requester
             },
@@ -836,6 +847,37 @@ function createRadarClient(options = {}) {
         }
       );
     },
+    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 !== void 0 ? { cwd: request.cwd } : {},
+              ...request.env !== void 0 ? { 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 === void 0)
@@ -1203,6 +1245,339 @@ function boundedRadarSnapshot(snapshot) {
   };
 }
 
+// extension/radar-children.ts
+import { randomUUID as randomUUID2 } from "node:crypto";
+
+// extension/radar-inspection.ts
+var INSPECTION_LINES = 80;
+var INSPECTION_OUTPUT_BYTES = 16 * 1024;
+async function provedRead(client, target) {
+  const read = await client.agentGet(target.agentId);
+  return read.ok === true && read.value.verification === "verified" && read.value.location?.pane === target.paneId && (target.session === void 0 || read.value.contextSession === target.session) ? read.value : void 0;
+}
+async function inspectRadarChild(client, target) {
+  const before = await provedRead(client, target);
+  if (before === void 0)
+    throw new Error("Inspection target identity did not match");
+  const output = await client.output({
+    pane_id: target.paneId,
+    source: "recent_unwrapped",
+    lines: INSPECTION_LINES
+  });
+  if (output.ok === false)
+    throw new Error(
+      `Inspection output unavailable (${output.code}: ${output.message})`
+    );
+  const foreground = await client.processInfo({ pane_id: target.paneId });
+  const after = await provedRead(client, target);
+  if (after === void 0)
+    throw new Error("Inspection target changed during capture");
+  const lines = output.value.text.trim().split(/\r?\n/).slice(-INSPECTION_LINES);
+  const bounded2 = utf8Tail(lines.join("\n"), INSPECTION_OUTPUT_BYTES);
+  return Object.freeze({
+    capturedAt: Date.now(),
+    recentOutputTruncated: output.value.truncated || bounded2.truncated,
+    ...bounded2.text ? { recentOutput: bounded2.text } : {},
+    ...foreground.ok === true ? { foreground: foreground.value } : {},
+    ...after.activity !== void 0 ? { activity: after.activity } : {}
+  });
+}
+function utf8Tail(value, maxBytes) {
+  const bytes = Buffer.from(value);
+  if (bytes.length <= maxBytes) return { text: value, truncated: false };
+  let start = bytes.length - maxBytes;
+  while (start < bytes.length && (bytes[start] & 192) === 128) start++;
+  return { text: bytes.subarray(start).toString(), truncated: true };
+}
+
+// extension/radar-launch.ts
+import { setTimeout as delay } from "node:timers/promises";
+function unknownChild(reason) {
+  return { kind: "unknown", diagnostic: trajectory(reason) };
+}
+function trajectory(reason) {
+  return `the daemon's current record of this launch's child is ${reason}`;
+}
+async function observeRadarChild(client, provenance) {
+  if (provenance.registration_id === void 0)
+    return unknownChild("not bound to a child by this launch");
+  if (provenance.pane_id === void 0)
+    return unknownChild("without a pane this launch recorded for it");
+  const read = await client.spawnGet(provenance.request_id);
+  if (read.ok === false)
+    return unknownChild(
+      `not readable (${read.code}: ${read.message})`
+    );
+  const topology = read.value;
+  const edge = topology.edge;
+  if (edge.bound === void 0 || edge.bound.registration_id === void 0)
+    return unknownChild("not bound to a child by the daemon");
+  if (edge.bound.registration_id !== provenance.registration_id)
+    return unknownChild(
+      `bound to another subject (${edge.bound.registration_id}), not to ${provenance.registration_id}`
+    );
+  if (edge.location?.pane === void 0)
+    return unknownChild("recorded without a pane");
+  if (edge.location.pane !== provenance.pane_id)
+    return unknownChild(
+      `recorded on pane ${edge.location.pane}, not on ${provenance.pane_id}`
+    );
+  if (edge.exit_observation?.state !== "unknown")
+    return unknownChild("recorded with an observed process exit");
+  if (topology.freshness !== "fresh")
+    return unknownChild(
+      "on a pane the daemon's own inventory does not currently report"
+    );
+  if (topology.state !== "bound")
+    return unknownChild(
+      `not currently placed (state ${topology.state ?? "unreported"})`
+    );
+  const reply = await client.agentGet(edge.bound.registration_id);
+  if (reply.ok === false)
+    return unknownChild(
+      `process verdict not readable (${reply.code}: ${reply.message})`
+    );
+  const { verification, location, contextSession } = reply.value;
+  if (verification === "absent" || verification === "mismatched")
+    return {
+      kind: "gone",
+      verification,
+      diagnostic: trajectory(`the registered process is ${verification}`)
+    };
+  if (verification !== "verified")
+    return unknownChild(`process verdict is ${verification}`);
+  if (location?.pane !== provenance.pane_id)
+    return unknownChild(
+      `registered on ${location?.pane ?? "no pane"}, not on ${provenance.pane_id}`
+    );
+  if (provenance.session_id === void 0)
+    return unknownChild("without a session this launch recorded for it");
+  if (contextSession !== provenance.session_id)
+    return unknownChild(
+      `publishing session ${contextSession ?? "none"}, not ${provenance.session_id}`
+    );
+  return {
+    kind: "live",
+    evidence: {
+      request_id: provenance.request_id,
+      registration_id: edge.bound.registration_id,
+      source: edge.bound.source,
+      incarnation: edge.bound.incarnation,
+      pane_id: edge.location.pane
+    }
+  };
+}
+function refusedLaunch(message) {
+  return { kind: "failed", message };
+}
+function unresolvedLaunch(requestId, message) {
+  return {
+    kind: "unresolved",
+    request_id: requestId,
+    message: `spawn ${requestId} is unresolved (${message})`
+  };
+}
+var PRE_EFFECT_CODES = [
+  "absent",
+  "unsupported",
+  "bad_version",
+  "bad_request",
+  "bad_params",
+  "unknown_method",
+  "refused",
+  "not_found",
+  "busy",
+  "backend_unavailable"
+];
+function launchFailure(result, requestId) {
+  return PRE_EFFECT_CODES.includes(result.code) ? refusedLaunch(result.message) : unresolvedLaunch(requestId, result.message);
+}
+async function waitForChild(client, requestId, options) {
+  let last = "the daemon has not answered";
+  for (; ; ) {
+    if (options.signal?.aborted)
+      return unresolvedLaunch(requestId, `the launch was cancelled (${last})`);
+    const answer = await client.spawnGet(requestId);
+    if (answer.ok === true) {
+      const { edge } = answer.value;
+      if (edge.withdrawn !== void 0)
+        return refusedLaunch(`the daemon withdrew this launch: ${edge.withdrawn.reason}`);
+      if (edge.granted_at === void 0) {
+        await delay(options.pollMs);
+        continue;
+      }
+      const pane = edge.location?.pane;
+      if (pane === void 0 || pane === "")
+        return unresolvedLaunch(
+          requestId,
+          "the daemon's launch recorded no pane to verify the child against"
+        );
+      const agentId = edge.bound?.registration_id;
+      if (agentId !== void 0 && isUuid(agentId)) {
+        const subjectId = edge.bound?.subject_id;
+        if (subjectId === void 0 || !isUuid(subjectId))
+          return unresolvedLaunch(
+            requestId,
+            `the daemon bound the child ${agentId} without recording its subject`
+          );
+        return {
+          kind: "bound",
+          subject_id: subjectId,
+          pane_id: pane
+        };
+      }
+      last = "no child has registered with this launch's token yet";
+    } else {
+      return unresolvedLaunch(requestId, answer.message);
+    }
+    await delay(options.pollMs);
+  }
+}
+
+// extension/radar-children.ts
+var PAGE = 100;
+var MAX_PAGES = 20;
+function createRadarChildren(client, publication) {
+  const held = /* @__PURE__ */ new Map();
+  async function resolveAll() {
+    const newest = /* @__PURE__ */ new Map();
+    let after;
+    for (let page = 0; page < MAX_PAGES; page++) {
+      const read = await client.spawnList({ ...after !== void 0 ? { after } : {}, limit: PAGE });
+      if (read.ok === false) return read;
+      for (const edge of read.value.spawns) {
+        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 !== void 0 && 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 resolve2(subject) {
+    const all = await resolveAll();
+    return all.ok ? all.value.get(subject) : void 0;
+  }
+  async function resolveAndFollow(subject) {
+    const all = await resolveAll();
+    if (!all.ok) return void 0;
+    follow(all.value);
+    return all.value.get(subject);
+  }
+  function follow(all) {
+    for (const [subject, entry] of held) {
+      const target = all.get(subject);
+      if (target !== void 0 && 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 === void 0)
+        return { kind: "failed", message: "this process has no Radar registration to restart a child under" };
+      const request_id = randomUUID2();
+      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 !== void 0 ? { 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 !== void 0) return existing.writer;
+      let latest;
+      const entry = { writer: void 0 };
+      const send = (target) => {
+        if (latest === void 0) return;
+        if (entry.published !== void 0 && 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 resolve2(subject).then((target) => {
+            if (target !== void 0) send(target);
+          });
+        },
+        retire() {
+          latest = void 0;
+          if (entry.published !== void 0) publication.retireAssignment(entry.published);
+          entry.published = void 0;
+        }
+      };
+      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 === void 0)
+        return { kind: "unknown", diagnostic: "the daemon records no bound launch for this child" };
+      return observeRadarChild(client, {
+        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 === void 0)
+        throw new Error("Inspection target is not a bound child with a pane");
+      return inspectRadarChild(client, {
+        agentId: target.registration_id,
+        paneId: target.child.pane_id,
+        ...session_id !== void 0 ? { session: session_id } : {}
+      });
+    }
+  };
+}
+
 // extension/radar-communication.ts
 function createRadarHandoffPort(client, publication, parentSubjectId = () => process.env.PI_RADAR_MANAGED_PARENT_SUBJECT_ID) {
   async function agentId() {
@@ -1241,7 +1616,7 @@ function createRadarHandoffPort(client, publication, parentSubjectId = () => pro
 }
 
 // extension/radar-publication.ts
-import { createHash, randomUUID as randomUUID2 } from "node:crypto";
+import { createHash, randomUUID as randomUUID3 } from "node:crypto";
 import {
   closeSync,
   constants,
@@ -1371,7 +1746,7 @@ function createPublicationStore(root) {
       ensureDirectory(directory);
       const temporary = join2(
         directory,
-        `.${name.slice(name.lastIndexOf("/") + 1)}.${randomUUID2()}.tmp`
+        `.${name.slice(name.lastIndexOf("/") + 1)}.${randomUUID3()}.tmp`
       );
       const bytes = Buffer.from(JSON.stringify(value), "utf8");
       if (bytes.length > MAX_RECORD_BYTES)
@@ -1427,7 +1802,7 @@ function radarProcessSlot() {
   return host[PROCESS_SLOT];
 }
 function radarProcessIncarnation(slot = radarProcessSlot()) {
-  return slot.incarnation ??= randomUUID2();
+  return slot.incarnation ??= randomUUID3();
 }
 function recordAt2(value, key) {
   if (typeof value !== "object" || value === null) return void 0;
@@ -1892,7 +2267,7 @@ function createPresenceReporter(input) {
         releases.push({ registration_id: state.registration_id, claim_id: state.claim_id });
       }
       standing = void 0;
-      state = { version: 2, session, claim_id: randomUUID2(), releases };
+      state = { version: 2, session, claim_id: randomUUID3(), releases };
       save();
       stopped = false;
       void ensure();
@@ -1929,7 +2304,7 @@ var STORE_IDENTITY = /* @__PURE__ */ new WeakMap();
 function storeIdentity(store) {
   const known = STORE_IDENTITY.get(store);
   if (known !== void 0) return known;
-  const created = randomUUID2();
+  const created = randomUUID3();
   STORE_IDENTITY.set(store, created);
   return created;
 }
@@ -2559,7 +2934,7 @@ async function resolveRadarProcessLocation(client, env = process.env) {
 
 // extension/radar-runtime.ts
 var RADAR_RUNTIME_REQUEST = "pi-radar/runtime-request";
-var RADAR_RUNTIME_VERSION = 2;
+var RADAR_RUNTIME_VERSION = 4;
 function lazyRadarRuntime(start) {
   let pending;
   return {
@@ -2588,6 +2963,7 @@ function registerPiRadar(pi) {
   const runtime = lazyRadarRuntime(async () => ({
     publication: execution.publication,
     communication: createRadarHandoffPort(client, execution.publication),
+    children: createRadarChildren(client, execution.publication),
     execution
   }));
   provideRadarRuntime(pi.events, runtime);