@huaweidevtools/aishell-dsh-e2b 0.0.0-stage → 0.0.1-beta.3

package/lib/types/client.d.ts

@@ -0,0 +1,124 @@
+/**
+ * The connection to the sandbox gateway.
+ *
+ * One `Sandbox` handle is built per sandbox id and reused, because the SDK's
+ * instance holds the resolved endpoints and per-sandbox tokens that the create
+ * response supplied. Rebuilding one per call would mean either reconnecting
+ * (an extra control-plane round trip) or, worse, constructing a handle from
+ * just an id — which works but silently drops the tokens the sandbox was
+ * actually issued, turning an authentication problem into "port is not open".
+ *
+ * ## What the SDK is configured with
+ *
+ * `domain` alone. The SDK composes `https://api.<domain>` for the control
+ * plane and `https://<port>-<sandboxId>.<domain>` for the data plane, and
+ * reads the key from `apiKey`. That is the whole configuration, which is the
+ * point of the gateway: a stock E2B client reaches it with two settings and no
+ * patched code.
+ *
+ * @module @huaweidevtools/aishell-dsh-e2b/client
+ */
+import { Sandbox } from 'e2b';
+import type { SandboxKeySource } from './sandbox-key.ts';
+/** How the connection is parameterised; every field is read per call. */
+export interface SandboxClientOptions {
+    /** The gateway's domain, e.g. `aishell.openbuildlab.com`. */
+    readonly resolveDomain: () => string;
+    /** The key source, which caches and refreshes the API key. */
+    readonly keys: SandboxKeySource;
+    /** Per-request timeout for SDK control-plane calls. */
+    readonly resolveRequestTimeoutMs: () => number;
+}
+/** Builds and caches SDK handles, one per sandbox id. */
+export declare class SandboxClient {
+    private readonly options;
+    /** Sandbox id → the live handle for it. */
+    private readonly handles;
+    constructor(options: SandboxClientOptions);
+    /**
+     * The live handle for one sandbox.
+     *
+     * @param sandboxId - the sandbox to address.
+     * @returns the cached handle, or a newly connected one.
+     */
+    handle(sandboxId: string): Promise<Sandbox>;
+    /**
+     * Create a sandbox and cache its handle.
+     *
+     * @param template - the template name or id; the SDK's own default when omitted.
+     * @param options - create options forwarded to the SDK.
+     * @returns the created sandbox handle.
+     */
+    create(template: string | undefined, options: {
+        readonly timeoutMs?: number;
+        readonly envs?: Record<string, string>;
+        readonly metadata?: Record<string, string>;
+        readonly signal?: AbortSignal;
+    }): Promise<Sandbox>;
+    /**
+     * Find the sandboxes carrying one metadata pair.
+     *
+     * The SDK encodes the pair into the `metadata` query parameter and the
+     * gateway forwards it to the upstream unchanged, so this is the mechanism a
+     * restarted process uses to rediscover the sandbox a conversation was
+     * working in.
+     *
+     * The search follows the pagination cursor. A single page would be enough
+     * for the common case, but not for a busy account: the gateway pages at 100
+     * and reports more with a cursor, and a conversation's own sandbox is not
+     * ordered ahead of the others — so on the day an account holds more than a
+     * page, the one sandbox the caller is looking for is as likely as any to be
+     * on a later page, and a single-page search would report "none".
+     *
+     * @param metadata - the pair to match; a sandbox must carry all of it.
+     * @param signal - caller cancellation.
+     * @returns one row per matching sandbox.
+     */
+    findByMetadata(metadata: Record<string, string>, signal: AbortSignal | undefined): Promise<Array<{
+        sandboxId: string;
+        state: string;
+    }>>;
+    /**
+     * List the sandboxes this account currently has.
+     *
+     * Follows the pagination cursor, for the same reason the metadata search
+     * does: the gateway pages at 100, and a caller asking what it has should not
+     * be told "these are all of them" when they are the first hundred.
+     *
+     * @param signal - caller cancellation.
+     * @returns one row per sandbox, in the shape the tool renders.
+     */
+    list(signal: AbortSignal | undefined): Promise<Array<{
+        sandboxId: string;
+        templateId: string;
+        state: string;
+        startedAt: string;
+        endAt: string;
+    }>>;
+    /**
+     * Drop a handle for a sandbox that no longer exists.
+     *
+     * Called after a kill, so a later call against the same id re-resolves
+     * rather than reusing an endpoint the gateway has already torn down.
+     *
+     * @param sandboxId - the sandbox whose handle to drop.
+     */
+    forget(sandboxId: string): void;
+    /** Connect to an existing sandbox. */
+    private connect;
+    /**
+     * Run one SDK call, retrying once against a freshly fetched key when the
+     * gateway rejects the one in hand.
+     *
+     * The key is handed to the callback rather than captured by it. A callback
+     * that closed over the first key would "retry" by presenting that same
+     * rejected key again — a loop that looks like a refresh and is not one.
+     *
+     * The retry is deliberately narrow: only an authentication failure clears
+     * the cache, and only once. A key that fails for any other reason — a
+     * sandbox that does not exist, a rate limit — is not evidence about the key,
+     * and refreshing on it would rotate the tenant for no reason.
+     */
+    private runWithKeyRefresh;
+}
+//# sourceMappingURL=client.d.ts.map

