pi-radar 0.7.0 → 0.9.0

package/README.md

@@ -35,6 +35,16 @@ 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.
+
+## Addressing children by subject
+
+The runtime's `children` service (`RADAR_RUNTIME_VERSION` 3) 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 = 7;
 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,6 +316,7 @@ 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"));
   return {
     ok: true,
@@ -328,7 +330,8 @@ 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 } : {}
@@ -400,6 +403,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 +813,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 +842,33 @@ 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;
+        return focusOutcome(recordAt(answer.value, "request"), request.request_id);
+      });
+    },
     async spawnList(request) {
       const registrationId = processRegistrationId;
       if (registrationId === void 0)
@@ -1203,6 +1236,348 @@ function boundedRadarSnapshot(snapshot) {
   };
 }
 
+// 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-location.ts
+import { basename } from "node:path";
+function radarLocalPane(env) {
+  const pane = env.TMUX_PANE?.trim();
+  return pane && /^%\d+$/.test(pane) ? pane : void 0;
+}
+function tmuxServerName(env) {
+  const socket = env.TMUX?.trim().split(",")[0];
+  return socket ? basename(socket) || void 0 : void 0;
+}
+function qualifiedOwnPane(env, backend, instance) {
+  if (backend !== "tmux")
+    return {
+      absent: `the daemon serves the ${backend} backend, and Herdsman drives only tmux`
+    };
+  if (instance === void 0 || instance === "")
+    return {
+      pending: "the daemon did not name the tmux server it addresses"
+    };
+  const server = tmuxServerName(env);
+  if (server === void 0)
+    return {
+      absent: "this process's own tmux client names no server, so it is not in the pane it would publish"
+    };
+  if (server !== instance)
+    return {
+      absent: `this process is attached to tmux server ${server}, not to ${instance}`
+    };
+  const pane = radarLocalPane(env);
+  if (pane === void 0)
+    return {
+      absent: "this process's own environment names no tmux pane of that server"
+    };
+  return { pane: `tmux:${instance}:${pane}` };
+}
+function observedContainment(inventory, paneId) {
+  const rows = inventory.panes.filter((pane) => pane.pane_id === paneId);
+  if (rows.length === 0) return void 0;
+  if (rows.length > 1) return { ambiguous: `topology reports pane ${paneId} twice` };
+  const row = rows[0];
+  const tab = inventory.tabs.find((candidate) => candidate.tab_id === row.tab_id);
+  if (tab !== void 0 && tab.workspace_id !== row.workspace_id)
+    return {
+      ambiguous: `pane ${paneId} is reported in ${row.workspace_id}, but its tab belongs to ${tab.workspace_id}`
+    };
+  return { pane: row };
+}
+async function resolveRadarProcessLocation(client, env = process.env) {
+  let ready;
+  try {
+    ready = await client.ping();
+  } catch {
+    return { state: "pending", reason: "the daemon did not answer this process" };
+  }
+  if (ready.ok === false)
+    return {
+      state: "pending",
+      reason: `the daemon did not answer this process (${ready.code})`
+    };
+  const backend = ready.value.backend;
+  if (backend === void 0 || backend === "none")
+    return { state: "absent", reason: "the daemon serves no physical backend" };
+  const instance = ready.value.instance ?? void 0;
+  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;
+  if (paneId === env.PI_HERDSMAN_PARENT_PANE_ID?.trim())
+    return {
+      state: "absent",
+      reason: "this process is in the pane its launch was created beside, not in a pane of its own"
+    };
+  let inventory;
+  try {
+    inventory = await client.observe();
+  } catch {
+    return {
+      state: "pending",
+      reason: "the daemon's topology could not be read for this process's pane"
+    };
+  }
+  if (inventory.ok === false)
+    return {
+      state: "pending",
+      reason: `the daemon's topology could not be read (${inventory.code})`
+    };
+  const containment = observedContainment(inventory.value, paneId);
+  if (containment === void 0)
+    return {
+      state: "pending",
+      reason: `the daemon's topology does not report pane ${paneId} yet`
+    };
+  if ("ambiguous" in containment)
+    return { state: "pending", reason: containment.ambiguous };
+  const row = containment.pane;
+  return {
+    state: "resolved",
+    location: {
+      backend,
+      ...instance !== void 0 ? { instance } : {},
+      workspace: row.workspace_id,
+      tab: row.tab_id,
+      pane: paneId
+    }
+  };
+}
+
+// extension/radar-launch.ts
+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
+    }
+  };
+}
+
+// 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.launched !== "completed") 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) };
+    },
+    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() {
@@ -2450,116 +2825,9 @@ function createRadarExecutionAdapter(pi, options) {
   };
 }
 
