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

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

package/lib/types/tools.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The model-facing tools.
+ *
+ * Each one is a thin projection of an E2B SDK call: the tool's parameters are
+ * the SDK's own options, and its result is the SDK's own return value in a
+ * shape that survives JSON. That correspondence is the point — an operator who
+ * reads the E2B documentation should find nothing surprising here, and the
+ * next plugin in this family can keep the same contract.
+ *
+ * Three conventions are load-bearing and are repeated in the descriptions the
+ * model reads:
+ *
+ *   - **One conversation, one sandbox.** No tool but `aishell__sandbox_create` takes a
+ *     `sandboxId`. There is nothing to choose between, so there is no parameter
+ *     to get wrong, and no way for a call to land in a different sandbox than
+ *     the model meant.
+ *   - **`timeoutMs` is milliseconds.** The TypeScript SDK counts milliseconds
+ *     where the Python one counts seconds; a model that learned the Python
+ *     spelling would ask for a five-second sandbox and get five thousand.
+ *   - **A non-zero exit is a result, not a failure.** `aishell__sandbox_commands_run`
+ *     reports the code and both streams, so a failing command reads as an
+ *     outcome to reason about rather than a broken tool.
+ *
+ * @module @huaweidevtools/aishell-dsh-e2b/tools
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { SandboxClient } from './client.ts';
+import { type SandboxRegistry } from './sandbox-registry.ts';
+/** What every tool needs to act. */
+export interface ToolDeps {
+    /** The sandbox gateway connection. */
+    readonly client: SandboxClient;
+    /** The sandbox this conversation is bound to. */
+    readonly registry: SandboxRegistry;
+    /** The filesystem the local workspace is reached through, when one is mounted. */
+    readonly resolveFs: () => Context['fs'] | undefined;
+}
+/**
+ * Register every sandbox tool.
+ *
+ * @param ctx - the plugin context, providing the tool registry.
+ * @param deps - the shared dependencies.
+ * @returns disposers for the registrations.
+ */
+export declare function registerSandboxTools(ctx: Context, deps: ToolDeps): Array<() => void>;
+//# sourceMappingURL=tools.d.ts.map

package/package.json

@@ -1,6 +1,56 @@
 {
   "name": "@huaweidevtools/aishell-dsh-e2b",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Runs throwaway and preview deployments in E2B sandboxes on DSH — sandbox lifecycle, commands, and files as tools",
+  "version": "0.0.1-beta.4",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yusheng-g/aishell-dsh-plugins.git",
+    "directory": "packages/aishell-e2b"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    }
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts",
+    "cordis.patch.yml"
+  ],
+  "license": "Apache-2.0",
+  "dependencies": {
+    "e2b": "2.59.0",
+    "@huaweidevtools/aishell-dsh-credentials-store": "0.0.1-beta.4"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.4",
+    "@deepseek-ai/dsh-fs": "0.2.0-rc.1 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1",
+    "@deepseek-ai/dsh-system-prompt": "0.2.0-rc.1 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1",
+    "@deepseek-ai/dsh-tools": "0.2.0-rc.1 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.4",
+    "@deepseek-ai/cordis-plugin-loader": "^1.0.5",
+    "@deepseek-ai/dsh-fs": "0.2.0-rc.1 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1",
+    "@deepseek-ai/dsh-system-prompt": "0.2.0-rc.1 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1",
+    "@deepseek-ai/dsh-tools": "0.2.0-rc.1 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1",
+    "@deepseek-ai/schemastery": "3.18.4",
+    "tsdown": "^0.10.0",
+    "typescript": "^5.7.0"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "scripts": {
+    "build:bundle": "tsdown"
+  }
 }