package/lib/types/credentials.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Reading the operator's Huawei Cloud credentials for control-plane requests.
+ *
+ * The read is delegated to `credentials-store/accounts`, which is now the one
+ * place the account names and the pairing rule live. Every plugin in this set
+ * that signs with the same key pair goes through it — this module, the LLM
+ * adapter, the credential form's Host route and the ops tools — so they cannot
+ * disagree about which keyring entries are the credentials or about what
+ * "half a pair" means.
+ *
+ * It used to say here that the literals were re-declared because
+ * `aishell-credentials` kept them unexported and the other packages each had
+ * their own copy. That was an accurate description of a real hazard, not a
+ * reason to keep it: a divergence in these names would not fail a build, it
+ * would surface as one plugin working and another reporting "not
+ * authenticated" on a machine where the operator had stored exactly one pair.
+ *
+ * @module @huaweidevtools/aishell-dsh-e2b/credentials
+ */
+import { type CredentialsStore } from '@huaweidevtools/aishell-dsh-credentials-store';
+import type { SignCredentials } from '@huaweidevtools/aishell-dsh-credentials-store/signer';
+/**
+ * Open a credential store.
+ *
+ * Takes no options: the service name is fixed in the store package, because a
+ * per-plugin choice of namespace is how a writer and a reader end up looking at
+ * different stores.
+ */
+export declare function openCredentialStore(): CredentialsStore;
+/**
+ * Read the current credentials.
+ *
+ * AK and SK are read as a pair: half a pair reads as no credentials rather
+ * than an error, so a partially-configured machine gets the "authenticate
+ * first" message instead of a signing failure with no remedy. The
+ * SecurityToken is optional and is omitted from the object entirely when
+ * absent — an empty string would sign as a third header the gateway then
+ * rejects.
+ *
+ * Called per request, never captured: that is what makes a credential saved
+ * from the credential form apply to the next call.
+ *
+ * @param store - the credential store to read.
+ * @returns the credentials, or `undefined` when the pair is incomplete.
+ */
+export declare function readCredentials(store: CredentialsStore): SignCredentials | undefined;
+//# sourceMappingURL=credentials.d.ts.map

