@sisu-ai/tool-terminal 7.0.1 → 7.1.1

package/README.md

@@ -1,3 +1,9 @@
+<div align="right">
+  <a href="https://github.com/finger-gun/sisu"><img src="https://github.com/finger-gun/sisu/raw/main/sisu-light.svg" alt="ProjectSpecs" width="100" /></a>
+</div>
+
+---
+
 # @sisu-ai/tool-terminal
 
 A secure terminal execution tool for Sisu agents. Provides sandboxed command execution with session support, a strict allow list, realpath-based path scoping, timeouts and basic file helpers. Commands run without a shell and reject control operators by default; optional shell-free pipelines (`|`) and sequences (`;`, `&&`, `||`) can be enabled via config.
@@ -153,3 +159,78 @@ Discover what you can do through examples or documentation. Check it out at http
 - [License](https://github.com/finger-gun/sisu/blob/main/LICENSE)
 - [Report a Bug](https://github.com/finger-gun/sisu/issues/new?template=bug_report.md)
 - [Request a Feature](https://github.com/finger-gun/sisu/issues/new?template=feature_request.md)
+
+---
+
+## Documentation
+
+**Core** — [Package docs](packages/core/README.md) · [Error types](packages/core/ERROR_TYPES.md)
+
+**Adapters** — [OpenAI](packages/adapters/openai/README.md) · [Anthropic](packages/adapters/anthropic/README.md) · [Ollama](packages/adapters/ollama/README.md)
+
+<details>
+<summary>All middleware packages</summary>
+
+- [@sisu-ai/mw-agent-run-api](packages/middleware/agent-run-api/README.md)
+- [@sisu-ai/mw-context-compressor](packages/middleware/context-compressor/README.md)
+- [@sisu-ai/mw-control-flow](packages/middleware/control-flow/README.md)
+- [@sisu-ai/mw-conversation-buffer](packages/middleware/conversation-buffer/README.md)
+- [@sisu-ai/mw-cors](packages/middleware/cors/README.md)
+- [@sisu-ai/mw-error-boundary](packages/middleware/error-boundary/README.md)
+- [@sisu-ai/mw-guardrails](packages/middleware/guardrails/README.md)
+- [@sisu-ai/mw-invariants](packages/middleware/invariants/README.md)
+- [@sisu-ai/mw-orchestration](packages/middleware/orchestration/README.md)
+- [@sisu-ai/mw-rag](packages/middleware/rag/README.md)
+- [@sisu-ai/mw-react-parser](packages/middleware/react-parser/README.md)
+- [@sisu-ai/mw-register-tools](packages/middleware/register-tools/README.md)
+- [@sisu-ai/mw-tool-calling](packages/middleware/tool-calling/README.md)
+- [@sisu-ai/mw-trace-viewer](packages/middleware/trace-viewer/README.md)
+- [@sisu-ai/mw-usage-tracker](packages/middleware/usage-tracker/README.md)
+</details>
+
+<details>
+<summary>All tool packages</summary>
+
+- [@sisu-ai/tool-aws-s3](packages/tools/aws-s3/README.md)
+- [@sisu-ai/tool-azure-blob](packages/tools/azure-blob/README.md)
+- [@sisu-ai/tool-extract-urls](packages/tools/extract-urls/README.md)
+- [@sisu-ai/tool-github-projects](packages/tools/github-projects/README.md)
+- [@sisu-ai/tool-summarize-text](packages/tools/summarize-text/README.md)
+- [@sisu-ai/tool-terminal](packages/tools/terminal/README.md)
+- [@sisu-ai/tool-vec-chroma](packages/tools/vec-chroma/README.md)
+- [@sisu-ai/tool-web-fetch](packages/tools/web-fetch/README.md)
+- [@sisu-ai/tool-web-search-duckduckgo](packages/tools/web-search-duckduckgo/README.md)
+- [@sisu-ai/tool-web-search-google](packages/tools/web-search-google/README.md)
+- [@sisu-ai/tool-web-search-openai](packages/tools/web-search-openai/README.md)
+- [@sisu-ai/tool-wikipedia](packages/tools/wikipedia/README.md)
+</details>
+
+<details>
+<summary>All examples</summary>
+
+**Anthropic** — [hello](examples/anthropic-hello/README.md) · [control-flow](examples/anthropic-control-flow/README.md) · [stream](examples/anthropic-stream/README.md) · [weather](examples/anthropic-weather/README.md)
+
+**Ollama** — [hello](examples/ollama-hello/README.md) · [stream](examples/ollama-stream/README.md) · [vision](examples/ollama-vision/README.md) · [weather](examples/ollama-weather/README.md) · [web-search](examples/ollama-web-search/README.md)
+
+**OpenAI** — [hello](examples/openai-hello/README.md) · [weather](examples/openai-weather/README.md) · [stream](examples/openai-stream/README.md) · [vision](examples/openai-vision/README.md) · [reasoning](examples/openai-reasoning/README.md) · [react](examples/openai-react/README.md) · [control-flow](examples/openai-control-flow/README.md) · [branch](examples/openai-branch/README.md) · [parallel](examples/openai-parallel/README.md) · [graph](examples/openai-graph/README.md) · [orchestration](examples/openai-orchestration/README.md) · [orchestration-adaptive](examples/openai-orchestration-adaptive/README.md) · [guardrails](examples/openai-guardrails/README.md) · [error-handling](examples/openai-error-handling/README.md) · [rag-chroma](examples/openai-rag-chroma/README.md) · [web-search](examples/openai-web-search/README.md) · [web-fetch](examples/openai-web-fetch/README.md) · [wikipedia](examples/openai-wikipedia/README.md) · [terminal](examples/openai-terminal/README.md) · [github-projects](examples/openai-github-projects/README.md) · [server](examples/openai-server/README.md) · [aws-s3](examples/openai-aws-s3/README.md) · [azure-blob](examples/openai-azure-blob/README.md)
+</details>
+
+---
+
+## Contributing
+
+We build Sisu in the open. Contributions welcome.
+
+[Contributing Guide](CONTRIBUTING.md) · [Report a Bug](https://github.com/finger-gun/sisu/issues/new?template=bug_report.md) · [Request a Feature](https://github.com/finger-gun/sisu/issues/new?template=feature_request.md) · [Code of Conduct](CODE_OF_CONDUCT.md)
+
+---
+
+<div align="center">
+
+**[Star on GitHub](https://github.com/finger-gun/sisu)** if Sisu helps you build better agents.
+
+*Quiet, determined, relentlessly useful.*
+
+[Apache 2.0 License](LICENSE)
+
+</div>

package/dist/index.d.ts

@@ -28,6 +28,26 @@ export interface TerminalToolConfig {
 export declare const DEFAULT_CONFIG: TerminalToolConfig;
 export declare const TERMINAL_COMMANDS_ALLOW: ReadonlyArray<string>;
 export declare function defaultTerminalConfig(overrides?: Partial<TerminalToolConfig>): TerminalToolConfig;
+interface TerminalPolicy {
+    allowed: boolean;
+    reason?: string;
+    allowedCommands?: string[];
+    allowedRoots?: string[];
+}
+interface TerminalRunResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    durationMs: number;
+    policy: TerminalPolicy;
+    message?: string;
+    cwd: string;
+}
+interface TerminalReadResult {
+    contents: string;
+    policy: TerminalPolicy;
+    message?: string;
+}
 export declare function createTerminalTool(config?: Partial<TerminalToolConfig>): {
     start_session: (args?: {
         cwd?: string;
@@ -42,17 +62,7 @@ export declare function createTerminalTool(config?: Partial<TerminalToolConfig>)
         env?: Record<string, string>;
         stdin?: string;
         sessionId?: string;
-    }) => Promise<{
-        exitCode: number;
-        stdout: string;
-        stderr: string;
-        durationMs: number;
-        policy: {
-            allowed: boolean;
-            reason?: string;
-        };
-        cwd: string;
-    }>;
+    }) => Promise<TerminalRunResult>;
     cd: (args: {
         path: string;
         sessionId?: string;
@@ -64,16 +74,14 @@ export declare function createTerminalTool(config?: Partial<TerminalToolConfig>)
         path: string;
         encoding?: "utf8" | "base64";
         sessionId?: string;
-    }) => Promise<{
-        contents: string;
-    }>;
+    }) => Promise<TerminalReadResult>;
     tools: (Tool<{
         command: string;
         cwd?: string;
         env?: Record<string, string>;
         stdin?: string;
         sessionId?: string;
-    }, any> | Tool<{
+    }, TerminalRunResult> | Tool<{
         path: string;
         sessionId?: string;
     }, {
@@ -83,8 +91,7 @@ export declare function createTerminalTool(config?: Partial<TerminalToolConfig>)
         path: string;
         encoding?: "utf8" | "base64";
         sessionId?: string;
-    }, {
-        contents: string;
-    }>)[];
+    }, TerminalReadResult>)[];
 };
 export type TerminalTool = ReturnType<typeof createTerminalTool>;
