pi-radar 0.5.0 → 0.5.1

package/README.md

@@ -19,7 +19,7 @@ The baseline reports session presence through one flat request. A fresh `session
 
 ## Daemon contract
 
-The client speaks protocol 2 and requires wire revision 3 or newer for its existing lifecycle operations. Revision 3 made lifecycle `subject_id` a stable logical identity and exposed the exact current `execution_id` and `u32` generation separately. Handoff methods additionally require the independently negotiated `communication.handoff.v1` contract introduced at wire revision 4; its timestamps remain exactly representable as JSON numbers. Clients that control managed executions must not target the legacy per-execution ID semantics. It reads `revision` and the public `contracts` list from `daemon.ping`, preserves unfamiliar contract names, and preflights only contracts needed for a multi-step or versioned operation. Backend `mux.*` primitives are private to the daemon; direct mux methods are dispatched and return the daemon's backend refusal when unavailable.
+The client speaks protocol 2 and requires wire revision 4. Revision 3 made lifecycle `subject_id` a stable logical identity and exposed the exact current `execution_id` and `u32` generation separately; revision 4 added Pi presence (`agent.presence`/`agent.release`), which is how a session acquires its subject, so a revision-3 daemon would accept the handshake and then leave every Pi session unmanaged. Handoff methods additionally require the independently negotiated `communication.handoff.v1` contract; its timestamps remain exactly representable as JSON numbers. Clients that control managed executions must not target the legacy per-execution ID semantics. It reads `revision` and the public `contracts` list from `daemon.ping`, preserves unfamiliar contract names, and preflights only contracts needed for a multi-step or versioned operation. Backend `mux.*` primitives are private to the daemon; direct mux methods are dispatched and return the daemon's backend refusal when unavailable.
 
 The client uses `registry.v1` for registry operations and additionally requires `registry.facts.v1` for the facts channel and assignment extensions. Managed children require `spawn.v1`, child-pane removal requires `spawn.close.v1`, event reads require `events.v1`, and handoff operations require `communication.handoff.v1`. The expected wire examples are maintained in this repository's `docs/control-plane.fixture.jsonl` and `docs/agent-registration.fixture.jsonl` and are exercised by the package tests.
 
@@ -31,10 +31,38 @@ The handoff API stores immutable bounded content separately from the recipient r
 
 ## 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/`. Serialize and deserialize schemas are separate because Serde defaults, null handling and omission differ by direction. The SDK's ping, 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.
+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.
+
+The public process identifier is `registration_id` — a clean rename from the pre-0.4 `agent_id` with no alias, because a mixed fleet would otherwise read a missing field as an absent identity. Durable agent identity is `subject_id`, which survives process replacement; a Pi session's subject is granted by `agent.presence` and released by `agent.release`. Breaking wire changes bump this package's minor version, so a consumer must move its pin and restart the daemon in one step.
 
 From the repository checkout, run `npm run generate:contracts` in this directory to regenerate schemas and TypeScript declarations. `npm test` checks the generated artifacts are current, typechecks the public SDK aliases, validates canonical wire fixtures and integer bounds against the schemas, and runs the package tests. Generation uses the locked Schemars crate plus pinned `json-schema-to-typescript` and TypeScript development dependencies; it adds no runtime package dependency.
 
 Lifecycle execution generations are bounded to `u32` and remain exactly representable as JavaScript numbers. The initial schema set leaves operation sequences and event cursors unchanged; their long-horizon representation remains a separate wire-compatibility decision.
 
 Run `npm pack` to build the bundled runtime entrypoints before creating the tarball.
