pi-radar 0.7.0 → 0.9.0

package/dist/extension/radar-children.js

@@ -0,0 +1,240 @@
+// 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 bounded = utf8Tail(lines.join("\n"), INSPECTION_OUTPUT_BYTES);
+  return Object.freeze({
+    capturedAt: Date.now(),
+    recentOutputTruncated: output.value.truncated || bounded.truncated,
+    ...bounded.text ? { recentOutput: bounded.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-client.ts
+var RADAR_MAX_LINE_BYTES = 1024 * 1024;
+
+// 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 resolve(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 resolve(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 } : {}
+      });
+    }
+  };
+}
+export {
+  createRadarChildren
+};

package/dist/extension/radar-client.js

@@ -4,12 +4,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))
@@ -866,7 +871,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
             },
@@ -894,6 +900,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)
@@ -1265,6 +1298,7 @@ export {
   RADAR_COMMUNICATION_CONTRACT,
   RADAR_EVENTS_CONTRACT,
   RADAR_EVENT_RETRY_MS,
+  RADAR_LIFECYCLE_RESTART_CONTRACT,
   RADAR_MAX_AWAITED,
   RADAR_MAX_BACKGROUND_TASKS,
   RADAR_MAX_LINE_BYTES,

package/dist/extension/radar-launch.js

@@ -141,25 +141,31 @@ async function launchRadarWorker(options) {
   const pollMs = options.pollMs ?? 250;
   const deadline = Date.now() + options.timeoutMs;
   const remaining = () => Math.max(0, deadline - Date.now());
-  const pane = launch.parent.location?.pane;
-  if (!isUuid(launch.parent.registration_id))
+  const parent = await options.publication.subject();
+  if (parent === void 0 || !isUuid(parent.registration_id))
     return refusedLaunch(
-      "the launch has no exact parent registration to spawn under"
+      "this process has no Radar registration, so a worker cannot be spawned under it"
     );
-  if (!isUuid(launch.parent.subject_id))
+  if (parent.subject_id === void 0 || !isUuid(parent.subject_id))
     return refusedLaunch(
-      "the launch has no managed Radar subject for its parent"
+      "this process has no managed Radar subject, so a worker cannot be spawned under it"
     );
+  const pane = parent.location?.pane;
   if (pane === void 0 || pane === "")
     return refusedLaunch(
-      "this process's Radar registration names no pane, so it cannot be a spawn parent"
+      "this process's Radar registration names no pane, so a worker cannot be placed beside it"
+    );
+  if (pane !== launch.pane_id)
+    return refusedLaunch(
+      `this process's Radar registration places it in pane ${pane}, not in the pane this launch would split`
     );
   const spawned = await client.spawn({
     request_id: launch.request_id,
-    parent: launch.parent.registration_id,
+    parent: parent.registration_id,
     parent_session_id: launch.parent_session_id,
     executable: launch.executable,
-    managed: { parent_subject_id: launch.parent.subject_id },
+    managed: { parent_subject_id: parent.subject_id },
+    ...launch.continues !== void 0 ? { continue_subject_id: launch.continues } : {},
     argv: launch.argv,
     ...launch.cwd !== "" ? { cwd: launch.cwd } : {},
     ...Object.keys(launch.env).length > 0 ? { env: launch.env } : {}
@@ -182,16 +188,6 @@ async function launchRadarWorker(options) {
   });
   if (bound.kind !== "bound") return bound;
   const agentId = bound.registration_id;
-  if (launch.onBound !== void 0) {
-    try {
-      launch.onBound({ registration_id: agentId, pane_id: bound.pane_id });
-    } catch (error) {
-      return unresolvedLaunch(
-        launch.request_id,
-        `the daemon's binding of the child ${agentId} could not be recorded (${String(error)})`
-      );
-    }
-  }
   try {
     const state = await options.readers.waitForState(
       launch.mailbox,
@@ -205,19 +201,15 @@ async function launchRadarWorker(options) {
         // the pane the daemon created is what refuses a child that inherited
         // another process's coordinates.
         paneId: radarPaneHandle(bound.pane_id)
-      }) && (launch.observedChildAgent === void 0 || launch.observedChildAgent() === agentId),
+      }),
       { timeoutMs: remaining(), ...signal !== void 0 ? { signal } : {} }
     );
     return {
       kind: "ready",
       value: {
         request_id: launch.request_id,
-        registration_id: agentId,
+        subject_id: bound.subject_id,
         pane_id: bound.pane_id,
-        bound_process: {
-          source: bound.source,
-          incarnation: bound.incarnation
-        },
         state
       }
     };
@@ -267,8 +259,15 @@ async function waitForChild(client, requestId, options) {
             requestId,
             `the daemon bound the child ${agentId} without recording the process it registered as`
           );
+        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,
           registration_id: agentId,
           pane_id: pane,
           source,

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 = 2;
+var RADAR_RUNTIME_VERSION = 3;
 function lazyRadarRuntime(start) {
   let pending;
   return {