@kici-dev/engine 0.1.27 → 0.2.0

package/dist/protocol/messages/heartbeat-health.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Heartbeat-freshness policy for Platform connection and agent health.
+ *
+ * Two distinct policies live here, and their numbers differ on purpose.
+ *
+ * **Rendering policy** — badge freshness, computed from `last_heartbeat_at` on
+ * a DB row, by any instance. Advisory: nothing routes on a badge, so it can
+ * afford a tight bound. Two independent heartbeat domains consult it — Platform
+ * connection health (platform_connections) and agent liveness in the
+ * dashboard's infrastructure tree — so the two badges cannot drift apart.
+ * Browser-safe so the dashboard renders against the same numbers the server
+ * computes with.
+ *
+ * **Teardown policy** — applied by the owning instance to its own live sockets.
+ * Wider than the rendering bounds because the `platform_connections.status`
+ * write it drives gates every `status = 'connected'` reader — among them the
+ * plan-limit connection count, the cross-instance relay lookup, the dashboard
+ * proxy's owning-instance lookup, and the stale-orchestrator detector. Marking
+ * a live socket unhealthy too eagerly removes it from routing while it is still
+ * serving.
+ *
+ * The two policies also cover different lifetimes. An instance that closes a
+ * socket at HEARTBEAT_CLOSE_MS deletes its row in the same step, so the `stale`
+ * (HEARTBEAT_DEGRADED_MS) and `orphaned` (HEARTBEAT_STALE_THRESHOLD_SECONDS)
+ * levels describe rows that delete never ran for — the ones the orphan sweeper
+ * reaps. That is why the sweeper cutoff sits at twice HEARTBEAT_CLOSE_MS: a
+ * clean close always beats the sweep to the row.
+ *
+ * Neither policy has an unclassified case, which is what makes them safe to
+ * keep separate: the rendering policy maps a missing `last_heartbeat_at` to
+ * `orphaned` (worst-case, no heartbeat evidence at all), and the teardown
+ * policy never encounters one because the registry stamps `lastHeartbeatAt` at
+ * registration. Any future attempt to collapse the two must preserve that — an
+ * unknown treated as healthy hides a dead peer, and one treated as unhealthy
+ * sheds a live one.
+ *
+ * Consumers:
+ *  - platform ws/connection-health.ts       — the four-level status computation
+ *  - platform ws/heartbeat.ts               — the teardown policy
+ *  - platform queue/jobs/orphan-sweeper.ts  — periodic DELETE of orphan rows
+ *  - platform ws/registry.ts                — plan-limit count excludes stale rows
+ *  - platform dashboard/routes/admin.ts     — GET /admin/connections filter enum
+ *  - platform dev-ops/developer-ops.ts      — the diagnostics badge + orphan count
+ *  - dashboard utils/diagnostics-helpers.ts — agent heartbeat badge colour
+ */
+import { z } from 'zod';
+/** A heartbeat younger than this is fully healthy. */
+export declare const HEARTBEAT_FRESH_MS = 60000;
+/** Between fresh and this, the peer is degraded but not yet presumed gone. */
+export declare const HEARTBEAT_DEGRADED_MS = 300000;
+/**
+ * A row is considered stale (the owning orchestrator process is no longer
+ * publishing heartbeats) when `last_heartbeat_at` is older than this. Past it,
+ * the connection is orphaned and the sweeper is entitled to delete the row.
+ *
+ * The Platform's same-instance DB eviction on reconnect
+ * (`ws/handler.ts#handleSourceRegistration`) shares this rationale: the DELETE
+ * itself is unconditional on staleness, but the reason it is needed at all is
+ * this same staleness window.
+ */
+export declare const HEARTBEAT_STALE_THRESHOLD_SECONDS = 360;
+/**
+ * Silence after which the owning instance writes
+ * `platform_connections.status = 'unhealthy'`. Wider than HEARTBEAT_FRESH_MS
+ * because that write gates relay routing, not rendering.
+ */
+export declare const HEARTBEAT_UNHEALTHY_MARK_MS = 90000;
+/**
+ * Silence after which the owning instance closes the socket with
+ * WS_CLOSE_HEARTBEAT_TIMEOUT (4004) and drops it from the registry — which
+ * deletes the platform_connections row too. A row outlives its socket only when
+ * that delete never ran; the orphan sweeper reaps those.
+ */
+export declare const HEARTBEAT_CLOSE_MS = 180000;
+/** The four-level connection health vocabulary, worst-last. */
+export declare const connectionHealthStatusSchema: z.ZodEnum<{
+    connected: "connected";
+    orphaned: "orphaned";
+    stale: "stale";
+    unhealthy: "unhealthy";
+}>;
+export type ConnectionHealthStatus = z.infer<typeof connectionHealthStatusSchema>;
+//# sourceMappingURL=heartbeat-health.d.ts.map

