@dynamicagents/plugins 0.16.1 → 0.18.0

package/dist/computer/tools-exec.d.ts

@@ -1,3 +1,42 @@
 import type { ToolSet } from "ai";
 import type { ComputerContext } from "./context.js";
+/**
+ * The container's shell, as Computer's `exec` tool.
+ *
+ * **The tool is upstream's, and deliberately not wrapped past the advisory
+ * gate.** Its schema, its description, its truncation and its result shape are
+ * `@cloudflare/computer`'s, so the model sees the same `exec` everywhere that
+ * package's tools are installed and this plugin has no second dialect to keep in
+ * step. What that costs, each of it accepted rather than overlooked:
+ *
+ * - **Truncation keeps the tail, not both ends.** Upstream cuts each stream to
+ *   its last lines, so a failure printed early in a long build is gone from what
+ *   the model reads. The exit code still reports it, and the model's recourse is
+ *   a narrower command.
+ * - **The description promises a file this workspace does not write.** Upstream
+ *   tells the model that truncated output is saved where `read` and `grep` can
+ *   open it. That holds for a Workspace whose runtime saves it; this one reports
+ *   no saved path, so the reply names none and the sentence is unfulfilled.
+ *   Nothing can be set to turn it off: the sentence is built into the generated
+ *   description.
+ * - **A command stopped at the time limit or cancelled reads as a plain
+ *   failure.** Upstream's result has somewhere for an exit code and somewhere
+ *   for an error, and nowhere for the difference between a command that outran
+ *   its limit, one whose call was cancelled, and one that simply failed.
+ *   {@link file://./client.ts CommandResult.status} still carries it for the log
+ *   line below, which is the only place it is read.
+ *
+ * What stays this plugin's, because neither belongs to a tool:
+ *
+ * - **The advisory gate**, below: a command waits out a running install, is
+ *   refused while something transient makes it pointless, and carries a note
+ *   about anything permanent. {@link file://./gate.ts ExecGate} is the contract.
+ * - **How the container runs a command**, in
+ *   {@link file://./sandbox.ts sandboxClient}: the launch-and-cancel handshake,
+ *   the time limit, and the shell transcript. A configured shell merges the two
+ *   streams onto one of them, so `stderr` arrives empty and the whole transcript
+ *   is in `stdout` — see {@link file://./shell.ts withShellTranscript} for why a
+ *   model reading output wants that, and why the plugin's context block rather
+ *   than the tool description is where the model is told.
+ */
 export declare function execTools(ctx: ComputerContext): ToolSet;