@stigmer/runner 0.1.0-dev.20261017020314.g644422724c27

package/dist/attach/waiter.d.ts

@@ -0,0 +1,108 @@
+/**
+ * The attach waiter: a sandbox that has no work yet, waiting to be told which
+ * task queue to serve, and then running the runner for it.
+ *
+ * Why a waiter and not a waiting runner. A sandbox platform that snapshots a
+ * started sandbox once and starts every later sandbox from that snapshot
+ * (Agent Substrate's golden snapshot) clones the snapshotted processes'
+ * memory into all of them. Measured on 2026-10-03 (gVisor, Node 22.23.2,
+ * OpenSSL 3.5.7): every clone of one snapshot produced the same
+ * `crypto.randomBytes`, the same x25519 keys, the same `randomUUID` and the
+ * same `Math.random`, even when the process drew nothing before the snapshot
+ * (Node seeds OpenSSL at process start) and even eight minutes later
+ * (OpenSSL reseeds from its own cloned state). A process started after the
+ * restore draws its own. So the snapshot holds this small process, which
+ * never makes a network call or uses randomness, and the runner always
+ * starts fresh, after the push, with its credentials in hand. The same
+ * measurement put a fresh slim runner at about 1.6 s from start to polling
+ * its queue.
+ *
+ * What it does:
+ *
+ *   - `GET /readyz` answers 200 as soon as the listener is up. A platform
+ *     that takes its snapshot once its readiness probe answers therefore
+ *     snapshots this process idle, never a runner mid-boot.
+ *   - `POST /attach` takes a push (`push.ts`). The first accepted push starts
+ *     the runner, with this sandbox's own environment plus
+ *     `STIGMER_TASK_QUEUE` and the pushed secrets: exactly the environment a
+ *     sandbox pod gives the runner at start, so the runner boots in its
+ *     ordinary static mode, unchanged. A later push for the same queue (a
+ *     driver pushes on every wakeup, with a fresh token) may only rotate
+ *     `STIGMER_TOKEN`: the token it carries is the one the runner restarts
+ *     with, and every other secret must be the first push's, so a caller
+ *     inside the sandbox (its agent can reach the listener over loopback)
+ *     cannot swap the runner's other secrets or drop its token, nor replace
+ *     it with a token of another kind or for another session. The live
+ *     runner keeps renewing its own token as it does in a pod. A push for
+ *     another queue is refused. Every refusal carries a stable `code`
+ *     (push.ts, PushRefusalCode) beside its text, so a driver acts on the
+ *     code: `secrets_changed` tells it the runner must start fresh to take
+ *     new secrets.
+ *   - It supervises the runner the way a pod's restart policy does: a runner
+ *     that exits is started again, after a delay that grows to a cap, with
+ *     the latest pushed environment. A push that arrives while a restart
+ *     waits out its delay starts the runner at once, since a push means a
+ *     turn is about to need it. Stopping the waiter stops the runner first
+ *     and waits for its graceful shutdown.
+ *
+ * One limit, the same as a pod's: a restart uses the latest PUSHED token, not
+ * the one the live runner renewed in-process (`sandbox-token-renewal.ts`).
+ * A runner that crashes after that token has expired restarts with a dead
+ * credential and retries at the delay cap until the driver's next push. So a
+ * driver pushes on every wakeup, and a composition whose tokens are renewed
+ * pushes the renewed token while the sandbox runs.
+ *
+ * Neither the token nor any secret is ever logged.
+ */
+import { type Server } from "node:http";
+import { type ChildProcess } from "node:child_process";
+import { type AttachPush } from "./push.js";
+/** Variables that configure the waiter itself and are not passed to the runner. */
+export declare const WAITER_ENV_KEYS: readonly string[];
+export type RunnerSpawner = (entry: string, env: NodeJS.ProcessEnv) => ChildProcess;
+export interface AttachWaiterOptions {
+    /** Port the listener binds; 0 picks a free one (tests). */
+    readonly port: number;
+    /** This sandbox's own name, read at push time (it differs per clone). */
+    readonly readSandboxName: () => string;
+    /** The runner's entry module, started with the current Node. */
+    readonly runnerEntry: string;
+    /** This sandbox's own environment, the base of the runner's. */
+    readonly baseEnv: NodeJS.ProcessEnv;
+    /** Seconds since the epoch. */
+    readonly now?: () => number;
+    readonly spawnRunner?: RunnerSpawner;
+    /** First restart delay; doubles per consecutive exit up to `maxRestartDelayMs`. */
+    readonly restartDelayMs?: number;
+    readonly maxRestartDelayMs?: number;
+    readonly log?: (message: string) => void;
+}
+export interface AttachWaiter {
+    readonly server: Server;
+    /** The bound port. */
+    readonly port: number;
+    /** The queue being served, once attached. */
+    attachedQueue(): string | undefined;
+    /** Stop the runner (waiting for its exit) and close the listener. */
+    close(): Promise<void>;
+}
+/** The runner's environment for one push: the sandbox's own, minus the waiter's, plus the push. */
+export declare function runnerEnvFor(baseEnv: NodeJS.ProcessEnv, push: AttachPush): NodeJS.ProcessEnv;
+/** Why a later push was refused: a stable code and a reason for people. */
+export interface LaterPushRefusal {
+    readonly code: "secrets_changed" | "token_mismatch";
+    readonly reason: string;
+}
+/**
+ * Why a later push may not be accepted, or undefined when it only rotates the
+ * token: every secret but `STIGMER_TOKEN` must equal the first push's
+ * (`secrets_changed`), and a token the first push carried may be replaced but
+ * not dropped, nor replaced by one of another kind: the new token must keep
+ * the first one's `token_type` and, when the first named a session, that
+ * session (`token_mismatch`). Tokens that name an execution rather than a
+ * session carry no session claim, so the rule holds for them too.
+ */
+export declare function laterPushRefusal(first: Readonly<Record<string, string>>, later: Readonly<Record<string, string>>): LaterPushRefusal | undefined;
+/** An error's code (or name), never its message, which may quote a pushed value. */
+export declare function spawnErrorCode(err: unknown): string;
+export declare function startAttachWaiter(options: AttachWaiterOptions): Promise<AttachWaiter>;