package/lib/types/errors.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Turning SDK failures into messages the model can act on.
+ *
+ * Two properties decide the shape here.
+ *
+ * **A non-zero exit is not an error.** The SDK's foreground `commands.run`
+ * rejects with `CommandExitError` when a command exits non-zero, carrying the
+ * exit code and both streams. Reporting that as a tool failure tells the model
+ * "the tool broke" when the truth is "the command ran and returned 1" — which
+ * for a build, a test run, or a `grep` with no match is the ordinary outcome.
+ * Callers convert it to a normal result instead; see `tools.ts`.
+ *
+ * **The error hierarchy does not share a root.** `AuthenticationError`,
+ * `BuildError` and `VolumeError` do not extend `SandboxError`, so matching on
+ * `SandboxError` alone would let exactly the failures with remedies fall
+ * through to a generic message. Matching is therefore by constructor name,
+ * which is stable across the SDK's own re-bundling and needs no import of a
+ * class the package may rename.
+ *
+ * @module @huaweidevtools/aishell-dsh-e2b/errors
+ */
+/** A failure whose text is already the message the model should see. */
+export declare class SandboxToolError extends Error {
+    constructor(message: string);
+}
+/**
+ * Render one thrown value as the message a tool should fail with.
+ *
+ * @param error - whatever was thrown.
+ * @param context - what the call was doing, prefixed for orientation.
+ * @returns the message to surface.
+ */
+export declare function describeSandboxError(error: unknown, context: string): string;
+/** The constructor name of a thrown value, or `''` for a non-object. */
+export declare function errorName(error: unknown): string;
+/**
+ * Whether a thrown value is a command that ran and exited non-zero.
+ *
+ * Kept separate from {@link describeSandboxError} because it is not a failure:
+ * see the module comment.
+ */
+export declare function isCommandExitError(error: unknown): error is {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+};
+//# sourceMappingURL=errors.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,128 @@
+/**
+ * The E2B sandbox plugin: a second, disposable execution tier for DSH.
+ *
+ * ## What problem this solves
+ *
+ * Every deployment request currently reaches the same path — the Huawei Cloud
+ * operations server, provisioning real resources with real cost, real
+ * credentials, and real cleanup obligations. A large fraction of requests do
+ * not need that: a static page, a small service, something to look at once.
+ * Those need a place to run and an address to open, and nothing that outlives
+ * the task.
+ *
+ * This plugin adds that tier. The model chooses between them, which is why it
+ * also contributes a prompt section saying when each is appropriate: tools
+ * alone would leave the choice to guesswork.
+ *
+ * ## What it is not
+ *
+ * It does not replace the harness's execution world. The official
+ * `@deepseek-ai/dsh-e2b` package does that — it swaps `ctx.fs` and
+ * `ctx.subprocess` so every file and command the agent touches runs remotely.
+ * This plugin instead adds *tools*, so the agent keeps working locally and
+ * reaches a sandbox only when it decides to. The two can be mounted together;
+ * only the names look alike.
+ *
+ * ## How it reaches the service
+ *
+ * The key comes from the AI Shell provisioning service, signed with the
+ * operator's stored Huawei Cloud credentials; the sandbox protocol itself is
+ * spoken by the official `e2b` client library, pointed at the gateway's domain.
+ * See `sandbox-key.ts` and `client.ts`.
+ *
+ * @module @huaweidevtools/aishell-dsh-e2b
+ */
+import type { Context, Volatile } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+/** Position of the tier guidance in the assembled prompt. */
+export declare const SANDBOX_PROMPT_ORDER = 110;
+/** Name this contribution registers under; unique across the assembled prompt. */
+export declare const SANDBOX_SECTION_NAME = "aishell:e2b";
+/**
+ * What the model reads about which tier to use.
+ *
+ * This is the plugin's reason for existing. Without it the model has a set of
+ * sandbox tools and no basis for preferring them over provisioning real
+ * resources — or for preferring those over a sandbox.
+ *
+ * ## Why the split is stated by use and by scale
+ *
+ * An earlier version drew the line at lifecycle: "does the result need to
+ * outlive the task?" That is the property that actually decides the tier, but
+ * it is one the model has to *infer* about work that has not been described in
+ * those terms yet. "A web page or a small demo" versus "a production system" is
+ * a distinction the user can answer directly, and it maps onto the lifecycle
+ * question without asking the model to guess at it.
+ *
+ * ## Why it says to ask
+ *
+ * A tie-break the model performs silently is a decision the user never sees
+ * until the bill or the outage. When the request does not make the tier
+ * obvious, the model asks — and says what the choice costs, because "sandbox vs
+ * Terraform" means nothing to someone who has not met either.
+ *
+ * The distinction is stated in consequences, not mechanism: throwaway and free
+ * to discard, versus real resources that bill and are meant to keep running.
+ *
+ * ## What it does not say
+ *
+ * It does not describe the Terraform workflow. That belongs to the plugin that
+ * owns those tools, which also states the approvals each step needs — and the
+ * two sections land far apart in the assembled prompt, so repeating it here
+ * would risk two instructions drifting out of step.
+ */
+export declare const SANDBOX_GUIDANCE = "A sandbox is a disposable Linux environment: it runs for a bounded time, then is deleted along with everything in it.\n\nUse the sandbox tools (aishell__sandbox_*) when the ask is a web page or a simple demo-scale web app \u2014 something to look at, or to try out, that does not need to keep existing.\n\nDeploy a production system instead, with the Terraform tools (aishell__terraform_* and their neighbours), when the result is real infrastructure: it will cost money, it should keep running, and it will be operated.\n\nIf the request does not make clear which of these it is, ask the user before choosing. Say what the difference amounts to for them: a sandbox is throwaway and costs nothing to discard, while Terraform provisions real resources that are billed and meant to keep running. Follow what they pick.\n\nA sandbox is often the right place to work something out before committing real resources to it.\n\nThis conversation works in at most one sandbox at a time. Create it with aishell__sandbox_create before the tools that use it, and choose its lifetime there \u2014 the value should match what the work needs, since the sandbox and its contents are deleted when it expires.";
+/** Plugin config. */
+export interface Config {
+    /** Base URL of the sandbox key provisioning service. */
+    readonly apiBaseUrl: Volatile<string>;
+    /** The sandbox gateway's domain, e.g. `aishell.openbuildlab.com`. */
+    readonly domain: Volatile<string>;
+    /** Per-request timeout for the key fetch and for SDK control-plane calls. */
+    readonly requestTimeoutMs: Volatile<number>;
+}
+/**
+ * Settings schema for this entry.
+ *
+ * Both URLs are Volatile: they are deployment facts that differ between a
+ * staging and a production profile, and a change should apply to the next call
+ * rather than requiring a restart.
+ */
+export declare const Config: z<Schemastery.ObjectS<NoInfer<{
+    apiBaseUrl: z<string, string, "volatile-defined">;
+    domain: z<string, string, "volatile-defined">;
+    requestTimeoutMs: z<number, number, "volatile-defined">;
+}>>, Schemastery.ObjectT<NoInfer<{
+    apiBaseUrl: z<string, string, "volatile-defined">;
+    domain: z<string, string, "volatile-defined">;
+    requestTimeoutMs: z<number, number, "volatile-defined">;
+}>>, "plain">;
+export declare const name = "aishell-e2b";
+/**
+ * Required services: the tool registry alone.
+ *
+ * The filesystem and the system prompt are both optional and taken through
+ * `ctx.inject` / `ctx.get` — a deployment without a filesystem loses one
+ * tool's destination, and one without a system prompt loses the guidance
+ * section, neither of which should stop the sandbox tools from registering.
+ */
+export declare const inject: string[];
+export declare function apply(ctx: Context, config: Config): void;
+declare module '@deepseek-ai/cordis' {
+    interface Events {
+        /**
+         * The stored Huawei Cloud credentials changed — a verified save, or a
+         * clear. Emitted by `aishell-credentials`, which owns the credential form
+         * and the store it writes.
+         *
+         * Declared here as well as on the emitting side because the two packages
+         * share no import: this is the whole interface between them. A listener
+         * reads the store itself; the event carries no value, so a secret can
+         * never ride on it.
+         *
+         * @mode on
+         */
+        'aishell/credentials-updated'(): void;
+    }
+}
+//# sourceMappingURL=index.d.ts.map