+export {};

package/dist/index.js

@@ -87,6 +87,8 @@ function isPathAllowed(absPath, cfg, mode) {
     return true;
 }
 function looksLikePath(arg) {
+    if (/^https?:\/\//i.test(arg))
+        return false;
     return (arg.startsWith(".") ||
         arg.includes("/") ||
         /^(?:[A-Za-z]:[\\/]|\\\\)/.test(arg));
@@ -240,7 +242,7 @@ function commandPolicyCheck(args, cfg) {
         found.push("`...`");
     if (/>/.test(cmdStr))
         found.push(">");
-    if (/<\<?/.test(cmdStr))
+    if (/<<?/.test(cmdStr))
         found.push("<");
     if (/(^|\s)&(\s|$)/.test(cmdStr))
         found.push("&");
@@ -373,7 +375,12 @@ export function createTerminalTool(config) {
                 stdout: "",
                 stderr: "",
                 durationMs: 0,
-                policy: pre,
+                policy: {
+                    allowed: false,
+                    reason: pre.reason,
+                    allowedCommands: cfg.commands.allow,
+                },
+                message: `Command denied by policy. Allowed commands: ${cfg.commands.allow.join(", ")}.`,
                 cwd,
             };
         }
@@ -431,7 +438,9 @@ export function createTerminalTool(config) {
                     try {
                         c.kill("SIGKILL");
                     }
-                    catch { }
+                    catch {
+                        // ignore kill errors
+                    }
                 }
             };
             const onStdout = (d) => {
@@ -547,14 +556,14 @@ export function createTerminalTool(config) {
     }
     function cd(args) {
         let session = getSession(args.sessionId);
+        let createdSessionId;
         // If no valid session is provided, create one anchored at the first root
         if (!session) {
             const cwd = canonicalize(cfg.roots[0]);
-            const sessionId = randomUUID();
+            createdSessionId = randomUUID();
             const expiresAt = Date.now() + cfg.sessions.ttlMs;
             session = { cwd, env: {}, expiresAt };
-            sessions.set(sessionId, session);
-            args._createdSessionId = sessionId;
+            sessions.set(createdSessionId, session);
         }
         const newPath = canonicalize(path.resolve(session.cwd, args.path));
         if (!isPathAllowed(newPath, cfg, "exec")) {
@@ -564,7 +573,7 @@ export function createTerminalTool(config) {
         session.expiresAt = Date.now() + cfg.sessions.ttlMs;
         return {
             cwd: session.cwd,
-            sessionId: args._createdSessionId ?? args.sessionId,
+            sessionId: createdSessionId ?? args.sessionId,
         };
     }
     async function read_file(args) {
@@ -573,12 +582,21 @@ export function createTerminalTool(config) {
         const session = getSession(args.sessionId);
         const cwd = session?.cwd ?? cfg.roots[0];
         const abs = canonicalize(path.resolve(cwd, args.path));
-        if (!isPathAllowed(abs, cfg, "read"))
-            throw new Error("path outside allowed roots");
+        if (!isPathAllowed(abs, cfg, "read")) {
+            return {
+                contents: "",
+                policy: {
+                    allowed: false,
+                    reason: "path outside allowed roots",
+                    allowedRoots: cfg.roots,
+                },
+                message: `Path denied by policy. Allowed roots: ${cfg.roots.join(", ")}.`,
+            };
+        }
         const buf = await fs.readFile(abs);
         const encoding = args.encoding ?? "utf8";
         const contents = encoding === "base64" ? buf.toString("base64") : buf.toString("utf8");
-        return { contents };
+        return { contents, policy: { allowed: true } };
     }
     const runCommandTool = {
         name: "terminalRun",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sisu-ai/tool-terminal",
-  "version": "7.0.1",
+  "version": "7.1.1",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -12,7 +12,7 @@
     "zod": "^3.23.8"
   },
   "peerDependencies": {
-    "@sisu-ai/core": "^2.3.1"
+    "@sisu-ai/core": "^2.3.2"
   },
   "repository": {
     "type": "git",