package/dist/protocol/messages/heartbeat-health.js

@@ -0,0 +1,87 @@
+import "../../rolldown-runtime-ClRpJifh.js";
+import { z } from "zod";
+//#region src/protocol/messages/heartbeat-health.ts
+/**
+* Heartbeat-freshness policy for Platform connection and agent health.
+*
+* Two distinct policies live here, and their numbers differ on purpose.
+*
+* **Rendering policy** — badge freshness, computed from `last_heartbeat_at` on
+* a DB row, by any instance. Advisory: nothing routes on a badge, so it can
+* afford a tight bound. Two independent heartbeat domains consult it — Platform
+* connection health (platform_connections) and agent liveness in the
+* dashboard's infrastructure tree — so the two badges cannot drift apart.
+* Browser-safe so the dashboard renders against the same numbers the server
+* computes with.
+*
+* **Teardown policy** — applied by the owning instance to its own live sockets.
+* Wider than the rendering bounds because the `platform_connections.status`
+* write it drives gates every `status = 'connected'` reader — among them the
+* plan-limit connection count, the cross-instance relay lookup, the dashboard
+* proxy's owning-instance lookup, and the stale-orchestrator detector. Marking
+* a live socket unhealthy too eagerly removes it from routing while it is still
+* serving.
+*
+* The two policies also cover different lifetimes. An instance that closes a
+* socket at HEARTBEAT_CLOSE_MS deletes its row in the same step, so the `stale`
+* (HEARTBEAT_DEGRADED_MS) and `orphaned` (HEARTBEAT_STALE_THRESHOLD_SECONDS)
+* levels describe rows that delete never ran for — the ones the orphan sweeper
+* reaps. That is why the sweeper cutoff sits at twice HEARTBEAT_CLOSE_MS: a
+* clean close always beats the sweep to the row.
+*
+* Neither policy has an unclassified case, which is what makes them safe to
+* keep separate: the rendering policy maps a missing `last_heartbeat_at` to
+* `orphaned` (worst-case, no heartbeat evidence at all), and the teardown
+* policy never encounters one because the registry stamps `lastHeartbeatAt` at
+* registration. Any future attempt to collapse the two must preserve that — an
+* unknown treated as healthy hides a dead peer, and one treated as unhealthy
+* sheds a live one.
+*
+* Consumers:
+*  - platform ws/connection-health.ts       — the four-level status computation
+*  - platform ws/heartbeat.ts               — the teardown policy
+*  - platform queue/jobs/orphan-sweeper.ts  — periodic DELETE of orphan rows
+*  - platform ws/registry.ts                — plan-limit count excludes stale rows
+*  - platform dashboard/routes/admin.ts     — GET /admin/connections filter enum
+*  - platform dev-ops/developer-ops.ts      — the diagnostics badge + orphan count
+*  - dashboard utils/diagnostics-helpers.ts — agent heartbeat badge colour
+*/
+/** A heartbeat younger than this is fully healthy. */
+const HEARTBEAT_FRESH_MS = 6e4;
+/** Between fresh and this, the peer is degraded but not yet presumed gone. */
+const HEARTBEAT_DEGRADED_MS = 3e5;
+/**
+* A row is considered stale (the owning orchestrator process is no longer
+* publishing heartbeats) when `last_heartbeat_at` is older than this. Past it,
+* the connection is orphaned and the sweeper is entitled to delete the row.
+*
+* The Platform's same-instance DB eviction on reconnect
+* (`ws/handler.ts#handleSourceRegistration`) shares this rationale: the DELETE
+* itself is unconditional on staleness, but the reason it is needed at all is
+* this same staleness window.
+*/
+const HEARTBEAT_STALE_THRESHOLD_SECONDS = 360;
+/**
+* Silence after which the owning instance writes
+* `platform_connections.status = 'unhealthy'`. Wider than HEARTBEAT_FRESH_MS
+* because that write gates relay routing, not rendering.
+*/
+const HEARTBEAT_UNHEALTHY_MARK_MS = 9e4;
+/**
+* Silence after which the owning instance closes the socket with
+* WS_CLOSE_HEARTBEAT_TIMEOUT (4004) and drops it from the registry — which
+* deletes the platform_connections row too. A row outlives its socket only when
+* that delete never ran; the orphan sweeper reaps those.
+*/
+const HEARTBEAT_CLOSE_MS = 18e4;
+/** The four-level connection health vocabulary, worst-last. */
+const connectionHealthStatusSchema = z.enum([
+	"connected",
+	"unhealthy",
+	"stale",
+	"orphaned"
+]);
+//#endregion
+export { HEARTBEAT_CLOSE_MS, HEARTBEAT_DEGRADED_MS, HEARTBEAT_FRESH_MS, HEARTBEAT_STALE_THRESHOLD_SECONDS, HEARTBEAT_UNHEALTHY_MARK_MS, connectionHealthStatusSchema };
+
+//# sourceMappingURL=heartbeat-health.js.map