-// extension/radar-location.ts
-import { basename } from "node:path";
-function radarLocalPane(env) {
-  const pane = env.TMUX_PANE?.trim();
-  return pane && /^%\d+$/.test(pane) ? pane : void 0;
-}
-function tmuxServerName(env) {
-  const socket = env.TMUX?.trim().split(",")[0];
-  return socket ? basename(socket) || void 0 : void 0;
-}
-function qualifiedOwnPane(env, backend, instance) {
-  if (backend !== "tmux")
-    return {
-      absent: `the daemon serves the ${backend} backend, and Herdsman drives only tmux`
-    };
-  if (instance === void 0 || instance === "")
-    return {
-      pending: "the daemon did not name the tmux server it addresses"
-    };
-  const server = tmuxServerName(env);
-  if (server === void 0)
-    return {
-      absent: "this process's own tmux client names no server, so it is not in the pane it would publish"
-    };
-  if (server !== instance)
-    return {
-      absent: `this process is attached to tmux server ${server}, not to ${instance}`
-    };
-  const pane = radarLocalPane(env);
-  if (pane === void 0)
-    return {
-      absent: "this process's own environment names no tmux pane of that server"
-    };
-  return { pane: `tmux:${instance}:${pane}` };
-}
-function observedContainment(inventory, paneId) {
-  const rows = inventory.panes.filter((pane) => pane.pane_id === paneId);
-  if (rows.length === 0) return void 0;
-  if (rows.length > 1) return { ambiguous: `topology reports pane ${paneId} twice` };
-  const row = rows[0];
-  const tab = inventory.tabs.find((candidate) => candidate.tab_id === row.tab_id);
-  if (tab !== void 0 && tab.workspace_id !== row.workspace_id)
-    return {
-      ambiguous: `pane ${paneId} is reported in ${row.workspace_id}, but its tab belongs to ${tab.workspace_id}`
-    };
-  return { pane: row };
-}
-async function resolveRadarProcessLocation(client, env = process.env) {
-  let ready;
-  try {
-    ready = await client.ping();
-  } catch {
-    return { state: "pending", reason: "the daemon did not answer this process" };
-  }
-  if (ready.ok === false)
-    return {
-      state: "pending",
-      reason: `the daemon did not answer this process (${ready.code})`
-    };
-  const backend = ready.value.backend;
-  if (backend === void 0 || backend === "none")
-    return { state: "absent", reason: "the daemon serves no physical backend" };
-  const instance = ready.value.instance ?? void 0;
-  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;
-  if (paneId === env.PI_HERDSMAN_PARENT_PANE_ID?.trim())
-    return {
-      state: "absent",
-      reason: "this process is in the pane its launch was created beside, not in a pane of its own"
-    };
-  let inventory;
-  try {
-    inventory = await client.observe();
-  } catch {
-    return {
-      state: "pending",
-      reason: "the daemon's topology could not be read for this process's pane"
-    };
-  }
-  if (inventory.ok === false)
-    return {
-      state: "pending",
-      reason: `the daemon's topology could not be read (${inventory.code})`
-    };
-  const containment = observedContainment(inventory.value, paneId);
-  if (containment === void 0)
-    return {
-      state: "pending",
-      reason: `the daemon's topology does not report pane ${paneId} yet`
-    };
-  if ("ambiguous" in containment)
-    return { state: "pending", reason: containment.ambiguous };
-  const row = containment.pane;
-  return {
-    state: "resolved",
-    location: {
-      backend,
-      ...instance !== void 0 ? { instance } : {},
-      workspace: row.workspace_id,
-      tab: row.tab_id,
-      pane: paneId
-    }
-  };
-}
-
 // extension/radar-runtime.ts
 var RADAR_RUNTIME_REQUEST = "pi-radar/runtime-request";
-var RADAR_RUNTIME_VERSION = 2;
+var RADAR_RUNTIME_VERSION = 3;
 function lazyRadarRuntime(start) {
   let pending;
   return {
@@ -2588,6 +2856,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);