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

package/lib/index.js

@@ -907,6 +907,18 @@ defineMethod("transform", [
 * used against should reach it.
 */
 const MAX_LIST_PAGES = 10;
+/**
+* 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.
+*/
+const DEFAULT_TEMPLATE = "default";
 /** Builds and caches SDK handles, one per sandbox id. */
 var SandboxClient = class {
 	constructor(options) {
@@ -929,7 +941,8 @@ var SandboxClient = class {
 	/**
 	* Create a sandbox and cache its handle.
 	*
-	* @param template - the template name or id; the SDK's own default when omitted.
+	* @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.
 	*/
@@ -941,11 +954,8 @@ var SandboxClient = class {
 			...options.envs === void 0 ? {} : { envs: options.envs },
 			...options.metadata === void 0 ? {} : { metadata: options.metadata }
 		};
-		const sandbox = await this.runWithKeyRefresh(options.signal, (apiKey, signal) => template === void 0 ? Sandbox.create({
-			...common,
-			apiKey,
-			...signal === void 0 ? {} : { signal }
-		}) : Sandbox.create(template, {
+		const resolved = template ?? DEFAULT_TEMPLATE;
+		const sandbox = await this.runWithKeyRefresh(options.signal, (apiKey, signal) => Sandbox.create(resolved, {
 			...common,
 			apiKey,
 			...signal === void 0 ? {} : { signal }
@@ -2429,55 +2439,19 @@ function getPortUrlTool(deps) {
 }
 
 //#endregion
-//#region src/index.ts
-/** The provisioning service the API key is fetched from. */
-const DEFAULT_API_BASE_URL = "https://openapi.aishell.openbuildlab.com";
-/** The sandbox gateway's domain — the value an E2B client calls `E2B_DOMAIN`. */
-const DEFAULT_DOMAIN = "aishell.openbuildlab.com";
-/** Default per-request timeout for both the key fetch and SDK calls. */
-const DEFAULT_REQUEST_TIMEOUT_MS = 6e4;
-/** Position of the tier guidance in the assembled prompt. */
+//#region src/prompt.ts
+/** Position of the tier guidance in the assembled context. */
 const SANDBOX_PROMPT_ORDER = 110;
 /** Name this contribution registers under; unique across the assembled prompt. */
 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.
-*/
-const SANDBOX_GUIDANCE = `A sandbox is a disposable Linux environment: it runs for a bounded time, then is deleted along with everything in it.
+/** What the model reads about which tier to use. */
+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.
 
-Use the sandbox tools (aishell__sandbox_*) when the ask is a web page or a simple demo-scale web app — something to look at, or to try out, that does not need to keep existing.
+That is the clearest signal: when the work has to be deployed somewhere reachable and the user wants a URL they can open — a web app, a demo, a service, a static page — 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.
 
-Deploy 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.
+At 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 — the address stops working when it expires.
+
+So: 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.
 
 If 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.
 
@@ -2485,6 +2459,34 @@ A sandbox is often the right place to work something out before committing real
 
 This 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 — 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.
+*/
+function registerSandboxGuidance(ctx) {
+	ctx.inject(["systemPrompt"], (scope) => {
+		scope.systemPrompt.section({
+			name: SANDBOX_SECTION_NAME,
+			order: SANDBOX_PROMPT_ORDER,
+			interpolate: false,
+			text: ({ scope: renderScope }) => ctx.tools.get("aishell__sandbox_create", renderScope) === void 0 ? "" : SANDBOX_GUIDANCE
+		});
+	});
+}
+
+//#endregion
+//#region src/index.ts
+/** The provisioning service the API key is fetched from. */
+const DEFAULT_API_BASE_URL = "https://openapi.aishell.openbuildlab.com";
+/** The sandbox gateway's domain — the value an E2B client calls `E2B_DOMAIN`. */
+const DEFAULT_DOMAIN = "aishell.openbuildlab.com";
+/** Default per-request timeout for both the key fetch and SDK calls. */
+const DEFAULT_REQUEST_TIMEOUT_MS = 6e4;
+/**
 * Settings schema for this entry.
 *
 * Both URLs are Volatile: they are deployment facts that differ between a
@@ -2535,14 +2537,7 @@ function apply(ctx, config) {
 	ctx.effect(() => ctx.on("aishell/credentials-updated", () => {
 		keys.invalidate();
 	}), "aishell-e2b: credential changes");
-	ctx.inject(["systemPrompt"], (scope) => {
-		scope.systemPrompt.section({
-			name: SANDBOX_SECTION_NAME,
-			order: SANDBOX_PROMPT_ORDER,
-			interpolate: false,
-			text: ({ scope: scope$1 }) => ctx.tools.get("aishell__sandbox_create", scope$1) === void 0 ? "" : SANDBOX_GUIDANCE
-		});
-	});
+	registerSandboxGuidance(ctx);
 }
 
 //#endregion

package/lib/types/client.d.ts

@@ -20,6 +20,18 @@
  */
 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`. */
@@ -45,7 +57,8 @@ export declare class SandboxClient {
     /**
      * Create a sandbox and cache its handle.
      *
-     * @param template - the template name or id; the SDK's own default when omitted.
+     * @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.
      */

package/lib/types/index.d.ts

@@ -34,44 +34,6 @@
  */
 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. */
@@ -97,6 +59,7 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
     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.

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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@huaweidevtools/aishell-dsh-e2b",
   "description": "Runs throwaway and preview deployments in E2B sandboxes on DSH — sandbox lifecycle, commands, and files as tools",
-  "version": "0.0.1-beta.3",
+  "version": "0.0.1-beta.5",
   "publishConfig": {
     "access": "public"
   },
@@ -27,7 +27,7 @@
   "license": "Apache-2.0",
   "dependencies": {
     "e2b": "2.59.0",
-    "@huaweidevtools/aishell-dsh-credentials-store": "0.0.1-beta.3"
+    "@huaweidevtools/aishell-dsh-credentials-store": "0.0.1-beta.5"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.4",