package/dist/attach/waiter.js

@@ -0,0 +1,323 @@
+/**
+ * The attach waiter: a sandbox that has no work yet, waiting to be told which
+ * task queue to serve, and then running the runner for it.
+ *
+ * Why a waiter and not a waiting runner. A sandbox platform that snapshots a
+ * started sandbox once and starts every later sandbox from that snapshot
+ * (Agent Substrate's golden snapshot) clones the snapshotted processes'
+ * memory into all of them. Measured on 2026-10-03 (gVisor, Node 22.23.2,
+ * OpenSSL 3.5.7): every clone of one snapshot produced the same
+ * `crypto.randomBytes`, the same x25519 keys, the same `randomUUID` and the
+ * same `Math.random`, even when the process drew nothing before the snapshot
+ * (Node seeds OpenSSL at process start) and even eight minutes later
+ * (OpenSSL reseeds from its own cloned state). A process started after the
+ * restore draws its own. So the snapshot holds this small process, which
+ * never makes a network call or uses randomness, and the runner always
+ * starts fresh, after the push, with its credentials in hand. The same
+ * measurement put a fresh slim runner at about 1.6 s from start to polling
+ * its queue.
+ *
+ * What it does:
+ *
+ *   - `GET /readyz` answers 200 as soon as the listener is up. A platform
+ *     that takes its snapshot once its readiness probe answers therefore
+ *     snapshots this process idle, never a runner mid-boot.
+ *   - `POST /attach` takes a push (`push.ts`). The first accepted push starts
+ *     the runner, with this sandbox's own environment plus
+ *     `STIGMER_TASK_QUEUE` and the pushed secrets: exactly the environment a
+ *     sandbox pod gives the runner at start, so the runner boots in its
+ *     ordinary static mode, unchanged. A later push for the same queue (a
+ *     driver pushes on every wakeup, with a fresh token) may only rotate
+ *     `STIGMER_TOKEN`: the token it carries is the one the runner restarts
+ *     with, and every other secret must be the first push's, so a caller
+ *     inside the sandbox (its agent can reach the listener over loopback)
+ *     cannot swap the runner's other secrets or drop its token, nor replace
+ *     it with a token of another kind or for another session. The live
+ *     runner keeps renewing its own token as it does in a pod. A push for
+ *     another queue is refused. Every refusal carries a stable `code`
+ *     (push.ts, PushRefusalCode) beside its text, so a driver acts on the
+ *     code: `secrets_changed` tells it the runner must start fresh to take
+ *     new secrets.
+ *   - It supervises the runner the way a pod's restart policy does: a runner
+ *     that exits is started again, after a delay that grows to a cap, with
+ *     the latest pushed environment. A push that arrives while a restart
+ *     waits out its delay starts the runner at once, since a push means a
+ *     turn is about to need it. Stopping the waiter stops the runner first
+ *     and waits for its graceful shutdown.
+ *
+ * One limit, the same as a pod's: a restart uses the latest PUSHED token, not
+ * the one the live runner renewed in-process (`sandbox-token-renewal.ts`).
+ * A runner that crashes after that token has expired restarts with a dead
+ * credential and retries at the delay cap until the driver's next push. So a
+ * driver pushes on every wakeup, and a composition whose tokens are renewed
+ * pushes the renewed token while the sandbox runs.
+ *
+ * Neither the token nor any secret is ever logged.
+ */
+import { createServer } from "node:http";
+import { spawn } from "node:child_process";
+import { sessionIdClaimOf, tokenTypeOf } from "../client/token-claims.js";
+import { verifyAttachPush } from "./push.js";
+/** Largest push body accepted; a real push is a few kilobytes. */
+const MAX_PUSH_BYTES = 64 * 1024;
+/** Variables that configure the waiter itself and are not passed to the runner. */
+export const WAITER_ENV_KEYS = [
+    "STIGMER_ATTACH_PORT",
+    "STIGMER_SANDBOX_NAME_FILE",
+];
+const defaultSpawner = (entry, env) => spawn(process.execPath, [entry], { env, stdio: "inherit" });
+/** The runner's environment for one push: the sandbox's own, minus the waiter's, plus the push. */
+export function runnerEnvFor(baseEnv, push) {
+    const env = { ...baseEnv };
+    for (const key of WAITER_ENV_KEYS)
+        delete env[key];
+    return { ...env, STIGMER_TASK_QUEUE: push.taskQueue, ...push.secrets };
+}
+/**
+ * Why a later push may not be accepted, or undefined when it only rotates the
+ * token: every secret but `STIGMER_TOKEN` must equal the first push's
+ * (`secrets_changed`), and a token the first push carried may be replaced but
+ * not dropped, nor replaced by one of another kind: the new token must keep
+ * the first one's `token_type` and, when the first named a session, that
+ * session (`token_mismatch`). Tokens that name an execution rather than a
+ * session carry no session claim, so the rule holds for them too.
+ */
+export function laterPushRefusal(first, later) {
+    const names = new Set([...Object.keys(first), ...Object.keys(later)]);
+    names.delete("STIGMER_TOKEN");
+    for (const name of names) {
+        if (first[name] !== later[name]) {
+            return {
+                code: "secrets_changed",
+                reason: `a later push may only rotate STIGMER_TOKEN; ${name} differs from the first push`,
+            };
+        }
+    }
+    const firstToken = first.STIGMER_TOKEN ?? "";
+    const laterToken = later.STIGMER_TOKEN ?? "";
+    if (firstToken === "")
+        return undefined;
+    if (laterToken === "") {
+        return { code: "token_mismatch", reason: "a later push may not drop STIGMER_TOKEN" };
+    }
+    if (tokenTypeOf(laterToken) !== tokenTypeOf(firstToken)) {
+        return { code: "token_mismatch", reason: "a later push's token is of another kind than the first push's" };
+    }
+    const firstSession = sessionIdClaimOf(firstToken);
+    if (firstSession !== undefined && sessionIdClaimOf(laterToken) !== firstSession) {
+        return { code: "token_mismatch", reason: "a later push's token names another session than the first push's" };
+    }
+    return undefined;
+}
+/** An error's code (or name), never its message, which may quote a pushed value. */
+export function spawnErrorCode(err) {
+    if (typeof err === "object" && err !== null) {
+        const code = err.code;
+        if (typeof code === "string")
+            return code;
+        if (err instanceof Error)
+            return err.name;
+    }
+    return "unknown error";
+}
+/** A refusal's reply: the stable code a driver acts on, and the reason for people. */
+function refuse(res, status, code, error) {
+    reply(res, status, { error, code });
+}
+function reply(res, status, body) {
+    res.statusCode = status;
+    res.setHeader("content-type", "application/json");
+    res.end(JSON.stringify(body));
+}
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        let size = 0;
+        const chunks = [];
+        // An oversized body is drained and discarded rather than cut off, so the
+        // sender still reads the refusal.
+        req.on("data", (chunk) => {
+            size += chunk.length;
+            if (size <= MAX_PUSH_BYTES)
+                chunks.push(chunk);
+        });
+        req.on("end", () => resolve(size > MAX_PUSH_BYTES ? undefined : Buffer.concat(chunks).toString("utf8")));
+        req.on("error", reject);
+    });
+}
+export async function startAttachWaiter(options) {
+    const now = options.now ?? (() => Math.floor(Date.now() / 1000));
+    const spawnRunner = options.spawnRunner ?? defaultSpawner;
+    const log = options.log ?? ((message) => console.warn(message));
+    const firstDelay = options.restartDelayMs ?? 1000;
+    const maxDelay = options.maxRestartDelayMs ?? 30_000;
+    // The queue this sandbox serves, once attached, the first push's secrets
+    // (fixed for the sandbox's life but for the token), and the environment
+    // the runner (re)starts with.
+    let attachedQueue;
+    let attachedSecrets = {};
+    let runnerEnv = {};
+    let child;
+    let restartTimer;
+    let nextDelay = firstDelay;
+    let stopping = false;
+    // A spawn can throw synchronously (an environment value Node refuses);
+    // its message may quote the value, so only the error's code is logged.
+    function spawnSafely(env) {
+        try {
+            return spawnRunner(options.runnerEntry, env);
+        }
+        catch (err) {
+            log(`[attach] the runner could not be started (${spawnErrorCode(err)})`);
+            return undefined;
+        }
+    }
+    // close() clears a pending restart, so none runs once the waiter is stopping.
+    function scheduleRestart(how) {
+        log(`[attach] runner ${how}; restarting in ${nextDelay}ms`);
+        restartTimer = setTimeout(restart, nextDelay);
+        nextDelay = Math.min(nextDelay * 2, maxDelay);
+    }
+    function restart() {
+        restartTimer = undefined;
+        const started = spawnSafely(runnerEnv);
+        if (started === undefined) {
+            scheduleRestart("could not be started");
+            return;
+        }
+        supervise(started);
+    }
+    function supervise(started) {
+        child = started;
+        const startedAt = Date.now();
+        let settled = false;
+        const onGone = (how) => {
+            if (settled)
+                return;
+            settled = true;
+            if (child === started)
+                child = undefined;
+            if (stopping)
+                return;
+            // A runner that served for a while restarts promptly; one that dies at
+            // once backs off, so a broken boot cannot spin.
+            if (Date.now() - startedAt > maxDelay)
+                nextDelay = firstDelay;
+            scheduleRestart(how);
+        };
+        started.on("exit", (code, signal) => onGone(`exited (${signal ?? code})`));
+        started.on("error", (err) => onGone(`failed to start (${spawnErrorCode(err)})`));
+    }
+    async function handleAttach(req, res) {
+        const raw = await readBody(req);
+        if (raw === undefined) {
+            refuse(res, 413, "too_large", `the push exceeds ${MAX_PUSH_BYTES} bytes`);
+            return;
+        }
+        let body;
+        try {
+            body = JSON.parse(raw);
+        }
+        catch {
+            refuse(res, 400, "malformed", "the push is not JSON");
+            return;
+        }
+        const verdict = verifyAttachPush(body, options.readSandboxName(), now());
+        if (!verdict.ok) {
+            // JSON-encoded: the reason may quote the pushed queue, untrusted text.
+            log(`[attach] push refused (${verdict.status}): ${JSON.stringify(verdict.reason)}`);
+            refuse(res, verdict.status, verdict.code, verdict.reason);
+            return;
+        }
+        const { push } = verdict;
+        // One sandbox serves one queue for its life. The name binding already
+        // ties a queue to one sandbox; this holds even if two queues' names met.
+        if (attachedQueue !== undefined && attachedQueue !== push.taskQueue) {
+            refuse(res, 409, "other_queue", `this sandbox serves ${attachedQueue}`);
+            return;
+        }
+        const first = attachedQueue === undefined;
+        if (!first) {
+            const refusal = laterPushRefusal(attachedSecrets, push.secrets);
+            if (refusal !== undefined) {
+                log(`[attach] push refused (409 ${refusal.code}): ${JSON.stringify(refusal.reason)}`);
+                refuse(res, 409, refusal.code, refusal.reason);
+                return;
+            }
+        }
+        const env = runnerEnvFor(options.baseEnv, push);
+        if (first) {
+            // The attachment is recorded only once a runner has started, so a push
+            // whose runner cannot start leaves the sandbox free for a corrected one.
+            const started = spawnSafely(env);
+            if (started === undefined) {
+                refuse(res, 500, "runner_start_failed", "the runner could not be started");
+                return;
+            }
+            attachedSecrets = push.secrets;
+            log(`[attach] attached to ${JSON.stringify(push.taskQueue)}; the runner started`);
+            attachedQueue = push.taskQueue;
+            runnerEnv = env;
+            supervise(started);
+        }
+        else {
+            runnerEnv = env;
+            // A runner waiting out its restart delay starts now, with the fresh
+            // token: the push is the driver saying a turn is about to need it.
+            if (restartTimer !== undefined) {
+                clearTimeout(restartTimer);
+                restartTimer = undefined;
+                nextDelay = firstDelay;
+                log("[attach] a push arrived during the restart delay; restarting now");
+                restart();
+            }
+        }
+        reply(res, 200, { taskQueue: push.taskQueue, started: first });
+    }
+    const server = createServer((req, res) => {
+        if (req.url === "/readyz" && req.method === "GET") {
+            reply(res, 200, { ready: true });
+            return;
+        }
+        if (req.url === "/attach") {
+            if (req.method !== "POST") {
+                refuse(res, 405, "method_not_allowed", "POST only");
+                return;
+            }
+            handleAttach(req, res).catch((err) => {
+                log(`[attach] push failed: ${err instanceof Error ? err.message : String(err)}`);
+                if (!res.headersSent)
+                    refuse(res, 500, "unreadable", "the push could not be read");
+            });
+            return;
+        }
+        reply(res, 404, { error: "not found" });
+    });
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(options.port, () => resolve());
+    });
+    const address = server.address();
+    const port = typeof address === "object" && address !== null ? address.port : options.port;
+    return {
+        server,
+        port,
+        attachedQueue: () => attachedQueue,
+        async close() {
+            stopping = true;
+            if (restartTimer)
+                clearTimeout(restartTimer);
+            const running = child;
+            if (running && running.exitCode === null && running.signalCode === null) {
+                await new Promise((resolve) => {
+                    running.once("exit", () => resolve());
+                    running.kill("SIGTERM");
+                });
+            }
+            await new Promise((resolve) => {
+                server.close(() => resolve());
+                server.closeAllConnections();
+            });
+        },
+    };
+}
+//# sourceMappingURL=waiter.js.map

package/dist/attach/waiter.js.map

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

package/dist/bootstrap.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Runner self-bootstrap for embedded runners.
+ *
+ * A cloud embedder's contract should be one endpoint plus one token. From that
+ * the runner needs two things it should not have to know or hold ahead of time:
+ * the Temporal frontend coordinates to poll for work, and (on cloud) a minted
+ * iss=stigmer access token for its Cursor-proxy traffic. This module resolves
+ * both at boot from a single control-plane call:
+ *
+ *   1. Explicit address wins. If TEMPORAL_SERVICE_ADDRESS (or the equivalent
+ *      option) is set, use it verbatim — preserves local dev and any caller that
+ *      already passes coordinates. Note: this branch does NOT call the control
+ *      plane, so no runner token is minted; pinning the address against cloud
+ *      means the runner keeps using its existing proxy token. Production desktop
+ *      does not pin the address, so this is a dev-only edge.
+ *   2. Otherwise discover. With only a token + backend endpoint, ask the control
+ *      plane (getRunnerBootstrapConfig). The token presence is the trigger: a
+ *      desktop runs MODE=local with a token + proxy, and must still discover the
+ *      cloud Temporal it cannot be expected to hardcode. The same response
+ *      carries the minted runner token (when the server mints one).
+ *   3. Otherwise localhost. A tokenless local runner (OSS, no auth) falls back
+ *      to the standard local Temporal.
+ *
+ * Two distinct failure semantics: the Temporal coordinates are load-bearing, so
+ * discovery failure throws — there is no silent localhost fallback once we have
+ * committed to discovery, because in a cloud deployment a wrong address fails
+ * later in a far more confusing way. The runner token is best-effort: a response
+ * that omits it is normal (OSS, or no signing key) and never throws — the runner
+ * just keeps its existing token.
+ */
+import type { RunnerBootstrapConfig } from "./client/stigmer-client.js";
+export interface ResolveTemporalOptions {
+    /** Explicit Temporal address from env/options. When non-empty it always wins. */
+    readonly explicitAddress?: string | null;
+    /** Explicit Temporal namespace, applied alongside an explicit/local address. */
+    readonly explicitNamespace?: string | null;
+    /** Auth token. Its presence (with no explicit address) triggers discovery. */
+    readonly token?: string | null;
+    /** Stigmer backend endpoint the runner authenticates against for discovery. */
+    readonly stigmerEndpoint: string;
+}
+/**
+ * A minimal discovery client seam, so the resolver can be unit-tested without a
+ * live control plane. Defaults to a real {@link StigmerClient}.
+ *
+ * Async because the default factory loads StigmerClient via dynamic import to
+ * keep @connectrpc/connect-node out of the pre-install module graph (see the
+ * note on the omitted static import at the top of this file).
+ */
+export type BootstrapClientFactory = (endpoint: string, token: string) => Promise<{
+    getRunnerBootstrapConfig(): Promise<RunnerBootstrapConfig>;
+}>;
+export declare function resolveRunnerBootstrap(options: ResolveTemporalOptions, clientFactory?: BootstrapClientFactory): Promise<RunnerBootstrapConfig>;
+/** A freshly minted runner proxy token and its remaining lifetime. */
+export interface RefreshedRunnerToken {
+    token: string;
+    expiresInSeconds?: number;
+}
+/**
+ * Re-mint the runner's proxy token from the control plane (best-effort).
+ *
+ * A long-lived embedded runner holds a minted iss=stigmer token with a TTL and
+ * must refresh it before expiry. Unlike {@link resolveRunnerBootstrap}, this:
+ *
+ *   - ignores the Temporal coordinates — they are resolved once at boot and do
+ *     not change for the life of the runner;
+ *   - never throws — a transient failure should trigger a retry, not crash a
+ *     running runner;
+ *   - authenticates with the caller's current control-plane token, which the
+ *     host keeps fresh independently, so re-minting works even after the
+ *     previous proxy token has fully expired (the chicken-and-egg a self-signed
+ *     refresh would hit).
+ *
+ * Returns undefined when there is no token to authenticate with, the server
+ * mints no token, or the call fails — the caller retries.
+ */
+export declare function refreshRunnerAccessToken(options: {
+    token: string | null;
+    stigmerEndpoint: string;
+}, clientFactory?: BootstrapClientFactory): Promise<RefreshedRunnerToken | undefined>;

package/dist/bootstrap.js

@@ -0,0 +1,119 @@
+/**
+ * Runner self-bootstrap for embedded runners.
+ *
+ * A cloud embedder's contract should be one endpoint plus one token. From that
+ * the runner needs two things it should not have to know or hold ahead of time:
+ * the Temporal frontend coordinates to poll for work, and (on cloud) a minted
+ * iss=stigmer access token for its Cursor-proxy traffic. This module resolves
+ * both at boot from a single control-plane call:
+ *
+ *   1. Explicit address wins. If TEMPORAL_SERVICE_ADDRESS (or the equivalent
+ *      option) is set, use it verbatim — preserves local dev and any caller that
+ *      already passes coordinates. Note: this branch does NOT call the control
+ *      plane, so no runner token is minted; pinning the address against cloud
+ *      means the runner keeps using its existing proxy token. Production desktop
+ *      does not pin the address, so this is a dev-only edge.
+ *   2. Otherwise discover. With only a token + backend endpoint, ask the control
+ *      plane (getRunnerBootstrapConfig). The token presence is the trigger: a
+ *      desktop runs MODE=local with a token + proxy, and must still discover the
+ *      cloud Temporal it cannot be expected to hardcode. The same response
+ *      carries the minted runner token (when the server mints one).
+ *   3. Otherwise localhost. A tokenless local runner (OSS, no auth) falls back
+ *      to the standard local Temporal.
+ *
+ * Two distinct failure semantics: the Temporal coordinates are load-bearing, so
+ * discovery failure throws — there is no silent localhost fallback once we have
+ * committed to discovery, because in a cloud deployment a wrong address fails
+ * later in a far more confusing way. The runner token is best-effort: a response
+ * that omits it is normal (OSS, or no signing key) and never throws — the runner
+ * just keeps its existing token.
+ */
+const LOCAL_TEMPORAL_ADDRESS = "localhost:7233";
+const DEFAULT_TEMPORAL_NAMESPACE = "default";
+const defaultClientFactory = async (endpoint, token) => {
+    const { StigmerClient } = await import("./client/stigmer-client.js");
+    return new StigmerClient({ endpoint, token });
+};
+export async function resolveRunnerBootstrap(options, clientFactory = defaultClientFactory) {
+    const explicit = options.explicitAddress?.trim();
+    const namespace = options.explicitNamespace?.trim() || DEFAULT_TEMPORAL_NAMESPACE;
+    if (explicit) {
+        return { temporalAddress: explicit, temporalNamespace: namespace };
+    }
+    const token = options.token?.trim();
+    if (!token) {
+        return {
+            temporalAddress: LOCAL_TEMPORAL_ADDRESS,
+            temporalNamespace: namespace,
+        };
+    }
+    let discovered;
+    try {
+        const client = await clientFactory(options.stigmerEndpoint, token);
+        discovered = await client.getRunnerBootstrapConfig();
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        throw new Error(`Failed to discover Temporal coordinates from ${options.stigmerEndpoint}: ${reason}. ` +
+            "Set TEMPORAL_SERVICE_ADDRESS explicitly, or upgrade the Stigmer server to one that " +
+            "supports runner bootstrap (getRunnerBootstrapConfig).");
+    }
+    if (!discovered.temporalAddress?.trim()) {
+        throw new Error(`Runner bootstrap from ${options.stigmerEndpoint} returned an empty Temporal address. ` +
+            "Set TEMPORAL_SERVICE_ADDRESS explicitly or check the server's runner-bootstrap configuration.");
+    }
+    return {
+        temporalAddress: discovered.temporalAddress.trim(),
+        temporalNamespace: discovered.temporalNamespace?.trim() || DEFAULT_TEMPORAL_NAMESPACE,
+        // Best-effort: pass the minted token through when present. Absence is normal
+        // (OSS / no signing key) and is handled by the runner, not treated as fatal.
+        runnerAccessToken: discovered.runnerAccessToken,
+        runnerAccessTokenExpiresInSeconds: discovered.runnerAccessTokenExpiresInSeconds,
+        // Server-managed payload-encryption keys ride the same best-effort lane:
+        // absent on OSS (env-configured keys) and on cloud servers predating key
+        // management. Note the explicit-address and localhost branches above return
+        // none by construction — key management only exists where discovery does.
+        payloadEncryption: discovered.payloadEncryption,
+    };
+}
+/**
+ * Re-mint the runner's proxy token from the control plane (best-effort).
+ *
+ * A long-lived embedded runner holds a minted iss=stigmer token with a TTL and
+ * must refresh it before expiry. Unlike {@link resolveRunnerBootstrap}, this:
+ *
+ *   - ignores the Temporal coordinates — they are resolved once at boot and do
+ *     not change for the life of the runner;
+ *   - never throws — a transient failure should trigger a retry, not crash a
+ *     running runner;
+ *   - authenticates with the caller's current control-plane token, which the
+ *     host keeps fresh independently, so re-minting works even after the
+ *     previous proxy token has fully expired (the chicken-and-egg a self-signed
+ *     refresh would hit).
+ *
+ * Returns undefined when there is no token to authenticate with, the server
+ * mints no token, or the call fails — the caller retries.
+ */
+export async function refreshRunnerAccessToken(options, clientFactory = defaultClientFactory) {
+    const token = options.token?.trim();
+    if (!token) {
+        return undefined;
+    }
+    try {
+        const client = await clientFactory(options.stigmerEndpoint, token);
+        const config = await client.getRunnerBootstrapConfig();
+        if (!config.runnerAccessToken) {
+            return undefined;
+        }
+        return {
+            token: config.runnerAccessToken,
+            expiresInSeconds: config.runnerAccessTokenExpiresInSeconds,
+        };
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        console.warn(`[runner] Failed to refresh runner access token: ${reason}`);
+        return undefined;
+    }
+}
+//# sourceMappingURL=bootstrap.js.map

package/dist/bootstrap.js.map

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