package/lib/types/sandbox-key.d.ts

@@ -0,0 +1,178 @@
+/**
+ * The E2B API key this plugin presents to the sandbox gateway.
+ *
+ * ## The lifecycle
+ *
+ * The key is a **stored credential**, not process state:
+ *
+ *   1. Read the `aishell_e2b` section of the `aishell-credential` bundle.
+ *   2. Not there, or past its expiry → `POST /e2b/keys` and store the result.
+ *   3. Either way, present the stored key as `X-API-KEY`.
+ *
+ * Persisting it is what makes a restart cheap and, more importantly, what
+ * keeps the key stable. The key *is* the tenant: the gateway derives a caller
+ * identity from the presented key and scopes every sandbox record to it, so a
+ * key re-created on every start would orphan every sandbox made before it —
+ * the model would see "no such sandbox" and never learn why.
+ *
+ * ## A key with no expiry
+ *
+ * A key issued with no expiry (`ttl_seconds: 0`) is normalised to
+ * `9999-12-31`, so the expiry check stays one comparison instead of two
+ * shapes. An `expires_at` that is present but cannot be parsed is treated the
+ * same way: a malformed timestamp is not evidence the key stopped working, and
+ * treating it as expired would re-create a key on every call — the one
+ * behaviour that guarantees orphaning sandboxes. The 401 fallback below still
+ * catches a key that really has stopped working.
+ *
+ * ## Why the call is signed
+ *
+ * Requesting a key authenticates with the operator's Huawei Cloud AK/SK — the
+ * same pair `aishell-llm` signs gateway requests with — so the service can tell
+ * whose key to issue.
+ *
+ * ## Why the key is bound to the AK that minted it
+ *
+ * A stored key outlives the credentials that created it. Clearing or replacing
+ * the AK/SK in the credential form therefore used to leave the old key — and so
+ * the old tenant, with all its sandboxes — alive and usable, which contradicts
+ * what clearing credentials is supposed to mean. A key with no expiry made that
+ * permanent rather than temporary.
+ *
+ * So the key records a fingerprint of the AK that minted it, and {@link get}
+ * discards a stored key whose fingerprint no longer matches the stored
+ * credentials. Three consequences are deliberate:
+ *
+ *   - **No credentials at all also invalidates it.** Clearing them is the
+ *     clearest statement that nothing this plugin was granted may still be used.
+ *   - **The same AK/SK re-entered does not rotate the key.** A fingerprint
+ *     answers "which identity minted this", not "when was it written"; someone
+ *     re-saving the same pair has changed nothing, and throwing their running
+ *     sandboxes away for it would be gratuitous.
+ *   - **No listener is needed.** The check happens on the read path, so it also
+ *     catches a store changed outside the credential form, or while this plugin
+ *     was not mounted. An event listener would only see the case where this
+ *     plugin happened to be running.
+ *
+ * A key stored by an older build carries no fingerprint. It is treated as
+ * matching (see {@link matchesFingerprint}) rather than re-created: rotating it
+ * would orphan every sandbox made before this build, and the 401 fallback still
+ * covers a key that has genuinely stopped working.
+ *
+ * @module @huaweidevtools/aishell-dsh-e2b/sandbox-key
+ */
+import type { CredentialsStore } from '@huaweidevtools/aishell-dsh-credentials-store';
+import { type E2BSection } from '@huaweidevtools/aishell-dsh-credentials-store/accounts';
+import { type SignCredentials } from '@huaweidevtools/aishell-dsh-credentials-store/signer';
+/** Path of the key endpoint: POST creates, GET lists. */
+export declare const KEYS_PATH = "/e2b/keys";
+/** An error the model can act on, carrying the endpoint's own message. */
+export declare class SandboxKeyError extends Error {
+    constructor(message: string);
+}
+/** Reads the operator's credentials, or `undefined` when the pair is incomplete. */
+export type CredentialsReader = () => SignCredentials | undefined;
+/** Everything the key source needs; injected so tests drive it without a network. */
+export interface SandboxKeyOptions {
+    /** Absolute base URL of the provisioning service, no trailing slash. */
+    readonly baseUrl: string;
+    /** Reads the signing credentials per attempt. */
+    readonly readCredentials: CredentialsReader;
+    /** The store holding the `aishell-credential` bundle. */
+    readonly store: CredentialsStore;
+    /** Fetch implementation; defaults to the global. */
+    readonly fetchImpl?: typeof fetch;
+    /** Request timeout in milliseconds. */
+    readonly timeoutMs: number;
+}
+/** One key as the store holds it. */
+export interface StoredKey {
+    /** The secret presented as `X-API-KEY`. */
+    readonly key: string;
+    /** When it stops working, ISO 8601; {@link FOREVER_EXPIRY} for no expiry. */
+    readonly expiresAt: string;
+    /**
+     * {@link fingerprint} of the AK that minted this key, or `undefined` for a
+     * key stored before fingerprints existed. See the module comment.
+     */
+    readonly akFingerprint?: string;
+}
+/**
+ * Whether a stored key may still be used for the credentials in hand.
+ *
+ * - No credentials → no, whatever the key says: nothing granted under a
+ *   credential set that has since been cleared may still be presented.
+ * - No fingerprint on the key (an older build) → yes. Rotating it would orphan
+ *   every sandbox made before this build, and that is worse than the gap it
+ *   closes; the 401 fallback still catches a dead key.
+ * - Otherwise → the fingerprint must equal the current AK's.
+ *
+ * @param stored - the key read from the store.
+ * @param credentials - the credentials in hand, or `undefined` when cleared.
+ * @returns `true` when the key belongs to the current credentials.
+ */
+export declare function matchesFingerprint(stored: StoredKey, credentials: SignCredentials | undefined): boolean;
+/**
+ * Convert the stored bundle section into this module's shape.
+ *
+ * Returns `undefined` when there is no usable key: a corrupt section should
+ * lead to a new key, not to a half-parsed value presented to the gateway.
+ *
+ * The section is decoded by the shared store module, so this function only
+ * renames fields — it never parses JSON.
+ *
+ * @param section - the e2b section read from the store.
+ * @returns the key, or `undefined` when there is none.
+ */
+export declare function fromStoredSection(section: E2BSection | undefined): StoredKey | undefined;
+/**
+ * Whether a stored key is past its expiry.
+ *
+ * @param key - the stored key.
+ * @param now - the instant to compare against.
+ * @returns `true` when the key should be replaced.
+ */
+export declare function isExpired(key: StoredKey, now: number): boolean;
+/** The stored form of one key, as the bundle keeps it. */
+export declare function toStoredSection(key: StoredKey): E2BSection;
+/** One key, read from the store and replaced when it expires or is refused. */
+export declare class SandboxKeySource {
+    private readonly options;
+    private readonly fetchImpl;
+    /** The key in hand, or `undefined` before the first read. */
+    private current;
+    /** The in-flight create, so concurrent callers share one request. */
+    private pending;
+    constructor(options: SandboxKeyOptions);
+    /**
+     * Return a usable API key.
+     *
+     * A key is used only while it is unexpired **and** still belongs to the
+     * credentials in hand — see the module comment on why the second check
+     * exists and why a mismatch does not delete the stored entry.
+     *
+     * @param signal - caller cancellation, forwarded to the fetch.
+     * @returns the key to present as `X-API-KEY`.
+     * @throws {SandboxKeyError} when no credentials are stored, so nothing can
+     *   be created to replace a key the current credentials do not own.
+     */
+    get(signal: AbortSignal | undefined): Promise<string>;
+    /**
+     * Forget the key, so the next {@link get} creates a new one.
+     *
+     * Called when the gateway refuses the key as unauthenticated — the one
+     * signal that it has stopped working earlier than its expiry said. The
+     * replacement is a different key, and therefore a different tenant: sandboxes
+     * created under the old one stop being reachable through this plugin.
+     */
+    invalidate(): void;
+    /**
+     * Create a key, store it, and return it.
+     *
+     * @param credentials - the pair to sign with; already read by {@link get},
+     *   so the fingerprint recorded on the key is the one it was minted under.
+     * @param signal - caller cancellation, forwarded to the fetch.
+     */
+    private createKey;
+}
+//# sourceMappingURL=sandbox-key.d.ts.map

