pi-radar 0.2.0 → 0.4.0

package/dist/extension/radar-client.js

@@ -11,6 +11,7 @@ var RADAR_SPAWN_CONTRACT = "spawn.v1";
 var RADAR_SPAWN_CLOSE_CONTRACT = "spawn.close.v1";
 var RADAR_SPAWN_LAUNCH_CONTEXT_CONTRACT = "spawn.launch_context.v1";
 var RADAR_EVENTS_CONTRACT = "events.v1";
+var RADAR_COMMUNICATION_CONTRACT = "communication.handoff.v1";
 var RADAR_REQUESTER = "pi-radar";
 var RADAR_MAX_LINE_BYTES = 1024 * 1024;
 var RADAR_CALL_TIMEOUT_MS = 2e3;
@@ -108,6 +109,25 @@ function recordAt(value, field) {
 function isUuid(value) {
   return typeof value === "string" && UUID.test(value);
 }
+function decodePresenceAnswer(value) {
+  const registrationId = recordAt(value, "registration_id");
+  const claimId = recordAt(value, "claim_id");
+  const standing = recordAt(value, "standing");
+  const subjectId = recordAt(value, "subject_id");
+  if (!isUuid(registrationId) || !isUuid(claimId) || !["pending", "granted", "duplicate", "released"].includes(String(standing)) || subjectId !== void 0 && !isUuid(subjectId) || standing === "granted" && !isUuid(subjectId))
+    return protocol("presence reply carries no valid claim standing");
+  return { ok: true, value };
+}
+function managementAt(value) {
+  const field = recordAt(value, "management");
+  const state = stringAt(field, "state");
+  if (state === "managed") {
+    const subjectId = stringAt(field, "subject_id");
+    return subjectId === void 0 ? void 0 : { state, subject_id: subjectId };
+  }
+  if (state === "duplicate" || state === "pending" || state === "unmanaged") return { state };
+  return void 0;
+}
 function stringAt(value, field) {
   if (typeof value !== "object" || value === null) return void 0;
   const found = value[field];
@@ -118,6 +138,28 @@ function numberAt(value, field) {
   const found = value[field];
   return typeof found === "number" && Number.isFinite(found) ? found : void 0;
 }
+function handoffAt(value) {
+  const version = numberAt(value, "version");
+  const id = stringAt(value, "id");
+  const sender = recordAt(value, "sender");
+  const senderGeneration = numberAt(sender, "execution_generation");
+  const target = stringAt(value, "recipient_subject_id");
+  const summary = stringAt(value, "summary");
+  const content = stringAt(value, "content");
+  const published = numberAt(value, "published_at_unix_ms");
+  const correlation = typeof value === "object" && value !== null ? value.correlation_id : void 0;
+  if (version !== 1 || !isUuid(id) || !isUuid(stringAt(sender, "registration_id")) || !isUuid(stringAt(sender, "session_id")) || !isUuid(stringAt(sender, "subject_id")) || !isUuid(stringAt(sender, "execution_id")) || !Number.isSafeInteger(senderGeneration) || (senderGeneration ?? 0) < 1 || !isUuid(target) || summary === void 0 || content === void 0 || published === void 0 || !Number.isSafeInteger(published) || published < 0 || correlation !== void 0 && correlation !== null && (typeof correlation !== "string" || correlation.length === 0 || Buffer.byteLength(correlation, "utf8") > 256 || new RegExp("\\p{Cc}", "u").test(correlation))) return void 0;
+  return value;
+}
+function handoffReceiptAt(value) {
+  const version = numberAt(value, "version");
+  const handoffId = stringAt(value, "handoff_id");
+  const recipient = recordAt(value, "recipient");
+  const generation = numberAt(recipient, "execution_generation");
+  const received = numberAt(value, "received_at_unix_ms");
+  if (version !== 1 || !isUuid(handoffId) || !isUuid(stringAt(recipient, "registration_id")) || !isUuid(stringAt(recipient, "session_id")) || !isUuid(stringAt(recipient, "subject_id")) || !isUuid(stringAt(recipient, "execution_id")) || !Number.isSafeInteger(generation) || (generation ?? 0) < 1 || received === void 0 || !Number.isSafeInteger(received) || received < 0) return void 0;
+  return value;
+}
 function writerBinding(value) {
   const handle = stringAt(value, "handle");
   const source = stringAt(value, "source");
@@ -227,7 +269,8 @@ var RADAR_SPAWN_TOKEN_ENV = "PI_RADAR_SPAWN_TOKEN";
 var RADAR_MANAGED_IDENTITY_ENV = /* @__PURE__ */ new Set([
   "PI_RADAR_MANAGED_SUBJECT_ID",
   "PI_RADAR_MANAGED_LAUNCH_ID",
-  "PI_RADAR_MANAGED_EXECUTION_GENERATION"
+  "PI_RADAR_MANAGED_EXECUTION_GENERATION",
+  "PI_RADAR_MANAGED_PARENT_SUBJECT_ID"
 ]);
 function unresolvedSpawn(requestId, detail) {
   return {
@@ -272,7 +315,7 @@ function spawnEdge(value) {
   const bound = recordAt(value, "bound");
   const source = stringAt(bound, "source");
   const incarnation = stringAt(bound, "incarnation");
-  const agentId = stringAt(bound, "agent_id");
+  const agentId = stringAt(bound, "registration_id");
   const exit = exitAt(recordAt(value, "exit_observation"));
   return {
     ok: true,
@@ -286,7 +329,7 @@ function spawnEdge(value) {
         bound: {
           source,
           incarnation,
-          ...isUuid(agentId) ? { agent_id: agentId } : {}
+          ...isUuid(agentId) ? { registration_id: agentId } : {}
         }
       } : {},
       ...exit !== void 0 ? { exit_observation: exit } : {}
@@ -684,6 +727,22 @@ function createRadarClient(options = {}) {
   return {
     socketPath,
     ping,
+    async presence(request) {
+      return withRegistry(async () => {
+        const answer = await call("agent.presence", { ...request });
+        if (!answer.ok) return answer;
+        return decodePresenceAnswer(answer.value);
+      });
+    },
+    async releasePresence(request) {
+      return withRegistry(async () => {
+        const answer = await call("agent.release", { ...request });
+        if (!answer.ok) return answer;
+        const decoded = decodePresenceAnswer(answer.value);
+        if (!decoded.ok) return decoded;
+        return decoded.value.standing === "released" ? decoded : protocol("release reply did not confirm the claim release");
+      });
+    },
     async register(registration) {
       return withRegistry(async () => {
         const answer = await call("agent.register", {
@@ -699,15 +758,15 @@ function createRadarClient(options = {}) {
         });
         if (answer.ok === false) return answer;
         const record = answer.value.registration;
-        const agentId = stringAt(record, "agent_id");
-        if (!isUuid(agentId)) return protocol("registration reply carries no agent_id");
-        return { ok: true, value: { agent_id: agentId } };
+        const agentId = stringAt(record, "registration_id");
+        if (!isUuid(agentId)) return protocol("registration reply carries no registration_id");
+        return { ok: true, value: { registration_id: agentId } };
       });
     },
     async acquire(request) {
       return withRegistryChannel(request.channel, async () => {
         const answer = await call("agent.acquire", {
-          agent_id: request.agent_id,
+          registration_id: request.registration_id,
           channel: request.channel,
           publisher: request.publisher,
           ...request.replace !== void 0 ? { replace: request.replace } : {}
@@ -736,7 +795,7 @@ function createRadarClient(options = {}) {
       }
       return withRegistryChannel(request.channel, async () => {
         const answer = await call("agent.publish", {
-          agent_id: request.agent_id,
+          registration_id: request.registration_id,
           channel: request.channel,
           writer_handle: request.writer_handle,
           sequence: request.sequence,
@@ -755,7 +814,7 @@ function createRadarClient(options = {}) {
     async context(request) {
       return withRegistry(async () => {
         const answer = await call("agent.context", {
-          agent_id: request.agent_id,
+          registration_id: request.registration_id,
           publisher: request.publisher,
           ...request.writer_handle !== void 0 ? { writer_handle: request.writer_handle } : {},
           ...request.replace !== void 0 ? { replace: request.replace } : {},
@@ -771,9 +830,14 @@ function createRadarClient(options = {}) {
         if (writer === void 0)
           return protocol("context reply carries no writer binding");
         const warning = stringAt(answer.value, "warning");
+        const management = managementAt(answer.value);
         return {
           ok: true,
-          value: { writer, ...warning !== void 0 ? { warning } : {} }
+          value: {
+            writer,
+            ...warning !== void 0 ? { warning } : {},
+            ...management !== void 0 ? { management } : {}
+          }
         };
       });
     },
@@ -850,7 +914,7 @@ function createRadarClient(options = {}) {
           message: "agent.get requires a canonical agent UUID"
         };
       return withRegistry(async () => {
-        const answer = await call("agent.get", { agent_id: agentId });
+        const answer = await call("agent.get", { registration_id: agentId });
         if (answer.ok === false) return answer;
         return agentProcessAt(recordAt(answer.value, "agent"));
       });
@@ -901,6 +965,56 @@ function createRadarClient(options = {}) {
         return protocol("spawn.close reply carries no close outcome");
       });
     },
+    async communicationPublish(request) {
+      return withContract(RADAR_COMMUNICATION_CONTRACT, async () => {
+        const answer = await call("communication.publish", {
+          sender_registration_id: request.sender_registration_id,
+          recipient_subject_id: request.recipient_subject_id,
+          ...request.correlation_id !== void 0 ? { correlation_id: request.correlation_id } : {},
+          summary: request.summary,
+          content: request.content
+        }, request.request_id);
+        if (answer.ok === false) return answer;
+        const handoff = handoffAt(recordAt(answer.value, "handoff"));
+        const created = recordAt(answer.value, "created");
+        if (handoff === void 0 || typeof created !== "boolean")
+          return protocol("communication.publish reply carries no handoff");
+        return { ok: true, value: { handoff, created } };
+      });
+    },
+    async communicationInbox(request) {
+      return withContract(RADAR_COMMUNICATION_CONTRACT, async () => {
+        const answer = await call("communication.inbox", request);
+        if (answer.ok === false) return answer;
+        const handoffIds = recordAt(answer.value, "handoff_ids");
+        if (!Array.isArray(handoffIds) || handoffIds.some((id) => !isUuid(id)))
+          return protocol("communication.inbox reply carries malformed handoff IDs");
+        return { ok: true, value: answer.value };
+      });
+    },
+    async communicationGet(request) {
+      return withContract(RADAR_COMMUNICATION_CONTRACT, async () => {
+        const answer = await call("communication.get", request);
+        if (answer.ok === false) return answer;
+        const handoff = handoffAt(recordAt(answer.value, "handoff"));
+        const receiptValue = recordAt(answer.value, "receipt");
+        const receipt = receiptValue === null ? null : handoffReceiptAt(receiptValue);
+        if (handoff === void 0 || receiptValue !== null && receipt === void 0)
+          return protocol("communication.get reply carries malformed content or receipt");
+        return { ok: true, value: { handoff, receipt: receipt ?? null } };
+      });
+    },
+    async communicationAck(request) {
+      return withContract(RADAR_COMMUNICATION_CONTRACT, async () => {
+        const answer = await call("communication.ack", request);
+        if (answer.ok === false) return answer;
+        const receipt = handoffReceiptAt(recordAt(answer.value, "receipt"));
+        const created = recordAt(answer.value, "created");
+        if (receipt === void 0 || typeof created !== "boolean")
+          return protocol("communication.ack reply carries no receipt");
+        return { ok: true, value: { receipt, created } };
+      });
+    },
     async events(request) {
       if (!Number.isSafeInteger(request.after) || request.after < 0 || !Number.isSafeInteger(request.wait_ms) || request.wait_ms < 0 || request.wait_ms > RADAR_EVENT_WAIT_MS)
         return {
@@ -1122,6 +1236,7 @@ function boundedRadarSnapshot(snapshot) {
 }
 export {
   RADAR_CALL_TIMEOUT_MS,
+  RADAR_COMMUNICATION_CONTRACT,
   RADAR_EVENTS_CONTRACT,
   RADAR_EVENT_RETRY_MS,
   RADAR_MAX_AWAITED,

package/dist/extension/radar-communication.js

@@ -0,0 +1,39 @@
+// extension/radar-communication.ts
+function createRadarHandoffPort(client, publication, parentSubjectId = () => process.env.PI_RADAR_MANAGED_PARENT_SUBJECT_ID) {
+  async function agentId() {
+    const subject = await publication.subject();
+    return subject === void 0 ? { ok: false, code: "absent", message: "this process has no current Radar registration" } : { ok: true, value: subject.registration_id };
+  }
+  return {
+    async publish(request) {
+      const identity = await agentId();
+      if (identity.ok === false) return identity;
+      const parent = parentSubjectId();
+      if (parent === void 0)
+        return { ok: false, code: "absent", message: "this managed execution has no Radar parent subject" };
+      return client.communicationPublish({
+        ...request,
+        sender_registration_id: identity.value,
+        recipient_subject_id: parent
+      });
+    },
+    async inbox() {
+      const identity = await agentId();
+      if (identity.ok === false) return identity;
+      return client.communicationInbox({ registration_id: identity.value });
+    },
+    async get(handoff_id) {
+      const identity = await agentId();
+      if (identity.ok === false) return identity;
+      return client.communicationGet({ registration_id: identity.value, handoff_id });
+    },
+    async ack(handoff_id) {
+      const identity = await agentId();
+      if (identity.ok === false) return identity;
+      return client.communicationAck({ registration_id: identity.value, handoff_id });
+    }
+  };
+}
+export {
+  createRadarHandoffPort
+};