@sentropic/h2a-runtime 0.81.0

package/dist/browser-bridge-local.js

@@ -0,0 +1,51 @@
+export const NOVNC_POD_PORT = 6080;
+export function evaluateExposure(req) {
+    switch (req.policy) {
+        case "operator-only":
+            return req.requester === "operator"
+                ? { allowed: true }
+                : { allowed: false, reason: `policy "operator-only" forbids requester "${req.requester}" — only an operator may expose this browser` };
+        case "session-private":
+            if (req.requester === "anonymous") {
+                return { allowed: false, reason: 'policy "session-private" forbids an anonymous requester — only the session owner or an operator may expose this browser' };
+            }
+            if (!req.hasToken) {
+                return { allowed: false, reason: 'policy "session-private" requires a per-session access token on the route (none present)' };
+            }
+            return { allowed: true };
+        case "public-expiring":
+            if (!req.hasToken) {
+                return { allowed: false, reason: 'policy "public-expiring" requires a per-session access token on the route (none present)' };
+            }
+            if (req.expiresInMs === undefined || req.expiresInMs <= 0) {
+                return { allowed: false, reason: 'policy "public-expiring" requires a finite positive expiry (expiresInMs) — refusing an open-ended public route' };
+            }
+            return { allowed: true };
+    }
+}
+export function buildForwardCommand(sessionId, localPort) {
+    const tail = localPort === undefined ? "" : ` ${localPort}`;
+    return `remote forward ${sessionId} ${NOVNC_POD_PORT}${tail}`;
+}
+export function buildNoVncUrl(opts) {
+    const host = opts.host ?? "localhost";
+    const port = opts.localPort ?? NOVNC_POD_PORT;
+    const interactive = opts.interactive ?? true;
+    const autoconnect = opts.autoconnect ?? true;
+    const params = new URLSearchParams();
+    params.set("path", `websockify?token=${opts.token}`);
+    if (autoconnect)
+        params.set("autoconnect", "true");
+    if (!interactive)
+        params.set("view_only", "true");
+    return `http://${host}:${port}/vnc.html?${params.toString()}`;
+}
+const defaultRandomBytes = (length) => {
+    const out = new Uint8Array(length);
+    globalThis.crypto.getRandomValues(out);
+    return out;
+};
+export function mintNoVncToken(rng = defaultRandomBytes) {
+    return Array.from(rng(16), (b) => b.toString(16).padStart(2, "0")).join("");
+}
+//# sourceMappingURL=browser-bridge-local.js.map

package/dist/browser-bridge-local.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-bridge-local.js","sourceRoot":"","sources":["../src/browser-bridge-local.ts"],"names":[],"mappings":"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"}

package/dist/browser.d.ts