package/dist/protocol/messages/log-stream.d.ts

@@ -0,0 +1,18 @@
+import { z } from 'zod';
+/**
+ * Which of a subprocess's two output streams a run-log line came from.
+ *
+ * Carried per log chunk rather than per line: chunks are delivered in order and
+ * the agent closes the pending chunk whenever the kind flips, so stdout/stderr
+ * interleaving is preserved without a per-line field.
+ *
+ * Lives in its own module because three protocol planes reference it — the
+ * agent→orchestrator chunk, the orchestrator→Platform relay, and the
+ * Platform→browser fan-out — and a shared leaf keeps those files acyclic.
+ */
+export declare const LogStream: z.ZodEnum<{
+    stderr: "stderr";
+    stdout: "stdout";
+}>;
+export type LogStream = z.infer<typeof LogStream>;
+//# sourceMappingURL=log-stream.d.ts.map

package/dist/protocol/messages/log-stream.js

@@ -0,0 +1,19 @@
+import "../../rolldown-runtime-ClRpJifh.js";
+import { z } from "zod";
+//#region src/protocol/messages/log-stream.ts
+/**
+* Which of a subprocess's two output streams a run-log line came from.
+*
+* Carried per log chunk rather than per line: chunks are delivered in order and
+* the agent closes the pending chunk whenever the kind flips, so stdout/stderr
+* interleaving is preserved without a per-line field.
+*
+* Lives in its own module because three protocol planes reference it — the
+* agent→orchestrator chunk, the orchestrator→Platform relay, and the
+* Platform→browser fan-out — and a shared leaf keeps those files acyclic.
+*/
+const LogStream = z.enum(["stdout", "stderr"]);
+//#endregion
+export { LogStream };
+
+//# sourceMappingURL=log-stream.js.map

package/dist/protocol/messages/oidc-mint.d.ts

@@ -1,4 +1,11 @@
 import { z } from 'zod';
+/**
+ * @deprecated The `oidc.mint.*` RPC pair (Platform-rooted identity mint) is
+ * hard-deprecated in favor of orchestrator-owned signing. It is kept
+ * wire-compatible for the mixed-version rollout window and removed at v1.0; a
+ * fresh orchestrator with its own signer never sends it. See
+ * docs/user/deprecations.md.
+ */
 /**
  * Error discriminator for a failed provenance mint, carried on
  * `oidc.mint.response.error.code`. Mirrors the three orchestrator-side error

package/dist/protocol/messages/oidc-mint.js

@@ -3,6 +3,13 @@ import { AttestationOrigin } from "../../provenance/attestation-origin.js";
 import { z } from "zod";
 //#region src/protocol/messages/oidc-mint.ts
 /**
+* @deprecated The `oidc.mint.*` RPC pair (Platform-rooted identity mint) is
+* hard-deprecated in favor of orchestrator-owned signing. It is kept
+* wire-compatible for the mixed-version rollout window and removed at v1.0; a
+* fresh orchestrator with its own signer never sends it. See
+* docs/user/deprecations.md.
+*/
+/**
 * Error discriminator for a failed provenance mint, carried on
 * `oidc.mint.response.error.code`. Mirrors the three orchestrator-side error
 * classes that consume it: