@stigmer/runner 0.1.0-dev.20261017020314.g644422724c27

package/dist/runner.js

@@ -0,0 +1,392 @@
+/**
+ * Public factory for the unified Stigmer runner.
+ *
+ * Encapsulates the full boot sequence: harness boot (the Cursor adapter
+ * installs its proxy interceptors there), bootstrap resolution, dynamic
+ * activity imports, Temporal worker creation. Consumers call
+ * {@link createStigmerRunner} with typed options and get back a handle
+ * to start/shutdown the worker.
+ *
+ * OTel tracing and metrics are intentionally excluded — they mutate
+ * global state and should be initialized by the consumer before calling
+ * this factory. The Temporal OTel activity interceptor is still wired
+ * internally when the standard settings export traces (`otel-export.ts`).
+ */
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { homedir, tmpdir } from "node:os";
+import { releasingOnFailure } from "./agent-host/failed-boot.js";
+import { DEFAULT_CURSOR_AGENT_RESOLVE_TIMEOUT_MS, DEFAULT_CURSOR_STREAM_STALL_TIMEOUT_MS, DEFAULT_WORKSPACE_LOCK_TIMEOUT_MS } from "./config.js";
+import { resolveRunnerBootstrap, refreshRunnerAccessToken } from "./bootstrap.js";
+import { createRunnerTokenCoordinator } from "./runner-token-coordinator.js";
+import { assertLlmBackendsPreflight } from "./preflight.js";
+import { captureRunnerSecrets, getRunnerSecret, setRunnerSecret, } from "./shared/runner-credential-store.js";
+import { loadTemporalConnectionConfig } from "@stigmer/temporal-codecs";
+import { markBoot, emitRunnerBootTiming } from "./shared/cold-start-timing.js";
+/**
+ * Wire up self-renewal for a static cloud sandbox's control-plane credential
+ * (see sandbox-token-renewal.ts for the model). The applied token reaches
+ * every consumer through the ONE ref: activity gRPC clients read
+ * {@code tokenRef} per request, the artifact store and the checkpoint saver
+ * read it per request, the per-turn model clients read it at build, per-call
+ * sites (the registry-endpoint headers) resolve it through the runner
+ * credential store (which replaced the process.env.STIGMER_TOKEN channel,
+ * #508), and the two Cursor SDK interceptors read the same ref per request
+ * as {@code Config.proxyTokenRef} — a static runner has no
+ * {@code RunnerTokenCoordinator} minting a separate proxy credential, so its
+ * x-stigmer-auth IS this token and one write here rotates it everywhere.
+ * Nothing holds the value: `Config` carries the ref alone (config.ts header).
+ */
+async function startStaticSandboxTokenRenewal(config, tokenRef) {
+    const { isRenewableSandboxToken, startSandboxTokenRenewal } = await import("./sandbox-token-renewal.js");
+    // Static mode's credential class never changes (it is baked into the pod's
+    // env), so a non-renewable credential — desktop/OSS/local — never starts
+    // the loop at all.
+    if (!isRenewableSandboxToken(tokenRef.current)) {
+        return null;
+    }
+    const { StigmerClient } = await import("./client/stigmer-client.js");
+    const client = new StigmerClient({
+        endpoint: config.stigmerBackendEndpoint,
+        token: null,
+        tokenRef,
+    });
+    return startSandboxTokenRenewal({
+        getToken: () => tokenRef.current,
+        renew: (currentToken) => client.getRunnerScopedToken({ renewal: true }, currentToken),
+        applyToken: (token) => {
+            tokenRef.current = token;
+            setRunnerSecret("STIGMER_TOKEN", token);
+        },
+    });
+}
+/**
+ * Create a Stigmer runner ready to poll a Temporal task queue.
+ *
+ * Handles all internal setup: harness boot, activity registration, and
+ * Temporal worker creation. Returns a handle with
+ * `start()` and `shutdown()` methods.
+ *
+ * @example
+ * ```ts
+ * import { createStigmerRunner } from '@stigmer/runner';
+ *
+ * const runner = await createStigmerRunner({
+ *   taskQueue: 'session:abc-123',
+ *   temporalAddress: 'localhost:7233',
+ *   stigmerEndpoint: 'http://localhost:7234',
+ * });
+ *
+ * process.on('SIGTERM', () => runner.shutdown());
+ * await runner.start();
+ * ```
+ */
+export async function createStigmerRunner(options) {
+    return releasingOnFailure((boot) => buildStigmerRunner(options, boot));
+}
+/** The factory's body; `boot.release` is set once the agent host is up (`agent-host/failed-boot.ts`). */
+async function buildStigmerRunner(options, boot) {
+    validateOptions(options);
+    // Take custody of runner secrets BEFORE anything else can read them from
+    // env — and before any agent code could spawn with them (#508). Runs here
+    // (not only in main.ts) because this factory is a public library boot door
+    // for in-process embedders.
+    captureRunnerSecrets();
+    // The control-plane credential lives in a shared mutable ref (as in manager
+    // mode) so the sandbox-token renewal below can rotate it in-process:
+    // activity clients read the ref per request instead of pinning the boot
+    // token for the pod's whole life. This root owns the writable object; the
+    // config carries it read-only (mapOptionsToConfig binds it as both the
+    // control-plane and the proxy credential — see there).
+    const tokenRef = { current: options.stigmerToken ?? null };
+    // The runner-class credential the bootstrap below may mint (see there); the
+    // ref exists from here so the boot config can carry it.
+    const runnerTokenRef = { current: null };
+    const bootConfig = mapOptionsToConfig(options, tokenRef, runnerTokenRef);
+    assertLlmBackendsPreflight(bootConfig.proxyEndpoint);
+    // Boot the harnesses BEFORE resolving Temporal coordinates. Coordinate
+    // discovery dials the control plane through connect-node, which snapshots
+    // the node:http2 ESM facade on first import; the Cursor adapter's boot
+    // installs the proxy interceptors (the HTTP/2 one patches http2.connect,
+    // which only reaches that facade if it runs first), proves the patch landed,
+    // and only then loads its SDK. Nothing a boot reads depends on the
+    // coordinates, so `bootConfig` carries none yet. The modules imported
+    // here are connect-free by construction (`harness-adapters.ts`,
+    // `harness/registry.ts`, `agent-host/hosting.ts`;
+    // `__tests__/harness-boot-order.test.ts`). The hosted harnesses' engines
+    // run in the agent host, behind their remote adapters (`agent-host/`).
+    const [{ HARNESS_ADAPTERS }, { adaptersOf, bootHarnesses, shutdownHarnesses }, { hostHarnesses }] = await Promise.all([
+        import("./harness-adapters.js"),
+        import("./harness/registry.js"),
+        import("./agent-host/hosting.js"),
+    ]);
+    const hosted = await hostHarnesses(HARNESS_ADAPTERS, bootConfig);
+    const releaseHosted = async () => {
+        try {
+            await shutdownHarnesses(adaptersOf(hosted.rows));
+        }
+        finally {
+            await hosted.close();
+        }
+    };
+    boot.release = releaseHosted;
+    await bootHarnesses(adaptersOf(hosted.rows), bootConfig);
+    markBoot("harnesses_booted");
+    // Resolve Temporal coordinates after the harnesses have booted (discovery
+    // dials the control plane through connect-node). Explicit address wins;
+    // otherwise a token triggers control-plane discovery; otherwise localhost.
+    // Only the worker connection consumes these coordinates — no activity dials
+    // Temporal directly (emit-event, the last one, now routes signals through
+    // the server's SendSignal lane; see oss#517).
+    const coordinates = await resolveRunnerBootstrap({
+        explicitAddress: options.temporalAddress,
+        explicitNamespace: options.temporalNamespace,
+        token: options.stigmerToken,
+        stigmerEndpoint: bootConfig.stigmerBackendEndpoint,
+    });
+    // Adopt the bootstrap-minted embedded_runner credential for gRPC runner-class
+    // calls. The static path historically discarded it ("the
+    // static token is already proxy-valid") — true for the PROXY lane, but the
+    // value fetch is gated on runner-class token_type: a user-token static
+    // runner (conformance harness, CLI daemon with a cloud token) had its
+    // scoped-token exchange refused and could not fetch a run's values. The coordinator owns the mint's TTL
+    // (same module the desktop manager uses — one refresh implementation, not
+    // two); its only sink here is the gRPC runner-credential ref, because the
+    // static host's proxy token is provided by the host and stays untouched.
+    // Servers that mint nothing (explicit-address boots, tokenless OSS, cloud
+    // sandboxes with baked credentials) leave the ref null — byte-identical
+    // behavior to before.
+    const runnerTokenCoordinator = createRunnerTokenCoordinator({
+        applyProxyToken: (token) => {
+            runnerTokenRef.current = token;
+        },
+        reMint: () => refreshRunnerAccessToken({
+            token: tokenRef.current,
+            stigmerEndpoint: bootConfig.stigmerBackendEndpoint,
+        }),
+    });
+    if (coordinates.runnerAccessToken) {
+        runnerTokenCoordinator.adoptMintedToken(coordinates.runnerAccessToken, coordinates.runnerAccessTokenExpiresInSeconds);
+    }
+    const config = {
+        ...bootConfig,
+        temporalAddress: coordinates.temporalAddress,
+        temporalNamespace: coordinates.temporalNamespace,
+    };
+    markBoot("bootstrap_resolved");
+    // Cloud sandbox credential self-renewal (no-op for desktop/OSS/local
+    // credentials — see the helper). Started before the worker so the first
+    // renewal point is scheduled even if the pod boots with a part-used token.
+    const tokenRenewal = await startStaticSandboxTokenRenewal(config, tokenRef);
+    const activities = await createAllActivities(config, hosted.rows);
+    markBoot("activities_imported");
+    console.log(`[runner] Registered activities: ${Object.keys(activities).join(", ")}`);
+    console.log(`[runner] Task queue: ${config.taskQueue} | ` +
+        `Mode: ${config.mode} | ` +
+        `Max concurrency: ${config.maxConcurrentActivities}`);
+    // Surface the resolved artifact store at boot so a path/type misconfiguration
+    // (the #285 class of failure) is visible immediately instead of only when an
+    // attachment or offload read fails minutes into an execution.
+    try {
+        const { loadArtifactStorageConfig } = await import("./shared/artifact-storage.js");
+        const artifactCfg = loadArtifactStorageConfig(config);
+        console.log(`[runner] Artifact store: type=${artifactCfg.type}` +
+            (artifactCfg.type === "local"
+                ? ` | root=${artifactCfg.localPath}`
+                : ` | proxy=${artifactCfg.proxyEndpoint ?? "(unset)"}`));
+    }
+    catch (err) {
+        console.warn(`[runner] Artifact store: could not resolve config for boot log: ${err}`);
+    }
+    const { createPayloadCodecs } = await import("./payload-codecs.js");
+    // Server-managed keys from the bootstrap response apply here too (a CLI
+    // daemon with a cloud token is desktop-class); cloud sandboxes are
+    // unaffected — their env-injected platform key wins inside the loader.
+    const payloadCodecs = await createPayloadCodecs(config, coordinates.payloadEncryption);
+    // Register the queue's shutdown signal BEFORE the worker can poll, so an
+    // activity interrupted by shutdown() below classifies the cancellation as a
+    // worker shutdown, not a user pause (issue #776). Static mode historically
+    // never registered one, leaving CLI daemons with the same misclassification
+    // the desktop manager had.
+    const { registerWorkerShutdownSignal } = await import("./shared/worker-shutdown.js");
+    const shutdownController = registerWorkerShutdownSignal(config.taskQueue);
+    const { startWorker } = await import("./worker.js");
+    const { worker, connection } = await startWorker({ config, activities, payloadCodecs });
+    markBoot("worker_created");
+    return {
+        async start() {
+            console.log("Worker ready, polling for tasks...");
+            // The boot timeline ends here: the worker is about to poll, so the
+            // sandbox can now receive its first activity. The final mark closes the
+            // worker_created → about-to-poll span — without it, total_ms would stop
+            // at worker_created and understate the boot time the warm-pool go/no-go
+            // decision reads.
+            markBoot("worker_polling");
+            emitRunnerBootTiming({ task_queue: config.taskQueue, mode: config.mode });
+            // Released however the worker ended, so a run that fails leaves no
+            // host child holding an embedder's event loop open.
+            try {
+                await worker.run();
+                console.log("Worker stopped");
+            }
+            finally {
+                await releaseAfterDrain({ shutdownHarnesses: releaseHosted, connection });
+            }
+        },
+        shutdown() {
+            tokenRenewal?.stop();
+            runnerTokenCoordinator.stop();
+            // Classification first, drain second: an in-flight activity cancelled
+            // by the drain must observe the signal already aborted (see
+            // shared/worker-shutdown.ts for the ownership contract).
+            shutdownController.abort();
+            worker.shutdown();
+        },
+    };
+}
+function validateOptions(options) {
+    if (!options.taskQueue) {
+        throw new Error("StigmerRunnerOptions.taskQueue is required — specify the Temporal task queue to poll");
+    }
+    if (!options.stigmerEndpoint) {
+        throw new Error("StigmerRunnerOptions.stigmerEndpoint is required — specify the Stigmer server endpoint (e.g. 'http://localhost:7234')");
+    }
+    // temporalAddress is intentionally NOT required: when omitted, the runner
+    // discovers it from the control plane (token-only embedding), falling back to
+    // localhost when no token is present.
+}
+/**
+ * The static runner's teardown once `worker.run()` has resolved, in the
+ * manager's order (runner-manager.ts `shutdown`): harnesses, then the
+ * Temporal connection.
+ *
+ * - Harnesses first: they release what they still hold (the Cursor harness:
+ *   its parked session agents, whose executor leases dispose with the
+ *   process, #215) over their own channels, never the Temporal one.
+ * - The connection last, and only after the drain: the SDK refuses to close
+ *   a connection a worker still holds, and `run()` releases it on its way
+ *   out.
+ *
+ * Each step is logged, never thrown: the drain has already happened and the
+ * process is exiting, so a teardown failure must not mask a clean stop, and
+ * one step failing does not skip the next.
+ */
+export async function releaseAfterDrain(resources, logError = (line) => console.error(line)) {
+    try {
+        await resources.shutdownHarnesses();
+    }
+    catch (err) {
+        logError(`[runner] Harness shutdown failed after the worker drained (continuing): ${errorText(err)}`);
+    }
+    try {
+        await resources.connection.close();
+    }
+    catch (err) {
+        logError(`[runner] Temporal connection close failed after the worker drained (continuing): ${errorText(err)}`);
+    }
+}
+function errorText(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * The runtime `Config` for the static root. The refs are the root's: it
+ * creates them before mapping and writes them on every rotation (the
+ * sandbox-token renewal), so a `Config` never carries a credential by value
+ * (config.ts header). `tokenRef` is bound as BOTH the control-plane and the
+ * proxy credential — a static host provides the proxy token itself and mints
+ * no separate one, so the interceptors read this same ref per request.
+ */
+export function mapOptionsToConfig(options, tokenRef, runnerTokenRef) {
+    const proxyActive = !!options.proxyEndpoint;
+    // Execution location is independent of proxy transport. An explicit
+    // `executionMode` always wins; otherwise fall back to the proxy-derived
+    // default for backward compatibility. Setting `executionMode: "local"` with a
+    // proxy is the desktop case (local-path workspaces + proxied Cursor traffic).
+    const mode = options.executionMode ?? (proxyActive ? "cloud" : "local");
+    return {
+        taskQueue: options.taskQueue,
+        // May be empty here; createStigmerRunner resolves it via
+        // resolveRunnerBootstrap before the worker connects to Temporal.
+        temporalAddress: options.temporalAddress ?? "",
+        temporalNamespace: options.temporalNamespace ?? "default",
+        temporalConnection: options.temporalConnection ?? loadTemporalConnectionConfig(getRunnerSecret),
+        stigmerBackendEndpoint: normalizeEndpoint(options.stigmerEndpoint),
+        stigmerTokenRef: tokenRef,
+        stigmerRunnerTokenRef: runnerTokenRef,
+        proxyTokenRef: tokenRef,
+        // Env-only like the env-loaded path (loadConfig): the bridge and public
+        // endpoints are deployment topology, not per-session state.
+        mcpBridgeEndpoint: process.env.STIGMER_MCP_BRIDGE_ENDPOINT ?? null,
+        mcpPublicEndpoint: process.env.STIGMER_MCP_PUBLIC_ENDPOINT || null,
+        cursorApiKey: proxyActive
+            ? (options.cursorApiKey ?? "proxy-managed")
+            : (options.cursorApiKey ?? ""),
+        workspaceRootDir: options.workspaceRootDir ?? resolveDefaultWorkspaceDir(),
+        mode,
+        proxyEndpoint: options.proxyEndpoint ?? null,
+        maxConcurrentActivities: options.maxConcurrentActivities ?? 5,
+        idleTimeoutSeconds: null,
+        cloudModeEnabled: options.cloudModeEnabled ?? false,
+        checkpointerType: options.checkpointerType
+            ?? (proxyActive ? "http" : "sqlite"),
+        checkpointerProxyEndpoint: options.checkpointerProxyEndpoint
+            ?? options.proxyEndpoint
+            ?? null,
+        artifactProxyEndpoint: options.artifactProxyEndpoint
+            ?? options.proxyEndpoint
+            ?? null,
+        primaryModel: options.primaryModel ?? "gpt-4.1",
+        cursorStreamStallTimeoutMs: options.cursorStreamStallTimeoutMs ?? DEFAULT_CURSOR_STREAM_STALL_TIMEOUT_MS,
+        agentResolveTimeoutMs: options.agentResolveTimeoutMs ?? DEFAULT_CURSOR_AGENT_RESOLVE_TIMEOUT_MS,
+        workspaceLockTimeoutMs: options.workspaceLockTimeoutMs ?? DEFAULT_WORKSPACE_LOCK_TIMEOUT_MS,
+    };
+}
+/**
+ * Dynamically import all activity factories and merge into a single map.
+ *
+ * Dynamic imports, after the harnesses have booted: several of these modules
+ * transitively load `@connectrpc/connect-node` and LangChain, and the Cursor
+ * adapter's boot must have patched `node:http2` before connect-node is first
+ * imported (see createStigmerRunner). The harness rows and the registry were
+ * imported by the factory for the boot, which hands this function the rows it
+ * booted (the hosted harnesses' remote adapters among them); the imports here
+ * hit the module cache.
+ */
+async function createAllActivities(config, harnessRows) {
+    const [{ createHarnessActivities }, { createEnsureThreadActivities }, { createGenerateSessionSubjectActivities }, { createListPluginToolsActivities }, { createAttachSessionActivities },] = await Promise.all([
+        import("./harness/registry.js"),
+        import("./activities/ensure-thread.js"),
+        import("./activities/generate-session-subject.js"),
+        import("./activities/list-plugin-tools.js"),
+        import("./activities/attach-session.js"),
+    ]);
+    return {
+        ...(await createHarnessActivities(harnessRows, config)),
+        ...createEnsureThreadActivities(),
+        ...createGenerateSessionSubjectActivities(config),
+        ...createListPluginToolsActivities(config),
+        ...createAttachSessionActivities(config),
+    };
+}
+function resolveDefaultWorkspaceDir() {
+    try {
+        const dir = join(homedir(), ".stigmer", "workspaces", "runner");
+        mkdirSync(dir, { recursive: true });
+        return dir;
+    }
+    catch {
+        const dir = join(tmpdir(), "stigmer-runner-workspace");
+        mkdirSync(dir, { recursive: true });
+        return dir;
+    }
+}
+function normalizeEndpoint(endpoint) {
+    if (endpoint.startsWith("http://") || endpoint.startsWith("https://")) {
+        return endpoint;
+    }
+    if (endpoint.endsWith(":443")) {
+        return `https://${endpoint}`;
+    }
+    return `http://${endpoint}`;
+}
+//# sourceMappingURL=runner.js.map

package/dist/runner.js.map

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

package/dist/sandbox-token-renewal.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Self-renewal of a cloud sandbox's control-plane credential (STIGMER_TOKEN).
+ *
+ * A sandbox token is minted with a fixed TTL, but the sandbox it serves has no
+ * fixed lifetime: an active conversation extends a session sandbox
+ * indefinitely, past any TTL chosen at provisioning. Before this module, the
+ * only refresh path was the control plane's Secret-rewrite + pod restart —
+ * which the 2026-08-05 incident showed both sacrifices the turn that trips it
+ * (the old pod picks up the work holding the dead env token) and wipes an
+ * ephemeral sandbox's workspace. Renewal decouples credential lifetime from
+ * sandbox lifetime: the runner re-mints in-process before expiry via the
+ * getRunnerScopedToken `renewal` arm, and the server bounds renewability by
+ * the live sandbox record (a reaped sandbox's credential dies with it).
+ *
+ * Relationship to {@link createRunnerTokenCoordinator}
+ * (runner-token-coordinator.ts): the coordinator owns the PROXY credential
+ * (x-stigmer-auth) and re-mints it using the control-plane token; this
+ * module keeps that control-plane token itself fresh, so the two form one
+ * chain with no expiring root. They stay separate modules because their
+ * hosts differ — every proxy-mode runner has a coordinator, but only
+ * in-cluster sandbox runners (static cloud sandboxes and pool members) hold
+ * a renewable credential; the desktop's control-plane token is the user's
+ * own Auth0 token, refreshed by the host app.
+ *
+ * The loop re-reads the CURRENT token every cycle rather than binding to
+ * the boot credential, because the credential's class can change under it:
+ * a pool member boots with a non-renewable pool_sandbox token and swaps to
+ * a renewable session token at claim time (attach-session.ts). A
+ * non-renewable token parks the loop on a slow recheck instead of stopping
+ * it, so the swap is picked up without any coupling to the claim path.
+ */
+export interface SandboxTokenRenewalOptions {
+    /** Reads the credential currently in effect (re-read every cycle; see module doc). */
+    readonly getToken: () => string | null | undefined;
+    /**
+     * Calls the getRunnerScopedToken `renewal` arm authenticated with
+     * {@code currentToken}. Returns undefined when the server minted nothing;
+     * the loop retries rather than crashing the runner.
+     */
+    readonly renew: (currentToken: string) => Promise<{
+        token: string;
+        expiresInSeconds?: number;
+    } | undefined>;
+    /** Applies a freshly minted credential to every sink the host wires (ref, env, interceptors). */
+    readonly applyToken: (token: string) => void;
+    /** Optional structured logger; defaults to console. */
+    readonly log?: Pick<typeof console, "log" | "warn">;
+}
+export interface SandboxTokenRenewal {
+    /** Stop the renewal timer. Idempotent. */
+    stop(): void;
+}
+/**
+ * Whether a token's decoded claims mark it as renewable through the
+ * `renewal` arm. Exported so a static-mode host can decide not to start
+ * the loop at all for a credential whose class can never change.
+ */
+export declare function isRenewableSandboxToken(token: string | null | undefined): boolean;
+/**
+ * Start the renewal loop. The first cycle runs immediately (it only reads
+ * the token and schedules; no network call unless the credential is already
+ * past its renewal point).
+ */
+export declare function startSandboxTokenRenewal(options: SandboxTokenRenewalOptions): SandboxTokenRenewal;

package/dist/sandbox-token-renewal.js

@@ -0,0 +1,168 @@
+/**
+ * Self-renewal of a cloud sandbox's control-plane credential (STIGMER_TOKEN).
+ *
+ * A sandbox token is minted with a fixed TTL, but the sandbox it serves has no
+ * fixed lifetime: an active conversation extends a session sandbox
+ * indefinitely, past any TTL chosen at provisioning. Before this module, the
+ * only refresh path was the control plane's Secret-rewrite + pod restart —
+ * which the 2026-08-05 incident showed both sacrifices the turn that trips it
+ * (the old pod picks up the work holding the dead env token) and wipes an
+ * ephemeral sandbox's workspace. Renewal decouples credential lifetime from
+ * sandbox lifetime: the runner re-mints in-process before expiry via the
+ * getRunnerScopedToken `renewal` arm, and the server bounds renewability by
+ * the live sandbox record (a reaped sandbox's credential dies with it).
+ *
+ * Relationship to {@link createRunnerTokenCoordinator}
+ * (runner-token-coordinator.ts): the coordinator owns the PROXY credential
+ * (x-stigmer-auth) and re-mints it using the control-plane token; this
+ * module keeps that control-plane token itself fresh, so the two form one
+ * chain with no expiring root. They stay separate modules because their
+ * hosts differ — every proxy-mode runner has a coordinator, but only
+ * in-cluster sandbox runners (static cloud sandboxes and pool members) hold
+ * a renewable credential; the desktop's control-plane token is the user's
+ * own Auth0 token, refreshed by the host app.
+ *
+ * The loop re-reads the CURRENT token every cycle rather than binding to
+ * the boot credential, because the credential's class can change under it:
+ * a pool member boots with a non-renewable pool_sandbox token and swaps to
+ * a renewable session token at claim time (attach-session.ts). A
+ * non-renewable token parks the loop on a slow recheck instead of stopping
+ * it, so the swap is picked up without any coupling to the claim path.
+ */
+/**
+ * Renew once the token has lived this fraction of its issued lifetime
+ * (anchored on iat/exp, the coordinator's 0.8 convention). Anchoring on the
+ * ISSUED lifetime matters: a fraction of the *remaining* lifetime re-arms at
+ * 80% of an ever-shrinking remainder and never reaches the renewal point.
+ */
+const RENEW_AT_LIFETIME_FRACTION = 0.8;
+/**
+ * Fallback safety margin before expiry for a token without an iat claim:
+ * renew this early, leaving room for two retry cycles.
+ */
+const FALLBACK_RENEW_MARGIN_MS = 10 * 60_000;
+/** Retry delay after a failed renewal — short enough to recover well before expiry. */
+const RETRY_DELAY_MS = 60_000;
+/** Recheck cadence while the current token is not a renewable class (pre-claim pool member). */
+const RECHECK_DELAY_MS = 60_000;
+/** Floor for any scheduled delay so a malformed expiry cannot spin a hot loop. */
+const MIN_DELAY_MS = 5_000;
+/** The token_type claims the renewal arm accepts (mirrors the server's gate). */
+const RENEWABLE_TOKEN_TYPES = new Set(["sandbox"]);
+/**
+ * Whether a token's decoded claims mark it as renewable through the
+ * `renewal` arm. Exported so a static-mode host can decide not to start
+ * the loop at all for a credential whose class can never change.
+ */
+export function isRenewableSandboxToken(token) {
+    const claims = decodeClaims(token);
+    return claims !== null
+        && RENEWABLE_TOKEN_TYPES.has(claims.tokenType ?? "")
+        && claims.expMs !== null;
+}
+/**
+ * Start the renewal loop. The first cycle runs immediately (it only reads
+ * the token and schedules; no network call unless the credential is already
+ * past its renewal point).
+ */
+export function startSandboxTokenRenewal(options) {
+    const log = options.log ?? console;
+    let stopped = false;
+    let timer = null;
+    const schedule = (delayMs) => {
+        if (stopped) {
+            return;
+        }
+        timer = setTimeout(() => {
+            void cycle();
+        }, Math.max(MIN_DELAY_MS, delayMs));
+        // Never keep the process alive solely for a token renewal.
+        timer.unref?.();
+    };
+    const cycle = async () => {
+        if (stopped) {
+            return;
+        }
+        const token = options.getToken() ?? null;
+        const claims = decodeClaims(token);
+        if (token === null || claims === null
+            || !RENEWABLE_TOKEN_TYPES.has(claims.tokenType ?? "")) {
+            // Not (yet) a renewable credential — a pre-claim pool member, or a
+            // credential class this loop does not own. Park and look again.
+            schedule(RECHECK_DELAY_MS);
+            return;
+        }
+        if (claims.expMs === null) {
+            // A renewable-class token without an expiry is a mint-side anomaly;
+            // renewing "before expiry" is undefined, so park rather than spin.
+            log.warn("[sandbox-token-renewal] Credential carries no exp claim; parking");
+            schedule(RECHECK_DELAY_MS);
+            return;
+        }
+        const renewAtMs = claims.iatMs !== null
+            ? claims.iatMs + (claims.expMs - claims.iatMs) * RENEW_AT_LIFETIME_FRACTION
+            : claims.expMs - FALLBACK_RENEW_MARGIN_MS;
+        const delayMs = renewAtMs - Date.now();
+        if (delayMs > MIN_DELAY_MS) {
+            schedule(delayMs);
+            return;
+        }
+        // At or past the renewal point (possibly past expiry after a long pod
+        // pause — the attempt is still correct: the server decides).
+        try {
+            const renewed = await options.renew(token);
+            if (renewed) {
+                options.applyToken(renewed.token);
+                log.log("[sandbox-token-renewal] Sandbox credential renewed");
+                // Recompute from the fresh token (its own exp is authoritative).
+                schedule(MIN_DELAY_MS);
+            }
+            else {
+                log.warn("[sandbox-token-renewal] Server minted no renewal; will retry");
+                schedule(RETRY_DELAY_MS);
+            }
+        }
+        catch (err) {
+            log.warn("[sandbox-token-renewal] Renewal failed; will retry: " +
+                `${err instanceof Error ? err.message : err}`);
+            schedule(RETRY_DELAY_MS);
+        }
+    };
+    void cycle();
+    return {
+        stop() {
+            stopped = true;
+            if (timer) {
+                clearTimeout(timer);
+                timer = null;
+            }
+        },
+    };
+}
+/**
+ * Decode the claims this module reads (token_type, iat, exp) from an
+ * unverified JWT. Decode-only on purpose: this is the runner's OWN
+ * credential, minted by the server it will present it back to —
+ * verification happens there.
+ */
+function decodeClaims(token) {
+    if (!token) {
+        return null;
+    }
+    const parts = token.split(".");
+    if (parts.length !== 3) {
+        return null;
+    }
+    try {
+        const payload = JSON.parse(Buffer.from(parts[1], "base64url").toString("utf-8"));
+        return {
+            tokenType: payload.token_type,
+            iatMs: typeof payload.iat === "number" ? payload.iat * 1000 : null,
+            expMs: typeof payload.exp === "number" ? payload.exp * 1000 : null,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=sandbox-token-renewal.js.map

package/dist/sandbox-token-renewal.js.map

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