@@ -0,0 +1,53 @@
+/**
+ * `remote browser open <sessionId>` — WP7 noVNC headful browser-in-pod.
+ *
+ * One command to open the headful browser view for a session so the user can
+ * complete a 2FA / login challenge visually. The heavy lifting (spawning the
+ * Xvfb+Chromium+x11vnc+websockify+noVNC sidecar) happens IN the Pod via the
+ * browser-bridge; this CLI surface is the user's entry point:
+ *
+ *   1. enforce the uat-exposure-policy locally (deny early with a reason);
+ *   2. mint the per-session noVNC token + build the forwardable noVNC URL;
+ *   3. print the exact `remote forward <id> 6080` command and the URL to open.
+ *
+ * The actual port-forward is delegated to the existing `remote forward`
+ * transport (forward.ts) — we don't duplicate kubectl wiring. The token is the
+ * only sensitive value; it is printed ONCE to the user's own terminal (so they
+ * can open the gated URL) and never logged elsewhere. The pure builder below is
+ * unit-tested; the action wiring lives in index.ts.
+ */
+import { type ExposureRequester, type RandomBytes } from "./browser-bridge-local.js";
+import type { UatExposurePolicy } from "./protocol-local.js";
+export type BrowserOpenPlan = {
+    readonly ok: true;
+    readonly podPort: number;
+    readonly forwardCommand: string;
+    readonly url: string;
+    /** Human-facing multi-line instructions (token only in the URL). */
+    readonly instructions: string;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+export type BuildBrowserOpenPlanOptions = {
+    readonly sessionId: string;
+    /** Default session-private — only the owner, token-gated. */
+    readonly exposurePolicy?: UatExposurePolicy;
+    /** Default session-owner (the user running the CLI owns the session). */
+    readonly requester?: ExposureRequester;
+    /** Local port the user will bind the forward to (optional). */
+    readonly localPort?: number;
+    /** Interactive (drive the 2FA) — default true. */
+    readonly interactive?: boolean;
+    /** Route TTL in ms (only required by the public-expiring policy). */
+    readonly ttlMs?: number;
+    /** Injectable RNG for the token (tests). */
+    readonly rng?: RandomBytes;
+};
+/**
+ * Build the open plan: policy-gate, then the forward command + noVNC URL the
+ * user runs/opens. Pure (token from the injected RNG) so the allow/deny and the
+ * exact command/URL are unit-tested without a cluster.
+ */
+export declare function buildBrowserOpenPlan(opts: BuildBrowserOpenPlanOptions): BrowserOpenPlan;
+//# sourceMappingURL=browser.d.ts.map

package/dist/browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAML,KAAK,iBAAiB,EACtB,KAAK,WAAW,EACjB,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAE7D,MAAM,MAAM,eAAe,GACvB;IACE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,oEAAoE;IACpE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B,GACD;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpD,MAAM,MAAM,2BAA2B,GAAG;IACxC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,6DAA6D;IAC7D,QAAQ,CAAC,cAAc,CAAC,EAAE,iBAAiB,CAAC;IAC5C,yEAAyE;IACzE,QAAQ,CAAC,SAAS,CAAC,EAAE,iBAAiB,CAAC;IACvC,+DAA+D;IAC/D,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,kDAAkD;IAClD,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B,qEAAqE;IACrE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,4CAA4C;IAC5C,QAAQ,CAAC,GAAG,CAAC,EAAE,WAAW,CAAC;CAC5B,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,2BAA2B,GAChC,eAAe,CAwCjB"}

package/dist/browser.js

@@ -0,0 +1,61 @@
+/**
+ * `remote browser open <sessionId>` — WP7 noVNC headful browser-in-pod.
+ *
+ * One command to open the headful browser view for a session so the user can
+ * complete a 2FA / login challenge visually. The heavy lifting (spawning the
+ * Xvfb+Chromium+x11vnc+websockify+noVNC sidecar) happens IN the Pod via the
+ * browser-bridge; this CLI surface is the user's entry point:
+ *
+ *   1. enforce the uat-exposure-policy locally (deny early with a reason);
+ *   2. mint the per-session noVNC token + build the forwardable noVNC URL;
+ *   3. print the exact `remote forward <id> 6080` command and the URL to open.
+ *
+ * The actual port-forward is delegated to the existing `remote forward`
+ * transport (forward.ts) — we don't duplicate kubectl wiring. The token is the
+ * only sensitive value; it is printed ONCE to the user's own terminal (so they
+ * can open the gated URL) and never logged elsewhere. The pure builder below is
+ * unit-tested; the action wiring lives in index.ts.
+ */
+import { buildForwardCommand, buildNoVncUrl, evaluateExposure, mintNoVncToken, NOVNC_POD_PORT, } from "./browser-bridge-local.js";
+/**
+ * Build the open plan: policy-gate, then the forward command + noVNC URL the
+ * user runs/opens. Pure (token from the injected RNG) so the allow/deny and the
+ * exact command/URL are unit-tested without a cluster.
+ */
+export function buildBrowserOpenPlan(opts) {
+    const policy = opts.exposurePolicy ?? "session-private";
+    const requester = opts.requester ?? "session-owner";
+    const interactive = opts.interactive ?? true;
+    const decision = evaluateExposure({
+        policy,
+        requester,
+        hasToken: true, // we always mint a token below
+        ...(policy === "public-expiring" && opts.ttlMs !== undefined
+            ? { expiresInMs: opts.ttlMs }
+            : {}),
+    });
+    if (!decision.allowed) {
+        return { ok: false, reason: decision.reason };
+    }
+    const token = mintNoVncToken(opts.rng);
+    const forwardCommand = buildForwardCommand(opts.sessionId, opts.localPort);
+    const url = buildNoVncUrl({
+        token,
+        interactive,
+        ...(opts.localPort !== undefined ? { localPort: opts.localPort } : {}),
+    });
+    const instructions = `[remote] headful browser for ${opts.sessionId} (noVNC, ${policy})\n` +
+        `[remote] 1. open the port-forward (foreground, Ctrl-C to stop):\n` +
+        `           ${forwardCommand}\n` +
+        `[remote] 2. then open this URL in your browser:\n` +
+        `           ${url}\n` +
+        `[remote] complete the 2FA/login in the desktop, then stop the forward.\n`;
+    return {
+        ok: true,
+        podPort: NOVNC_POD_PORT,
+        forwardCommand,
+        url,
+        instructions,
+    };
+}
+//# sourceMappingURL=browser.js.map

package/dist/browser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.js","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EACL,mBAAmB,EACnB,aAAa,EACb,gBAAgB,EAChB,cAAc,EACd,cAAc,GAGf,MAAM,2BAA2B,CAAC;AA8BnC;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAClC,IAAiC;IAEjC,MAAM,MAAM,GAAsB,IAAI,CAAC,cAAc,IAAI,iBAAiB,CAAC;IAC3E,MAAM,SAAS,GAAsB,IAAI,CAAC,SAAS,IAAI,eAAe,CAAC;IACvE,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,IAAI,IAAI,CAAC;IAE7C,MAAM,QAAQ,GAAG,gBAAgB,CAAC;QAChC,MAAM;QACN,SAAS;QACT,QAAQ,EAAE,IAAI,EAAE,+BAA+B;QAC/C,GAAG,CAAC,MAAM,KAAK,iBAAiB,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS;YAC1D,CAAC,CAAC,EAAE,WAAW,EAAE,IAAI,CAAC,KAAK,EAAE;YAC7B,CAAC,CAAC,EAAE,CAAC;KACR,CAAC,CAAC;IACH,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC;QACtB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC;IAChD,CAAC;IAED,MAAM,KAAK,GAAG,cAAc,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACvC,MAAM,cAAc,GAAG,mBAAmB,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;IAC3E,MAAM,GAAG,GAAG,aAAa,CAAC;QACxB,KAAK;QACL,WAAW;QACX,GAAG,CAAC,IAAI,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACvE,CAAC,CAAC;IAEH,MAAM,YAAY,GAChB,gCAAgC,IAAI,CAAC,SAAS,YAAY,MAAM,KAAK;QACrE,mEAAmE;QACnE,cAAc,cAAc,IAAI;QAChC,mDAAmD;QACnD,cAAc,GAAG,IAAI;QACrB,0EAA0E,CAAC;IAE7E,OAAO;QACL,EAAE,EAAE,IAAI;QACR,OAAO,EAAE,cAAc;QACvB,cAAc;QACd,GAAG;QACH,YAAY;KACb,CAAC;AACJ,CAAC"}

package/dist/conductor-launch.d.ts

@@ -0,0 +1,179 @@
+/**
+ * WP10 — handler for h2a `conductor-launch-request` envelopes (PURE core).
+ *
+ * The h2a maintainer (a2a-cli, h2a 0.68.0) owns the EMIT side: when a workspace
+ * has STALLED work AND no live conductor, h2a drops an envelope into `remote`'s
+ * h2a inbox. h2a NEVER spawns — `remote` is the executor. This module is the
+ * PURE decision core (parse + validate + select host + cooldown gate + task
+ * builder); the side-effecting wiring (PATH detection, registry/h2a probes,
+ * launch, inbox marking) lives in index.ts behind injectable seams.
+ *
+ * The on-disk envelope mirrors the standard h2a shape `{protocol, version, id,
+ * type, actor, to, body, createdAt}` (h2a-jobs.ts / h2a-bridge.ts README). The
+ * WP10 contract puts the payload on `body`:
+ *   body.kind  = "message"
+ *   body.topic = "conductor-launch-request"
+ *   body.request = { kind, workspaceId, hostPref, stalled[], reason }
+ * (we also tolerate the request fields spread directly onto `body` rather than
+ * nested under `body.request`, since the maintainer's exact nesting is not yet
+ * pinned — flagged for a2a-cli alignment).
+ *
+ * SECURITY: the conductor task is plain prose passed as a SINGLE argv token by
+ * the caller (buildDelegateArgs → startJob); it is NEVER concatenated into a
+ * `bash -lc` string. Nothing here shells out.
+ */
+import type { DelegateType } from "./delegate.js";
+/** The contract topic the maintainer emits under. */
+export declare const CONDUCTOR_LAUNCH_TOPIC = "conductor-launch-request";
+/**
+ * Default host preference order when the envelope omits one / lists only
+ * unknown hosts. Mirrors the maintainer's documented default
+ * (`['claude','codex','agy']`).
+ */
+export declare const DEFAULT_HOST_PREF: ReadonlyArray<DelegateType>;
+/** A stalled work item the conductor should pick up (best-effort fields). */
+export type StalledItem = {
+    id: string;
+    title: string;
+    reason?: string;
+    since?: string;
+};
+/** The typed, validated payload of a `conductor-launch-request` envelope. */
+export type ConductorLaunchRequest = {
+    kind: "conductor-launch-request";
+    /** Durable git-shared id: `ws:<hex>` (matchable via computeDurableWorkspaceId). */
+    workspaceId: string;
+    /** Ordered host preference (claude/codex/agy), normalized + filtered to known hosts. */
+    hostPref: DelegateType[];
+    stalled: StalledItem[];
+    reason: string;
+};
+/**
+ * Parse + validate an incoming `conductor-launch-request` envelope (a JSON
+ * string OR an already-parsed object) into a typed `ConductorLaunchRequest`.
+ * Returns undefined when the input is not a valid conductor-launch envelope:
+ *  - not JSON / not an object,
+ *  - body.kind !== "message" or body.topic !== "conductor-launch-request",
+ *  - no workspaceId.
+ * Tolerates the request nested under `body.request` OR spread onto `body`.
+ * Pure (no fs / no clock), exported for tests.
+ */
+export declare function parseConductorLaunchEnvelope(input: string | unknown): ConductorLaunchRequest | undefined;
+/**
+ * Pick the host to launch: the FIRST entry of `hostPref` that is in
+ * `availableHosts` (the CLIs found on PATH). Honors the preference ORDER, not
+ * the set's. Returns undefined when none of the preferred hosts is available.
+ * Pure, exported for tests.
+ */
+export declare function selectHost(hostPref: ReadonlyArray<DelegateType>, availableHosts: ReadonlySet<DelegateType>): DelegateType | undefined;
+export type ShouldLaunchInput = {
+    request: ConductorLaunchRequest;
+    /** How many conductors we already know to be alive for this workspace (registry + h2a). */
+    liveConductors: number;
+    /** Epoch ms of the last launch for THIS workspace, or undefined when none. */
+    lastLaunchAt: number | undefined;
+    now: number;
+    cooldownMs: number;
+};
+export type ShouldLaunchResult = {
+    launch: boolean;
+    reason: string;
+};
+/**
+ * The launch gate, in priority order (each branch is mutually exclusive):
+ *  1. a conductor is already alive → SKIP (idempotency, the whole point),
+ *  2. there is no stalled work → SKIP (nothing to conduct),
+ *  3. a launch happened within the cooldown window → SKIP (watch-loop guard),
+ *  4. otherwise → LAUNCH.
+ * The live-conductor check wins over the cooldown so an idempotent skip is
+ * always reported as such. Pure (clock injected via `now`), exported for tests.
+ */
+export declare function shouldLaunch(input: ShouldLaunchInput): ShouldLaunchResult;
+/**
+ * The task prompt for the delegated conductor. It instructs the agent to CLAIM
+ * the conductor role at boot (`h2a conductor claim`, if available) then conduct
+ * the stalled items. Returned as plain prose — the caller passes it as a SINGLE
+ * argv token (buildDelegateArgs → startJob); it is NEVER shell-concatenated.
+ * Pure, exported for tests.
+ */
+export declare function buildConductorTask(request: ConductorLaunchRequest): string;
+/**
+ * Normalize the root-commit set into the canonical string a2a-cli/track hash:
+ * ALL root commits (`git rev-list --max-parents=0 HEAD`), trimmed, de-duped,
+ * sorted ascending, joined by ",". A mono-root repo collapses to its single
+ * SHA. Invariant across clone / fork / path / machine (unlike a remote url).
+ * Pure, exported for tests.
+ */
+export declare function normalizeRootCommits(shas: ReadonlyArray<string>): string;
+/**
+ * Durable, git-shared workspace id — byte-identical to track + h2a 0.68's
+ * `durableWorkspaceId`:
+ *
+ *   workspaceId = "ws:" + sha256hex( rootCommitSHA + "\n" + worktreeRelPath )
+ *
+ * where `rootCommitSHA` is {@link normalizeRootCommits}' output and
+ * `worktreeRelPath` is "" for the primary worktree, else the basename of
+ * `git rev-parse --git-dir` (the `.git/worktrees/<name>` dir) for a linked
+ * worktree. Pinned vectors (shared with track): ("abc","") →
+ * ws:edeaaff3… ; ("abc","my-feature") → ws:81a25e53…. Pure, exported for tests.
+ */
+export declare function computeDurableWorkspaceId(rootCommitSHA: string, worktreeRelPath: string): string;
+/**
+ * Which delegate hosts (claude/codex/agy) are resolvable on PATH. The `which`
+ * seam is injectable; the default uses a login shell `command -v` (same probe
+ * as tmux.ts commandAvailable / delegate.ts defaultWhich), so it sees the same
+ * binaries the tmux windows would. Best-effort: a failing probe = not present.
+ */
+export declare function detectAvailableHosts(which?: (bin: string) => boolean): Set<DelegateType>;
+/**
+ * Thin seam over a live `h2a` call: returns the raw stdout, or undefined when
+ * the `h2a` binary is missing / errors (GRACEFUL DEGRADE — the caller treats an
+ * undefined result as "can't tell from h2a", falling back to our own registry).
+ * The runner is injectable so tests never shell out. Best-effort, never throws.
+ */
+export type H2aRunner = (args: ReadonlyArray<string>) => string | undefined;
+export declare function defaultH2aRunner(args: ReadonlyArray<string>): string | undefined;
+/**
+ * Does h2a itself report a live conductor for `workspaceId`? Best-effort over
+ * `h2a discover` (whatever shape it prints — we only look for the durable id +
+ * a "conductor" mention near it). Returns:
+ *  - true  → h2a sees a conductor (definitely skip),
+ *  - false → h2a ran and did NOT mention one,
+ *  - undefined → h2a unavailable / unparseable (caller relies on the registry).
+ * Conservative substring match (the maintainer's discover output is not pinned
+ * — flagged for a2a-cli alignment). The runner is injectable.
+ */
+export declare function h2aReportsLiveConductor(workspaceId: string, run?: H2aRunner): boolean | undefined;
+export type LaunchEnvelopeFile = {
+    /** Absolute path of the envelope file. */
+    path: string;
+    /** mtime (epoch ms) — used to pick the FRESHEST unprocessed envelope. */
+    mtimeMs: number;
+    request: ConductorLaunchRequest;
+};
+/**
+ * Read every `conductor-launch-request` envelope under `<localRoot>/inbox/**`
+ * (one dir level deep, the h2a layout — same as h2a-jobs.readInboxEnvelopes),
+ * parsed + validated. Skips already-processed ones (a sibling `.processed`
+ * stamp, see markProcessed). Missing store → []. Never throws on a bad file.
+ * The fs is isolated here so the parsing above stays pure.
+ */
+export declare function readLaunchEnvelopes(localRoot?: string): LaunchEnvelopeFile[];
+/** The freshest (highest mtime) unprocessed launch envelope, or undefined. Pure. */
+export declare function freshestLaunchEnvelope(envelopes: ReadonlyArray<LaunchEnvelopeFile>): LaunchEnvelopeFile | undefined;
+/**
+ * Idempotently mark an envelope processed by dropping a sibling `.processed`
+ * stamp next to it (we never DELETE the envelope — the bridge/h2a own cleanup,
+ * exactly like dropEnvelope's non-destructive contract). Best-effort: returns
+ * false on any fs error. `note` is a short human reason (dry-run vs launched).
+ */
+export declare function markLaunchEnvelopeProcessed(envelopePath: string, note: string, nowMs?: number): boolean;
+/** Read the last-launch epoch ms for `workspaceId`, or undefined. Best-effort. */
+export declare function readLastLaunchAt(workspaceId: string, localRoot?: string): number | undefined;
+/**
+ * Record `nowMs` as the last launch for `workspaceId` (so a watch loop honors
+ * the per-workspace cooldown). Best-effort: returns false on any fs error.
+ * Atomic-ish (tmp + rename) like the registry.
+ */
+export declare function recordLaunchAt(workspaceId: string, nowMs?: number, localRoot?: string): boolean;
+//# sourceMappingURL=conductor-launch.d.ts.map

package/dist/conductor-launch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conductor-launch.d.ts","sourceRoot":"","sources":["../src/conductor-launch.ts"],"names":[],"mappings":"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"}