/** * `gsk sb-box … --session ` — a client-side session → sandbox binding. * * Why: an agent that drives sandboxes from its shell has to carry the * `sbx-…` id from one command to the next itself, and a tool wrapper * (the former opencode `python.ts`) had to keep its own id file to give a * conversation one stateful interpreter. Both are the same bookkeeping, so * it lives here once: a key names the session, the CLI remembers which * sandbox belongs to it, checks the sandbox is still alive before reuse and * creates a new one when it is not. * * Why client-side: the backend tool is stateless per call and shared by * REST users and in-product agents; the binding is a convenience of THIS * process (like `--args-file` or sb-git's `--execute`). Nothing is sent to * the server that it does not already accept — the resolved id goes out as * the ordinary `sandbox_id` parameter. * * Key resolution (first hit wins): `--session `, then the * `GSK_SB_BOX_SESSION` env var, then the session id a host agent exports * (`CLAUDE_CODE_SESSION_ID`). An explicit `--sandbox_id` always wins over * all of them and leaves the binding untouched. * * Bindings live in `/sb-box-sessions.json`, scoped by the API * host so a dev and a prod key never resolve to each other's sandboxes. */ import type { ApiResponse } from '../types.js'; export declare const SESSION_ENV = "GSK_SB_BOX_SESSION"; /** Session ids host agents export into the shells they spawn. */ export declare const HOST_SESSION_ENVS: readonly ["CLAUDE_CODE_SESSION_ID"]; export declare const SESSIONS_FILE = "sb-box-sessions.json"; /** Actions that address a sandbox (the server's "Required for" list). */ export declare const SANDBOX_ACTIONS: Set; /** * Actions that may START a session's sandbox when it has none (or its last * one is gone): the ones that put work on a machine. Reads, lifecycle and * inspection never create — a `kill`/`get`/`read` on an empty session is a * mistake worth surfacing, not a reason to bill a new sandbox. */ export declare const CREATING_ACTIONS: Set; /** * States in which the bound sandbox is reusable. frozen / paused are fine: * the next data-plane call resumes it with its files and interpreter state. */ export declare const ALIVE_STATES: Set; export declare class SessionError extends Error { } export interface SessionKey { key: string; source: 'flag' | typeof SESSION_ENV | (typeof HOST_SESSION_ENVS)[number]; } /** * Pick the session key for this invocation. `explicit` is the `--session` * flag value; the env fallbacks make a host-spawned shell "just work" * without the model ever handling an id. */ export declare function resolveSessionKey(explicit: unknown, env?: NodeJS.ProcessEnv): SessionKey | undefined; export interface SessionBinding { sandbox_id: string; template?: string; updated_at: string; } export declare class SessionStore { private readonly filePath; private readonly scope; constructor(filePath: string, scope: string); private lockDir; /** * Run `fn` while holding this key's lock. `fn` receives `held()`, which * re-reads the lock's owner: a holder about to commit something it must * not do twice (bind a freshly created sandbox) checks it, because an * eviction race can in theory move a live lock aside — see `evict`. */ withLock(key: string, fn: (held: () => boolean) => Promise): Promise; static forConfig(configPath: string, baseUrl: string): SessionStore; private readAll; private writeAll; get(key: string): SessionBinding | undefined; set(key: string, binding: Omit): void; delete(key: string): void; } /** Bindings are per API host: a dev and a prod key must never cross. */ export declare function scopeOf(baseUrl: string): string; /** * `gsk sb-box create` with no --template: the SERVER picks the default — * the `base` alias, resolved in the placement lever's region from the public * catalog (gen-spark#79863). The CLI used to pick "newest ready * `sb-box-base-*`" client-side from the templates list, which ignored the * region and sent dev sandboxes to the validation-only GCP cell as soon as * its catalog build was the newest. Returns undefined = omit `template`. */ export declare function defaultTemplate(): undefined; export type ToolCall = (args: Record) => Promise; export interface BindResult { key: SessionKey; sandbox_id: string; /** true when this invocation created the sandbox */ created: boolean; /** state of the bound sandbox when it was reused */ state?: string; } /** * Resolve the sandbox for a session before the real call: reuse the bound * one if it is alive, otherwise create (for CREATING_ACTIONS) or fail with * a message that says what to do. `args` is mutated: `sandbox_id` is set, * and `template` (a create-only parameter) is consumed when a sandbox had * to be created. */ export declare function bindSession(opts: { key: SessionKey; action: string; args: Record; call: ToolCall; store: SessionStore; log?: (line: string) => void; }): Promise; /** * After the real call: keep the binding in step with explicit lifecycle * actions (`create --session` binds the new sandbox, a successful `kill` * drops it) and echo the binding on the envelope so a caller that never * saw the id learns it once. */ export declare function afterSessionCall(opts: { key: SessionKey; action: string; bind: BindResult | undefined; result: ApiResponse; store: SessionStore; }): void; //# sourceMappingURL=sb-box-session.d.ts.map