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

package/lib/types/client.d.ts

@@ -0,0 +1,137 @@
+/**
+ * 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';
+/**
+ * The template to start from when the caller names none.
+ *
+ * Not the SDK's own default. The SDK resolves an omitted template to `"base"`,
+ * a name from the hosted service; this gateway's templates are its own, and it
+ * answers `"base"` with `404 sandbox unknown was not found` — a message that
+ * reads like a missing sandbox rather than an unknown template, which is what
+ * makes it worth pinning here rather than discovering at the first create.
+ *
+ * `"default"` is what this gateway provisions.
+ */
+export declare const DEFAULT_TEMPLATE = "default";
+/** 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; {@link DEFAULT_TEMPLATE} 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,91 @@
+/**
+ * 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';
+/** 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 { SANDBOX_GUIDANCE, SANDBOX_PROMPT_ORDER, SANDBOX_SECTION_NAME } from './prompt.ts';
+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/prompt.d.ts

@@ -0,0 +1,62 @@
+/**
+ * What the model reads about which tier to use.
+ *
+ * ## Why this is its own module
+ *
+ * The text and the mechanism that delivers it belong together. Split across
+ * `index.ts` — the string one place, the `systemPrompt.section()` call another —
+ * the only way to see what the model actually reads is to read both. Here they
+ * sit side by side, and `apply()` just calls {@link registerSandboxGuidance}.
+ *
+ * ## Why the split is stated three ways
+ *
+ * An earlier version drew the line at lifecycle alone: "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.
+ *
+ * Two things make it answerable instead:
+ *
+ *   - **What the user asked for.** "A web page or a demo" versus "a production
+ *     system" is a distinction a person can answer directly.
+ *   - **What the work needs.** The one capability a sandbox has that this
+ *     machine does not is a public address. A request to deploy something and
+ *     get a URL back is the strongest signal there is, and it is stated first
+ *     because it is the least ambiguous.
+ *
+ * The three are kept together rather than reduced to one. They disagree at the
+ * edges — a demo that must stay up, a production service that starts as a
+ * sketch — and when they do, asking the user is the answer, which the text says.
+ *
+ * ## 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. So 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.
+ *
+ * ## 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.
+ *
+ * @module @huaweidevtools/aishell-dsh-e2b/prompt
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Position of the tier guidance in the assembled context. */
+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. */
+export declare const SANDBOX_GUIDANCE = "A sandbox is a Linux environment running remotely. It exists for a bounded time, then is deleted along with everything in it. What it gives you that this machine does not is a public address.\n\nThat is the clearest signal: when the work has to be deployed somewhere reachable and the user wants a URL they can open \u2014 a web app, a demo, a service, a static page \u2014 use the sandbox tools (aishell__sandbox_*). Put the files there with aishell__sandbox_files_write, start the server with aishell__sandbox_commands_run and background: true, then call aishell__sandbox_get_port_url and give the user that address.\n\nAt the other end, a production system belongs in real infrastructure, deployed with the Terraform tools (aishell__terraform_* and their neighbours). It will cost money, it should keep running, and it will be operated. The sandbox is the wrong tier for it not because it is small but because it is deliberately short-lived \u2014 the address stops working when it expires.\n\nSo: a page or a demo, or anything that should end in a URL to open, is a sandbox. A system to run and keep running is Terraform.\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.";
+/**
+ * Register the guidance section.
+ *
+ * Deferred behind `ctx.inject` rather than declared in this plugin's own
+ * `inject`: the guidance is an enhancement, and a deployment without a system
+ * prompt should lose it rather than fail to mount.
+ *
+ * @param ctx - host context.
+ */
+export declare function registerSandboxGuidance(ctx: Context): void;
+//# sourceMappingURL=prompt.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