package/lib/types/sandbox-registry.d.ts

@@ -0,0 +1,114 @@
+/**
+ * The sandbox a conversation works in.
+ *
+ * One conversation, one sandbox. That is the whole model: there is no
+ * "which sandbox did you mean" question for the tools to ask, because there is
+ * only ever one answer, and no `sandboxId` parameter for the model to get
+ * wrong. The tools act on *the* sandbox, and creating one is the explicit act
+ * that binds it to the conversation.
+ *
+ * ## Why the binding is created explicitly, never lazily
+ *
+ * A tool that quietly created a sandbox on first use would have to choose the
+ * template and the lifetime itself, and those are exactly the two facts the
+ * operator should be deciding — a preview page wants a different lifetime from
+ * a debugging session, and that choice is the reason the create tool takes
+ * parameters at all. A lazy create would move that decision into the plugin
+ * and out of the conversation, where nobody can see it or correct it.
+ *
+ * So a tool with no sandbox bound fails, and names `aishell__sandbox_create` as the way
+ * forward. The failure is cheap and legible; a silently invented sandbox is
+ * neither.
+ *
+ * ## Why the binding survives a restart
+ *
+ * The mapping cannot live in memory alone. A plugin restart — a reload, a
+ * crash, a profile edit — would otherwise orphan a running sandbox: the model
+ * would find no binding, create a second sandbox, and the first would keep
+ * billing until its lifetime expired, with nothing in the conversation
+ * accounting for it.
+ *
+ * So the sandbox carries its conversation in its own `metadata` at creation,
+ * and the registry rebuilds the binding by querying for it. The gateway
+ * forwards `metadata` filters to the upstream unchanged, and
+ * `Sandbox.list({ query: { metadata } })` is ordinary SDK surface, so the
+ * recovery needs nothing from either service.
+ *
+ * A recovered binding is refused if the sandbox is not running. A paused
+ * sandbox is not adopted: connecting to it would resume it and silently
+ * restart its clock, which is a billing decision nobody asked for.
+ *
+ * @module @huaweidevtools/aishell-dsh-e2b/sandbox-registry
+ */
+/** The metadata key a sandbox carries its owning conversation under. */
+export declare const SESSION_METADATA_KEY = "aishell-session";
+/** One sandbox the registry knows about. */
+export interface BoundSandbox {
+    /** The sandbox id. */
+    readonly sandboxId: string;
+    /** Whether the gateway reports it as running. */
+    readonly state: string;
+}
+/** Lists the sandboxes carrying one metadata pair. */
+export type SandboxFinder = (metadata: Record<string, string>, signal: AbortSignal | undefined) => Promise<ReadonlyArray<BoundSandbox>>;
+/** In-memory bindings plus the lookup used to rebuild them. */
+export declare class SandboxRegistry {
+    /** Session id → the sandbox bound to it. */
+    private readonly bySession;
+    /** The metadata lookup, injected so tests need no gateway. */
+    private readonly find;
+    constructor(find: SandboxFinder);
+    /**
+     * Bind a sandbox to its conversation.
+     *
+     * @param sessionId - the owning conversation, or `undefined` for a call that
+     *   ran outside one. Such a call is recorded nowhere: without a conversation
+     *   to key on, there would be nothing to bind later calls to.
+     * @param sandboxId - the sandbox to bind.
+     */
+    bind(sessionId: string | undefined, sandboxId: string): void;
+    /**
+     * The sandbox this conversation is bound to, recovering the binding if this
+     * process has not seen one.
+     *
+     * @param sessionId - the calling conversation.
+     * @param signal - caller cancellation, forwarded to the lookup.
+     * @returns the sandbox id, or `undefined` when the conversation has none.
+     */
+    resolve(sessionId: string | undefined, signal?: AbortSignal): Promise<string | undefined>;
+    /**
+     * The sandbox bound right now, without a lookup.
+     *
+     * Used where a call has already resolved the binding and needs it again
+     * without a second round trip.
+     *
+     * @param sessionId - the calling conversation.
+     * @returns the bound sandbox id, or `undefined`.
+     */
+    bound(sessionId: string | undefined): string | undefined;
+    /**
+     * Drop a binding, because the sandbox it names no longer exists.
+     *
+     * @param sandboxId - the sandbox that is gone.
+     */
+    forget(sandboxId: string): void;
+}
+/** The metadata a new sandbox carries so its conversation can be recovered. */
+export declare function sessionMetadata(sessionId: string | undefined, extra: Record<string, string> | undefined): Record<string, string> | undefined;
+/**
+ * The message a tool gets when the conversation has no sandbox.
+ *
+ * Names the remedy, and deliberately does not offer to create one: the model
+ * chooses the template and the lifetime, and it cannot do that from inside a
+ * tool that was asked to write a file.
+ */
+export declare const NO_SANDBOX_MESSAGE: string;
+/**
+ * The message a tool gets when a sandbox existed but is now gone.
+ *
+ * Distinct from {@link NO_SANDBOX_MESSAGE} because the remedy differs: the
+ * binding is stale rather than absent, and the model should know the previous
+ * sandbox's contents are not recoverable — creating a new one starts empty.
+ */
+export declare const SANDBOX_GONE_MESSAGE: string;
+//# sourceMappingURL=sandbox-registry.d.ts.map