pi-radar 0.9.0 → 0.11.0

package/dist/extension/radar-children.js

@@ -1,237 +1,127 @@
-// 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-children.ts
+import { randomUUID } from "node:crypto";
+
+// extension/radar-launch.ts
+import { setTimeout as delay } from "node:timers/promises";
 
 // extension/radar-client.ts
 var RADAR_MAX_LINE_BYTES = 1024 * 1024;
+var UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function isUuid(value) {
+  return typeof value === "string" && UUID.test(value);
+}
 
 // extension/radar-launch.ts
-function unknownChild(reason) {
-  return { kind: "unknown", diagnostic: trajectory(reason) };
+function refusedLaunch(message) {
+  return { kind: "failed", message };
 }
-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}`
-    );
+function unresolvedLaunch(requestId, message) {
   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
-    }
+    kind: "unresolved",
+    request_id: requestId,
+    message: `spawn ${requestId} is unresolved (${message})`
   };
 }
-
-// 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"
-          }
-        });
+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;
       }
-      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);
+      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
+function createRadarChildren(client, publication) {
   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;
+    async list(selection) {
+      const children = [];
+      let after;
+      do {
+        const page = await client.subjectChildren({ selection, after, limit: 100 });
+        if (!page.ok) return page;
+        children.push(...page.value.subjects);
+        if (page.value.next === after)
+          return { ok: false, code: "protocol", message: "child page did not advance" };
+        after = page.value.next ?? void 0;
+      } while (after !== void 0);
+      return { ok: true, value: children };
     },
-    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 restart(subject, program, options) {
+      const parent = await publication.subject();
+      if (parent?.subject_id === void 0)
+        return { kind: "failed", message: "this process has no granted subject" };
+      const request_id = randomUUID();
+      const requested = await client.restart({ request_id, parent: parent.registration_id, subject_id: subject, ...program });
+      if (!requested.ok) 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;
+      return { kind: "ready", value: { request_id: requested.value.launch_request_id, subject_id: bound.subject_id, pane_id: bound.pane_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 } : {}
-      });
+    assignment: (subject, owner) => publication.assignment(subject, owner),
+    retire: (subject) => publication.retireAssignment(subject),
+    async observe(subject) {
+      const read = await client.childGet(subject);
+      if (!read.ok) return { kind: "unknown", diagnostic: `${read.code}: ${read.message}` };
+      if (read.value.state === "live") return { kind: "live", subject: read.value };
+      if (read.value.state === "detached") return { kind: "gone", subject: read.value };
+      return { kind: "unknown", diagnostic: `child attachment is ${read.value.state}` };
+    },
+    async inspect(subject) {
+      const read = await client.childInspect(subject);
+      if (!read.ok) throw new Error(`Child inspection unavailable (${read.code}: ${read.message})`);
+      return read.value;
     }
   };
 }

package/dist/extension/radar-client.js

@@ -4,11 +4,10 @@ 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 = 7;
+var RADAR_MINIMUM_REVISION = 9;
 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";
@@ -318,6 +317,9 @@ function spawnEdge(value) {
   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: {
@@ -334,7 +336,9 @@ function spawnEdge(value) {
           ...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 } } : {}
     }
   };
 }
@@ -344,6 +348,14 @@ var PROCESS_VERDICTS = [
   "mismatched",
   "unavailable"
 ];
+function subjectAt(value) {
+  const subjectId = recordAt(value, "subject_id");
+  const session = recordAt(value, "session_id");
+  const state = recordAt(value, "state");
+  if (!isUuid(subjectId) || session != null && !isUuid(session) || !["starting", "live", "detached", "unknown"].includes(String(state)))
+    return protocol("subject read carries no valid identity or attachment state");
+  return { ok: true, value };
+}
 function agentProcessAt(agent) {
   const process2 = recordAt(agent, "process");
   const claimed = recordAt(process2, "claimed");
@@ -736,7 +748,9 @@ function createRadarClient(options = {}) {
       return withRegistry(async () => {
         const answer = await call("agent.presence", { ...request });
         if (!answer.ok) return answer;
-        return decodePresenceAnswer(answer.value);
+        const decoded = decodePresenceAnswer(answer.value);
+        if (decoded.ok) processRegistrationId = decoded.value.registration_id;
+        return decoded;
       });
     },
     async releasePresence(request) {
@@ -771,9 +785,13 @@ function createRadarClient(options = {}) {
     },
     async acquire(request) {
       return withRegistryChannel(request.channel, async () => {
-        const answer = await call("agent.acquire", {
-          registration_id: request.registration_id,
-          channel: request.channel,
+        const assignment = request.channel === "assignment";
+        if (assignment && processRegistrationId === void 0)
+          return { ok: false, code: "refused", message: "assignment requires a granted parent" };
+        if (assignment && request.subject_id === void 0)
+          return { ok: false, code: "bad_params", message: "an assignment names a child subject" };
+        const answer = await call(assignment ? "subject.assignment.acquire" : "agent.acquire", {
+          ...assignment ? { registration_id: processRegistrationId, subject_id: request.subject_id } : { registration_id: request.registration_id, channel: request.channel },
           publisher: request.publisher,
           ...request.replace !== void 0 ? { replace: request.replace } : {}
         });
@@ -800,15 +818,19 @@ function createRadarClient(options = {}) {
         }
       }
       return withRegistryChannel(request.channel, async () => {
-        const answer = await call("agent.publish", {
-          registration_id: request.registration_id,
-          channel: request.channel,
+        const update = {
           writer_handle: request.writer_handle,
           sequence: request.sequence,
           ...request.lease_ms !== void 0 ? { lease_ms: request.lease_ms } : {},
           ...request.observed_at !== void 0 ? { observed_at: request.observed_at } : {},
           snapshot
-        });
+        };
+        const assignment = request.channel === "assignment";
+        if (assignment && processRegistrationId === void 0)
+          return { ok: false, code: "refused", message: "assignment requires a granted parent" };
+        if (assignment && request.subject_id === void 0)
+          return { ok: false, code: "bad_params", message: "an assignment names a child subject" };
+        const answer = await call(assignment ? "subject.assignment.publish" : "agent.publish", assignment ? { registration_id: processRegistrationId, subject_id: request.subject_id, update } : { registration_id: request.registration_id, channel: request.channel, ...update });
         if (answer.ok === false) return answer;
         const channel = answer.value.channel;
         const writer = channel?.writer;
@@ -849,7 +871,15 @@ function createRadarClient(options = {}) {
     },
     async retire(request) {
       return withRegistryChannel(request.channel, async () => {
-        const answer = await call("agent.retire", request);
+        const assignment = request.channel === "assignment";
+        if (assignment && processRegistrationId === void 0)
+          return { ok: false, code: "refused", message: "assignment requires a granted parent" };
+        if (assignment && request.subject_id === void 0)
+          return { ok: false, code: "bad_params", message: "an assignment names a child subject" };
+        const answer = await call(assignment ? "subject.assignment.retire" : "agent.retire", {
+          ...assignment ? { registration_id: processRegistrationId, subject_id: request.subject_id } : { registration_id: request.registration_id, channel: request.channel },
+          writer_handle: request.writer_handle
+        });
         return answer.ok === true ? { ok: true, value: void 0 } : answer;
       });
     },
@@ -924,14 +954,73 @@ function createRadarClient(options = {}) {
           request.request_id
         );
         if (answer.ok === false) return answer;
-        return focusOutcome(recordAt(answer.value, "request"), request.request_id);
+        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 subjectChildren(request = {}) {
+      const registrationId = processRegistrationId;
+      if (registrationId === void 0)
+        return { ok: false, code: "refused", message: "this process has no Radar registration" };
+      return withRegistry(async () => {
+        const params = { ...request, registration_id: registrationId };
+        const answer = await call("subject.children", { ...params });
+        if (!answer.ok) return answer;
+        const subjects = recordAt(answer.value, "subjects");
+        const next = recordAt(answer.value, "next");
+        if (!Array.isArray(subjects) || next != null && !isUuid(next))
+          return protocol("subject.children reply carries no valid page");
+        for (const subject of subjects) {
+          const decoded = subjectAt(subject);
+          if (!decoded.ok) return decoded;
+        }
+        return { ok: true, value: answer.value };
+      });
+    },
+    async childGet(subject_id) {
+      const registrationId = processRegistrationId;
+      if (registrationId === void 0)
+        return { ok: false, code: "refused", message: "this process has no Radar registration" };
+      if (!isUuid(subject_id))
+        return { ok: false, code: "bad_params", message: "child requires a subject UUID" };
+      return withRegistry(async () => {
+        const params = { registration_id: registrationId, subject_id };
+        const answer = await call("subject.child.get", { ...params });
+        return answer.ok ? subjectAt(recordAt(answer.value, "subject")) : answer;
+      });
+    },
+    async childInspect(subject_id) {
+      const registration_id = processRegistrationId;
+      if (registration_id === void 0)
+        return { ok: false, code: "refused", message: "this process has no Radar registration" };
+      return withRegistry(async () => {
+        const answer = await call("subject.child.inspect", { registration_id, subject_id });
+        if (!answer.ok) return answer;
+        const subject = subjectAt(recordAt(answer.value, "subject"));
+        if (!subject.ok) return subject;
+        const output = recordAt(answer.value, "output");
+        const text = stringAt(output, "text");
+        if (text === void 0 || typeof recordAt(output, "truncated") !== "boolean")
+          return protocol("child inspection has no output evidence");
+        const foreground = recordAt(answer.value, "foreground");
+        const activity = subject.value.execution?.snapshot?.snapshot;
+        return { ok: true, value: {
+          capturedAt: Date.now(),
+          recentOutputTruncated: recordAt(output, "truncated"),
+          ...text ? { recentOutput: text } : {},
+          ...foreground ? { foreground } : {},
+          ...activity && "activity" in activity ? { activity: activity.activity } : {}
+        } };
       });
     },
     async spawnList(request) {
       const registrationId = processRegistrationId;
       if (registrationId === void 0)
         return { ok: false, code: "refused", message: "spawn.list requires this client's process registration" };
-      return withContract(RADAR_SPAWN_LIST_CONTRACT, async () => {
+      return withRegistry(async () => {
         const params = {
           registration_id: registrationId,
           ...request.after !== void 0 ? { after: request.after } : {},
@@ -1311,7 +1400,6 @@ export {
   RADAR_SPAWN_CLOSE_CONTRACT,
   RADAR_SPAWN_CONTRACT,
   RADAR_SPAWN_LAUNCH_CONTEXT_CONTRACT,
-  RADAR_SPAWN_LIST_CONTRACT,
   boundedRadarAssignment,
   boundedRadarFacts,
   boundedRadarSnapshot,