+
+## Releasing
+
+Publishing is one tag push and it runs in CI; no npm token is stored anywhere.
+`.github/workflows/publish-pi-radar.yml` publishes on a `pi-radar-vX.Y.Z` tag
+push, authenticating with npm trusted publishing (OIDC) and emitting provenance.
+
+One-time setup, on npmjs.com under the `pi-radar` package's settings: add a
+trusted publisher of type GitHub Actions naming owner `Shrub24`, repository
+`agent-radar`, workflow filename `publish-pi-radar.yml`, and no environment.
+The workflow sets no `environment:`, so a non-empty value here stops it from
+publishing; the same is true of an `NPM_TOKEN` secret, which trusted publishing
+does not use.
+
+To release:
+
+1. Bump `version` in `package.json` and `package-lock.json` on `main` and push.
+   Semantics: a breaking wire change bumps the minor, additive changes the patch.
+2. Tag that commit and push the tag: `git tag pi-radar-vX.Y.Z && git push origin pi-radar-vX.Y.Z`.
+
+The workflow refuses to publish unless the tag's version matches
+`package.json`, the tagged commit is on `main`, and that version is not already
+on npm; then it installs from the lockfile, runs `npm test`, preflights the
+tarball with `npm pack --dry-run` (which builds `dist/` through `prepack`), and
+publishes. A failed run is re-runnable by fixing the cause and re-pushing the
+tag; an already-published version fails by design rather than republishing.

package/dist/extension/baseline.js

@@ -8,7 +8,7 @@ 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 = 3;
+var RADAR_MINIMUM_REVISION = 4;
 var RADAR_REGISTRY_CONTRACT = "registry.v1";
 var RADAR_REGISTRY_FACTS_CONTRACT = "registry.facts.v1";
 var RADAR_SPAWN_CONTRACT = "spawn.v1";

package/dist/extension/radar-client.js

@@ -4,7 +4,7 @@ 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 = 3;
+var RADAR_MINIMUM_REVISION = 4;
 var RADAR_REGISTRY_CONTRACT = "registry.v1";
 var RADAR_REGISTRY_FACTS_CONTRACT = "registry.facts.v1";
 var RADAR_SPAWN_CONTRACT = "spawn.v1";

package/dist/index.js

@@ -39,7 +39,7 @@ 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 = 3;
+var RADAR_MINIMUM_REVISION = 4;
 var RADAR_REGISTRY_CONTRACT = "registry.v1";
 var RADAR_REGISTRY_FACTS_CONTRACT = "registry.facts.v1";
 var RADAR_SPAWN_CONTRACT = "spawn.v1";

package/extension/radar-client.ts

