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

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined in Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is derived from (or based upon) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Huawei Cloud AI Shell
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied. See the License for the specific language governing
+   permissions and limitations under the License.

package/README.md

@@ -1,3 +1,201 @@
-# Temporary Holding Version
+# @huaweidevtools/aishell-dsh-e2b
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Runs throwaway and preview deployments in E2B sandboxes — sandbox lifecycle,
+commands, and files, as tools the model calls.
+
+> **Not to be confused with `@deepseek-ai/dsh-e2b`.** That official package
+> replaces the harness's execution world: mount it and *all* of the agent's own
+> file and command work runs in a remote sandbox. This package instead adds
+> *tools*, so the agent keeps working locally and reaches a sandbox only when it
+> decides to.
+>
+> The two can be mounted together. This package registers its tools under the
+> `aishell__` prefix (`aishell__sandbox_create`), so a tool name cannot collide
+> with the official package's, whichever names it uses.
+
+## Why this exists
+
+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 second tier, and contributes a prompt section stating when
+each is appropriate. Tools alone would leave the choice to guesswork.
+
+## How it reaches the service
+
+```
+POST https://openapi.aishell.openbuildlab.com/e2b/keys   (AK/SK signed)
+    → {"api_key": "sk-e2b-…", "expires_at": "…"}   presented as X-API-KEY
+```
+
+The key is a **stored credential**, kept under `AISHELL_E2B_API_KEY` in the same
+credential store the AK/SK live in:
+
+1. Read it from the store.
+2. Missing, past its `expires_at`, **or minted under different credentials** →
+   `POST /e2b/keys` once, and store the result.
+3. Present the stored key on every sandbox call.
+4. If a sandbox call is refused as unauthenticated → discard the key, issue a
+   new one, and retry that call once.
+
+A key issued with no expiry records `9999-12-31` as its expiry, so "never
+expires" stays one comparison rather than a second shape.
+
+### The key belongs to the credentials that minted it
+
+The key entry also records a **fingerprint of the AK** that requested it, and a
+stored key is used only while it matches the credentials in hand. Without that,
+clearing or replacing the AK/SK would leave the old key — and so the old tenant,
+with all its sandboxes — alive and usable, which is the opposite of what
+clearing credentials means.
+
+Three consequences are deliberate:
+
+- **No credentials at all invalidates it too.** Clearing them states that
+  nothing granted under them may still be presented.
+- **Re-entering the same AK/SK does not rotate the key.** The fingerprint
+  answers "which identity minted this", not "when was it written". Re-saving the
+  same pair has changed nothing, and throwing away running sandboxes for it
+  would be gratuitous.
+- **No event listener is needed.** The check is on the read path, so it also
+  catches a store changed outside the credential form, or while this plugin was
+  not mounted.
+
+A mismatch does **not** delete the stored entry: an empty read is not proof of a
+clear (a locked keyring answers `undefined` for entries that are really there),
+and deleting on it would rotate the tenant on every keyring hiccup. The entry is
+overwritten by the next successful create. A key stored by an older build
+carries no fingerprint and is trusted as-is, so upgrading does not orphan
+existing sandboxes; the 401 path still catches a key that has really stopped
+working.
+
+The key is the tenant: the gateway derives a caller identity from the presented
+key and scopes every sandbox to it. That is why it is **persisted rather than
+held in memory** — a key re-created on every start would be a new tenant, and
+every sandbox made before it would stop being reachable, which surfaces as "no
+such sandbox" and points nowhere near the cause. A replacement key is a new
+tenant for the same reason, so the 401 path is a recovery for a dead key, not a
+routine refresh.
+
+The sandbox protocol itself is spoken by the official `e2b` client library,
+pointed at the gateway's domain — the configuration the gateway exists to accept.
+
+## Tools
+
+Registered under `aishell__`, like every tool this plugin set contributes. The
+prefix is what makes several packages' tools coexist in one registry: a bare
+`sandbox_create` is fine until another package registers the same name, and then
+one of the two silently loses.
+
+| Tool | E2B SDK method |
+|---|---|
+| `aishell__sandbox_create` | `Sandbox.create` |
+| `aishell__sandbox_list` | `Sandbox.list` |
+| `aishell__sandbox_info` | `getInfo` |
+| `aishell__sandbox_kill` | `kill` |
+| `aishell__sandbox_set_timeout` | `setTimeout` |
+| `aishell__sandbox_commands_run` | `commands.run` |
+| `aishell__sandbox_commands_kill` | `commands.kill` |
+| `aishell__sandbox_files_write` | `files.write` |
+| `aishell__sandbox_files_read` | `files.read` |
+| `aishell__sandbox_files_download` | `files.read` → `ctx.fs` |
+| `aishell__sandbox_files_list` | `files.list` |
+| `aishell__sandbox_get_port_url` | `getHost` |
+
+### One conversation, one sandbox
+
+A conversation works in at most 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 somewhere the model did not mean.
+
+`aishell__sandbox_create` binds the sandbox to the conversation; creating a second one
+replaces the binding, and the first keeps running until its lifetime expires, so
+`aishell__sandbox_kill` is how it is released.
+
+**The binding is never created implicitly.** A tool called with no sandbox fails
+and names `aishell__sandbox_create`. A tool that quietly created one would have to pick
+the template and the lifetime, and those are the two decisions the create tool's
+parameters exist to put in the conversation.
+
+**The binding survives a restart.** The sandbox is tagged with its conversation
+in its own `metadata` at creation, and a process that has no binding rebuilds it
+by querying for that tag — so a plugin reload does not orphan a running sandbox.
+A paused sandbox is not adopted, because using it would mean resuming it and
+restarting its clock.
+
+### Three conventions worth knowing
+
+- **`timeoutMs` is milliseconds.** The TypeScript SDK counts milliseconds where
+  the Python one counts seconds. The service caps a lifetime at 24 hours for a
+  pro account and 1 hour for a hobby account.
+- **A sandbox that has expired is distinguished from one that never existed.**
+  The first means the previous sandbox's contents are gone and a replacement
+  starts empty; the error says so, because the model has to know that before it
+  decides to carry on.
+- **A non-zero exit is a result, not a failure.** `aishell__sandbox_commands_run` reports
+  the exit code and both streams, so a failing test or a compile error reads as
+  an outcome to reason about rather than a broken tool.
+
+## Config
+
+| Field | Default | Meaning |
+|---|---|---|
+| `apiBaseUrl` | `https://openapi.aishell.openbuildlab.com` | The key provisioning service |
+| `domain` | `aishell.openbuildlab.com` | The sandbox gateway's domain (an E2B client's `E2B_DOMAIN`) |
+| `requestTimeoutMs` | `60,000` | Per-request timeout, key fetch and SDK calls alike |
+
+Credentials are the same Huawei Cloud AK/SK pair the other plugins in this set
+use, read from the same store. Store them through the credential button in the
+composer — the Huawei Cloud chip under the input bar, or the same chip on the
+New-Session row. Clicking it opens the credential form in the current
+conversation; there is no Settings section to find.
+
+## What it does NOT do
+
+- **It does not provision cloud resources.** Persistent infrastructure belongs to
+  the operations server; nothing here survives a sandbox's lifetime.
+- **It does not move the agent's own work into a sandbox.** Files the agent reads
+  and commands it runs stay local unless it calls one of these tools. For the
+  other arrangement, mount the official `@deepseek-ai/dsh-e2b`.
+- **It does not gate destructive calls behind approval.** `aishell__sandbox_kill` and
+  `aishell__sandbox_commands_run` run without an approval prompt in this version.
+- **It cannot write a binary file to the local workspace.** The sandbox side
+  supports it — `files.read` returns bytes, and `sandbox.downloadUrl` issues a
+  presigned URL — but the harness filesystem (`ctx.fs`) accepts UTF-8 text only,
+  with no binary write on either the abstract provider or the local backend. So
+  `aishell__sandbox_files_download` writes text as text and, for a binary file, returns
+  base64 and says so rather than writing a mangled copy.
+- **It does not adopt a paused sandbox.** Recovery only takes a sandbox the
+  gateway reports as running. A paused one would have to be resumed to be used,
+  which restarts its clock — a billing decision left to `aishell__sandbox_create`.
+- **It does not tag pre-existing sandboxes.** A sandbox created outside this
+  plugin carries no conversation tag, so `aishell__sandbox_list` shows it but no
+  conversation adopts it.
+
+## Install
+
+```sh
+# Standalone
+dsh plugin --profile <name> add @huaweidevtools/aishell-dsh-e2b
+
+# Or as part of the set
+dsh plugin --profile <name> add @huaweidevtools/aishell-dsh-base
+```
+
+## Known gaps
+
+- **Public reachability of a port URL is not yet settled.** `aishell__sandbox_get_port_url`
+  returns `https://<port>-<sandboxId>.<domain>`, following the E2B SDK, whose
+  `getHost` composes exactly that hostname. Whether that address is open to
+  anyone or requires the sandbox's traffic token is decided by the gateway's
+  network configuration, and has not been verified against a live deployment.
+- **`files.write` feature gates depend on the sandbox's `envd` version.** In
+  particular `useOctetStream` needs envd ≥ 0.5.7 — below that the SDK silently
+  falls back to multipart. The text writes this plugin performs are unaffected.
+
+## License
+
+Apache License 2.0. See [LICENSE](../../LICENSE).

package/cordis.patch.yml

@@ -0,0 +1,19 @@
+# aishell-e2b bundle patch: inserts the sandbox-tools plugin.
+# Install standalone: `dsh plugin --profile <name> add @huaweidevtools/aishell-dsh-e2b`
+#
+# The single row mounts a host-only plugin: it registers the sandbox tools
+# and one prompt section saying when a sandbox is the right tier rather than
+# provisioning real resources. It has no browser half.
+#
+# The name is close to the official `@deepseek-ai/dsh-e2b`, which is a
+# different thing: that package replaces the harness's execution world so all
+# of the agent's own file and command work runs remotely. This one adds tools
+# the agent calls deliberately, and leaves its local work local. Only the names
+# resemble each other.
+#
+# The row carries no `config`: the defaults point at the published AI Shell
+# services, and a profile that needs another deployment sets apiBaseUrl and
+# domain itself.
+- insert:
+    - id: aishell-e2b
+      name: '@huaweidevtools/aishell-dsh-e2b'