@@ -30,8 +30,13 @@ import type {
  * served under the old name.
  */
 export const RADAR_PROTOCOL_VERSION = 2;
-/** The minimum daemon wire revision this client understands. */
-export const RADAR_MINIMUM_REVISION = 3;
+/**
+ * The minimum daemon wire revision this client understands. Revision 4 is where
+ * Pi presence and exact session release arrived; a revision-3 daemon would pass
+ * this handshake and then refuse every presence report, leaving a Pi session
+ * silently unmanaged instead of telling the operator to restart the daemon.
+ */
+export const RADAR_MINIMUM_REVISION = 4;
 /** Public daemon contracts this client may preflight. */
 export const RADAR_REGISTRY_CONTRACT = "registry.v1";
 export const RADAR_REGISTRY_FACTS_CONTRACT = "registry.facts.v1";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-radar",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "type": "module",
   "description": "Radar daemon client, communication, publication, execution, location, launch and inspection surface for Pi extensions.",
   "license": "Apache-2.0",

package/dist/extension/radar-session-marker.js

@@ -1,82 +0,0 @@
-// extension/radar-session-marker.ts
-var RADAR_LAUNCH_MARKER_TYPE = "pi-radar.launch-identity";
-var RADAR_LAUNCH_MARKER_VERSION = 1;
-var RADAR_MAX_EXECUTION_GENERATION = 4294967295;
-var RADAR_MANAGED_SUBJECT_ENV = "PI_RADAR_MANAGED_SUBJECT_ID";
-var RADAR_MANAGED_LAUNCH_ENV = "PI_RADAR_MANAGED_LAUNCH_ID";
-var RADAR_MANAGED_GENERATION_ENV = "PI_RADAR_MANAGED_EXECUTION_GENERATION";
-var UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu;
-function decodeRadarLaunchMarker(value) {
-  if (typeof value !== "object" || value === null || Array.isArray(value)) return void 0;
-  const record = value;
-  if (Object.keys(record).sort().join(",") !== "execution_generation,launch_id,subject_id,version") {
-    return void 0;
-  }
-  if (record.version !== RADAR_LAUNCH_MARKER_VERSION || typeof record.subject_id !== "string" || !UUID.test(record.subject_id) || typeof record.launch_id !== "string" || !UUID.test(record.launch_id) || !Number.isSafeInteger(record.execution_generation) || record.execution_generation < 1 || record.execution_generation > RADAR_MAX_EXECUTION_GENERATION) {
-    return void 0;
-  }
-  return {
-    version: RADAR_LAUNCH_MARKER_VERSION,
-    subject_id: record.subject_id,
-    launch_id: record.launch_id,
-    execution_generation: record.execution_generation
-  };
-}
-function appendRadarLaunchMarker(appendEntry, marker) {
-  const validated = decodeRadarLaunchMarker(marker);
-  if (!validated) throw new Error("invalid Radar launch identity marker");
-  appendEntry(RADAR_LAUNCH_MARKER_TYPE, validated);
-}
-function latestRadarLaunchMarker(branch) {
-  let latest;
-  for (const entry of branch) {
-    if (entry.type === "custom" && entry.customType === RADAR_LAUNCH_MARKER_TYPE) {
-      latest = entry;
-    }
-  }
-  if (!latest) return { status: "absent" };
-  const marker = decodeRadarLaunchMarker(latest.data);
-  return marker ? { status: "valid", marker } : { status: "invalid" };
-}
-function radarLaunchMarkerFromEnvironment(env = process.env) {
-  const rawGeneration = env[RADAR_MANAGED_GENERATION_ENV];
-  if (env[RADAR_MANAGED_SUBJECT_ENV] === void 0 || env[RADAR_MANAGED_LAUNCH_ENV] === void 0 || rawGeneration === void 0 || !/^[1-9][0-9]*$/.test(rawGeneration)) {
-    return void 0;
-  }
-  return decodeRadarLaunchMarker({
-    version: RADAR_LAUNCH_MARKER_VERSION,
-    subject_id: env[RADAR_MANAGED_SUBJECT_ENV],
-    launch_id: env[RADAR_MANAGED_LAUNCH_ENV],
-    execution_generation: Number(rawGeneration)
-  });
-}
-function activeRadarLaunchMarker(host) {
-  if (!host.sessionManager) return { status: "absent" };
-  return latestRadarLaunchMarker(host.sessionManager.getBranch());
-}
-function persistRadarLaunchMarker(host, env = process.env) {
-  const marker = radarLaunchMarkerFromEnvironment(env);
-  if (!marker) return "absent";
-  if (!host.appendEntry || !host.sessionManager) return "unsupported";
-  const current = latestRadarLaunchMarker(host.sessionManager.getBranch());
-  if (current.status === "valid" && sameMarker(current.marker, marker)) return "unchanged";
-  appendRadarLaunchMarker(host.appendEntry, marker);
-  return "written";
-}
-function sameMarker(a, b) {
-  return a.version === b.version && a.subject_id === b.subject_id && a.launch_id === b.launch_id && a.execution_generation === b.execution_generation;
-}
-export {
-  RADAR_LAUNCH_MARKER_TYPE,
-  RADAR_LAUNCH_MARKER_VERSION,
-  RADAR_MANAGED_GENERATION_ENV,
-  RADAR_MANAGED_LAUNCH_ENV,
-  RADAR_MANAGED_SUBJECT_ENV,
-  RADAR_MAX_EXECUTION_GENERATION,
-  activeRadarLaunchMarker,
-  appendRadarLaunchMarker,
-  decodeRadarLaunchMarker,
-  latestRadarLaunchMarker,
-  persistRadarLaunchMarker,
-  radarLaunchMarkerFromEnvironment
-};