@sisu-ai/tool-terminal 1.1.0

package/README.md

@@ -0,0 +1,119 @@
+# @sisu-ai/tool-terminal
+
+[![Tests](https://github.com/finger-gun/sisu/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/finger-gun/sisu/actions/workflows/tests.yml)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/finger-gun/sisu/blob/main/LICENSE)
+[![Downloads](https://img.shields.io/npm/dm/%40sisu-ai%2Ftool-terminal)](https://www.npmjs.com/package/@sisu-ai/tool-terminal)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/finger-gun/sisu/blob/main/CONTRIBUTING.md)
+
+A secure terminal execution tool for Sisu agents. Provides sandboxed shell command execution with session support, command allow/deny lists, path scoping, timeouts and basic file helpers.
+
+## API
+
+- `createTerminalTool(config?)` → returns an instance with:
+  - methods: `start_session`, `run_command`, `cd`, `read_file`
+  - `tools`: an array of Tool definitions (for models): `terminalRun`, `terminalCd`, `terminalReadFile`.
+
+### Defaults & Reuse
+- Importable defaults to help you build policies/UI:
+  - `DEFAULT_CONFIG` — full default config object
+  - `TERMINAL_COMMANDS_ALLOW` — default allowlist array
+  - `TERMINAL_COMMANDS_DENY` — default denylist array
+  - `defaultTerminalConfig(partial)` — helper to merge your overrides with sensible defaults
+
+## Quick Start
+
+```ts
+import 'dotenv/config';
+import { Agent, SimpleTools, InMemoryKV, NullStream, createConsoleLogger, type Ctx } from '@sisu-ai/core';
+import { openAIAdapter } from '@sisu-ai/adapter-openai';
+import { registerTools } from '@sisu-ai/mw-register-tools';
+import { inputToMessage, conversationBuffer } from '@sisu-ai/mw-conversation-buffer';
+import { toolCalling } from '@sisu-ai/mw-tool-calling';
+import { errorBoundary } from '@sisu-ai/mw-error-boundary';
+import { traceViewer } from '@sisu-ai/mw-trace-viewer';
+import { createTerminalTool } from '@sisu-ai/tool-terminal';
+
+const terminal = createTerminalTool({ roots: [process.cwd()] });
+
+const model = openAIAdapter({ model: process.env.MODEL || 'gpt-4o-mini' });
+const ctx: Ctx = {
+  input: 'List files in the project root and show the first 10 lines of README.md.',
+  messages: [{ role: 'system', content: 'You are a helpful assistant.' }],
+  model,
+  tools: new SimpleTools(),
+  memory: new InMemoryKV(),
+  stream: new NullStream(),
+  state: {},
+  signal: new AbortController().signal,
+  log: createConsoleLogger({ level: (process.env.LOG_LEVEL as any) ?? 'info' }),
+};
+
+const app = new Agent()
+  .use(errorBoundary(async (err, c) => { c.log.error(err); }))
+  .use(traceViewer())
+  .use(registerTools(terminal.tools))
+  .use(inputToMessage)
+  .use(conversationBuffer({ window: 6 }))
+  .use(toolCalling);
+
+await app.handler()(ctx);
+console.log(ctx.messages.filter(m => m.role === 'assistant').pop()?.content);
+```
+
+## Logging & Traces
+- Tools emit structured logs via `ctx.log` so runs are visible in traces:
+  - `terminalRun`: logs policy pre-check and final result (exit code, duration, bytes).
+  - `terminalCd`: logs requested and resolved paths and whether allowed.
+  - `terminalReadFile`: logs resolved path and byte size of returned contents.
+
+## Config (subset)
+
+```ts
+type TerminalToolConfig = {
+  roots: string[];                // allowed path roots (required)
+  readOnlyRoots?: string[];
+  capabilities: { read: boolean; write: boolean; delete: boolean; exec: boolean };
+  commands: { allow: string[]; deny: string[] };
+  execution: { timeoutMs: number; maxStdoutBytes: number; maxStderrBytes: number; shell: 'direct'|'sh'|'bash'|'powershell'|'cmd' };
+  sessions: { enabled: boolean; ttlMs: number; maxPerAgent: number };
+}
+```
+
+Sensible defaults: `read: true`, `exec: true`, `write/delete: false`, timeout 10s, `roots: [process.cwd()]`, and a conservative allow/deny command policy. See `DEFAULT_CONFIG` in `src/index.ts` for full details.
+
+## Tool Schemas
+
+- `terminalRun({ command, cwd?, env?, stdin?, sessionId? }) → { exitCode, stdout, stderr, durationMs, policy, cwd }`
+- `terminalCd({ path, sessionId? }) → { cwd, sessionId? }`  // creates a session if missing
+- `terminalReadFile({ path, encoding?, sessionId? }) → { contents }`
+
+Each tool is validated with zod and registered through the instance’s `tools` array. `start_session` is available as a method for advanced use but is not exposed as a tool by default.
+
+### When To Use `start_session`
+- Persistent cwd across multiple calls: when you plan a sequence like “cd → run → read → run” and want a stable working directory without passing `cwd` every time.
+- Pre-seeding env: when a short‑lived, limited env should apply to multiple runs (e.g., `PATH` tweak, `FOO_MODE=1`) without repeating it on each call.
+- Deterministic bursts: when you want a TTL‑bounded context that will expire automatically after inactivity (defaults to 2 minutes), avoiding stale state.
+- Lower friction than an initial `terminalCd`: prefer `start_session({ cwd, env })` if you already know the starting folder and env.
+
+Example
+```ts
+const term = createTerminalTool({ roots: [process.cwd()] });
+const { sessionId } = term.start_session({ cwd: process.cwd(), env: { FOO_MODE: '1' } });
+await term.run_command({ sessionId, command: 'ls -la' });
+await term.run_command({ sessionId, command: 'grep -n "TODO" README.md' });
+const file = await term.read_file({ sessionId, path: 'README.md' });
+```
+
+## Notes
+
+- Non-interactive commands only.
+- Network-accessing commands are denied by default via patterns (e.g., `curl *`, `wget *`).
+- All paths are resolved and constrained to configured `roots`; write/delete under read-only roots are denied.
+- Absolute path arguments outside `roots` are denied (e.g., `grep -r /`). Prefer setting `cwd` (via `terminalCd`) and using relative paths.
+
+# Community & Support
+- [Code of Conduct](https://github.com/finger-gun/sisu/blob/main/CODE_OF_CONDUCT.md)
+- [Contributing Guide](https://github.com/finger-gun/sisu/blob/main/CONTRIBUTING.md)
+- [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)

package/dist/index.d.ts

@@ -0,0 +1,108 @@
+import type { Tool } from '@sisu-ai/core';
+export interface TerminalToolConfig {
+    roots: string[];
+    readOnlyRoots?: string[];
+    capabilities: {
+        read: boolean;
+        write: boolean;
+        delete: boolean;
+        exec: boolean;
+    };
+    commands: {
+        allow: string[];
+        deny: string[];
+    };
+    execution: {
+        timeoutMs: number;
+        maxStdoutBytes: number;
+        maxStderrBytes: number;
+        shell: 'sh' | 'bash' | 'powershell' | 'cmd' | 'direct';
+    };
+    sessions: {
+        enabled: boolean;
+        ttlMs: number;
+        maxPerAgent: number;
+    };
+}
+export declare const DEFAULT_CONFIG: TerminalToolConfig;
+export declare const TERMINAL_COMMANDS_ALLOW: ReadonlyArray<string>;
+export declare const TERMINAL_COMMANDS_DENY: ReadonlyArray<string>;
+export declare function defaultTerminalConfig(overrides?: Partial<TerminalToolConfig>): TerminalToolConfig;
+export declare function createTerminalTool(config?: Partial<TerminalToolConfig>): {
+    start_session: (args?: {
+        cwd?: string;
+        env?: Record<string, string>;
+    }) => {
+        sessionId: `${string}-${string}-${string}-${string}-${string}`;
+        expiresAt: string;
+    };
+    run_command: (args: {
+        command: string;
+        cwd?: string;
+        env?: Record<string, string>;
+        stdin?: string;
+        sessionId?: string;
+    }) => Promise<{
+        exitCode: number;
+        stdout: string;
+        stderr: string;
+        durationMs: number;
+        policy: {
+            allowed: boolean;
+            reason?: string;
+        };
+        cwd: string;
+    } | {
+        exitCode: number;
+        stdout: Buffer<ArrayBufferLike>;
+        stderr: Buffer<ArrayBufferLike>;
+        durationMs: number;
+        policy: {
+            allowed: boolean;
+        };
+        cwd: string;
+    } | {
+        exitCode: any;
+        stdout: string;
+        stderr: string;
+        durationMs: number;
+        policy: {
+            allowed: boolean;
+        };
+        cwd: string;
+    }>;
+    cd: (args: {
+        path: string;
+        sessionId?: string;
+    }) => {
+        cwd: string;
+        sessionId?: string;
+    };
+    read_file: (args: {
+        path: string;
+        encoding?: "utf8" | "base64";
+        sessionId?: string;
+    }) => Promise<{
+        contents: string;
+    }>;
+    tools: (Tool<{
+        command: string;
+        cwd?: string;
+        env?: Record<string, string>;
+        stdin?: string;
+        sessionId?: string;
+    }, any> | Tool<{
+        path: string;
+        sessionId?: string;
+    }, {
+        cwd: string;
+        sessionId?: string;
+    }> | Tool<{
+        path: string;
+        encoding?: "utf8" | "base64";
+        sessionId?: string;
+    }, {
+        contents: string;
+    }>)[];
+};
+export type TerminalTool = ReturnType<typeof createTerminalTool>;

package/dist/index.js

@@ -0,0 +1,291 @@
+import { randomUUID } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { exec as cpExec } from 'node:child_process';
+import { promisify } from 'node:util';
+import { minimatch } from 'minimatch';
+import { z } from 'zod';
+const exec = promisify(cpExec);
+export const DEFAULT_CONFIG = {
+    roots: [process.cwd()],
+    capabilities: { read: true, write: false, delete: false, exec: true },
+    commands: {
+        allow: [
+            'pwd',
+            'ls',
+            'cat',
+            'head',
+            'tail',
+            'stat',
+            'wc',
+            'grep',
+            'find',
+            'echo',
+            'sed',
+            'awk',
+            'cut',
+            'sort',
+            'uniq',
+            'xargs',
+            'node',
+            'npm',
+            'pnpm',
+            'yarn'
+        ],
+        deny: [
+            'sudo',
+            'chmod',
+            'chown',
+            'mount',
+            'umount',
+            'shutdown',
+            'reboot',
+            'dd',
+            'mkfs*',
+            'service',
+            'systemctl',
+            'iptables',
+            'firewall*',
+            'curl *',
+            'wget *'
+        ]
+    },
+    execution: {
+        timeoutMs: 10_000,
+        maxStdoutBytes: 1_000_000,
+        maxStderrBytes: 250_000,
+        shell: 'direct'
+    },
+    sessions: { enabled: true, ttlMs: 120_000, maxPerAgent: 4 }
+};
+// Reusable exports for consumers who want to surface or extend policy
+export const TERMINAL_COMMANDS_ALLOW = Object.freeze([...DEFAULT_CONFIG.commands.allow]);
+export const TERMINAL_COMMANDS_DENY = Object.freeze([...DEFAULT_CONFIG.commands.deny]);
+export function defaultTerminalConfig(overrides) {
+    return {
+        ...DEFAULT_CONFIG,
+        ...overrides,
+        capabilities: { ...DEFAULT_CONFIG.capabilities, ...(overrides?.capabilities ?? {}) },
+        commands: {
+            allow: overrides?.commands?.allow ?? DEFAULT_CONFIG.commands.allow,
+            deny: overrides?.commands?.deny ?? DEFAULT_CONFIG.commands.deny,
+        },
+        execution: { ...DEFAULT_CONFIG.execution, ...(overrides?.execution ?? {}) },
+        sessions: { ...DEFAULT_CONFIG.sessions, ...(overrides?.sessions ?? {}) },
+    };
+}
+function isCommandAllowed(cmd, policy) {
+    const normalized = cmd.trim().replace(/\s+/g, ' ');
+    const verb = normalized.split(' ')[0] ?? '';
+    const candidates = [normalized, verb];
+    const opts = { nocase: true, matchBase: true };
+    const denyHit = policy.deny.some(p => candidates.some(c => minimatch(c, p, opts)));
+    if (denyHit)
+        return false;
+    return policy.allow.some(p => candidates.some(c => minimatch(c, p, opts)));
+}
+function isPathAllowed(absPath, cfg, mode) {
+    const real = path.resolve(absPath);
+    const roots = cfg.roots.map(r => path.resolve(r));
+    const inside = roots.some(r => real === r || real.startsWith(r + path.sep));
+    if (!inside)
+        return false;
+    if (mode !== 'read' && cfg.readOnlyRoots) {
+        const ro = cfg.readOnlyRoots.map(r => path.resolve(r));
+        const inRo = ro.some(r => real === r || real.startsWith(r + path.sep));
+        if (inRo)
+            return false;
+    }
+    return true;
+}
+function extractAbsolutePaths(cmd) {
+    // Very simple token scan: find whitespace-delimited tokens that start with '/'
+    const matches = cmd.match(/(?:^|\s)(\/[\w\-./]+)(?=\s|$)/g) || [];
+    return matches.map(m => m.trim());
+}
+function commandPolicyCheck(args, cfg) {
+    if (!cfg.capabilities.exec)
+        return { allowed: false, reason: 'exec disabled' };
+    if (!isPathAllowed(args.cwd, cfg, 'exec'))
+        return { allowed: false, reason: 'cwd outside roots' };
+    if (!isCommandAllowed(args.command, cfg.commands))
+        return { allowed: false, reason: 'command denied' };
+    // Guard against absolute path escapes: deny any absolute path outside roots
+    const abs = extractAbsolutePaths(args.command);
+    for (const p of abs) {
+        if (!isPathAllowed(p, cfg, 'read')) {
+            return { allowed: false, reason: `absolute path outside roots: ${p}` };
+        }
+    }
+    return { allowed: true };
+}
+export function createTerminalTool(config) {
+    const cfg = defaultTerminalConfig(config);
+    const sessions = new Map();
+    function getSession(id) {
+        if (!id)
+            return undefined;
+        const s = sessions.get(id);
+        if (!s)
+            return undefined;
+        if (Date.now() > s.expiresAt) {
+            sessions.delete(id);
+            return undefined;
+        }
+        return s;
+    }
+    function start_session(args) {
+        const cwd = args?.cwd ? path.resolve(args.cwd) : cfg.roots[0];
+        if (!isPathAllowed(cwd, cfg, 'exec')) {
+            throw new Error('cwd outside allowed roots');
+        }
+        const sessionId = randomUUID();
+        const expiresAt = Date.now() + cfg.sessions.ttlMs;
+        sessions.set(sessionId, { cwd, env: { ...(args?.env ?? {}) }, expiresAt });
+        return { sessionId, expiresAt: new Date(expiresAt).toISOString() };
+    }
+    async function run_command(args) {
+        const session = getSession(args.sessionId);
+        const cwd = path.resolve(args.cwd ?? session?.cwd ?? cfg.roots[0]);
+        const commandStr = args.command;
+        const pre = commandPolicyCheck({ command: commandStr, cwd }, cfg);
+        if (!pre.allowed) {
+            return { exitCode: -1, stdout: '', stderr: '', durationMs: 0, policy: pre, cwd };
+        }
+        const start = Date.now();
+        try {
+            const { stdout: s, stderr: e } = await exec(commandStr, {
+                cwd,
+                env: { ...(session?.env ?? {}), ...(args.env ?? {}) },
+                timeout: cfg.execution.timeoutMs,
+                input: args.stdin
+            });
+            const dur = Date.now() - start;
+            let stdout = s ?? '';
+            let stderr = e ?? '';
+            if (Buffer.byteLength(stdout) > cfg.execution.maxStdoutBytes) {
+                stdout = stdout.slice(-cfg.execution.maxStdoutBytes);
+            }
+            if (Buffer.byteLength(stderr) > cfg.execution.maxStderrBytes) {
+                stderr = stderr.slice(-cfg.execution.maxStderrBytes);
+            }
+            if (session)
+                session.cwd = cwd;
+            return { exitCode: 0, stdout, stderr, durationMs: dur, policy: { allowed: true }, cwd };
+        }
+        catch (err) {
+            const dur = Date.now() - start;
+            const stdout = String(err.stdout ?? '');
+            const stderr = String(err.stderr ?? err.message ?? '');
+            const code = typeof err.code === 'number' ? err.code : -1;
+            return { exitCode: code, stdout, stderr, durationMs: dur, policy: { allowed: true }, cwd };
+        }
+    }
+    function cd(args) {
+        let session = getSession(args.sessionId);
+        // If no valid session is provided, create one anchored at the first root
+        if (!session) {
+            const cwd = cfg.roots[0];
+            const sessionId = randomUUID();
+            const expiresAt = Date.now() + cfg.sessions.ttlMs;
+            session = { cwd, env: {}, expiresAt };
+            sessions.set(sessionId, session);
+            // attach generated id on args for return below
+            args._createdSessionId = sessionId;
+        }
+        const newPath = path.resolve(session.cwd, args.path);
+        if (!isPathAllowed(newPath, cfg, 'exec')) {
+            throw new Error('path outside allowed roots');
+        }
+        session.cwd = newPath;
+        session.expiresAt = Date.now() + cfg.sessions.ttlMs;
+        return { cwd: session.cwd, sessionId: args._createdSessionId ?? args.sessionId };
+    }
+    async function read_file(args) {
+        if (!cfg.capabilities.read)
+            throw new Error('read disabled');
+        const session = getSession(args.sessionId);
+        const cwd = session?.cwd ?? cfg.roots[0];
+        const abs = path.resolve(cwd, args.path);
+        if (!isPathAllowed(abs, cfg, 'read'))
+            throw new Error('path outside allowed roots');
+        const buf = await fs.readFile(abs);
+        const encoding = args.encoding ?? 'utf8';
+        const contents = encoding === 'base64' ? buf.toString('base64') : buf.toString('utf8');
+        return { contents };
+    }
+    const runCommandTool = {
+        name: 'terminalRun',
+        description: [
+            `Run a non-interactive, sandboxed terminal command within allowed roots (${cfg.roots}).`,
+            `Use for listing files (ls), printing files (cat), simple text processing etc. Allowed commands are ${cfg.commands.allow.join(', ')}).`,
+            'Always prefer passing a safe single command. Network and destructive commands are denied by policy.',
+            'Tips: pass cwd to run in a specific folder; use terminalCd first to set a working directory for subsequent calls; prefer terminalReadFile when you only need file contents.'
+        ].join(' '),
+        schema: z.object({
+            command: z.string(),
+            cwd: z.string().optional(),
+            env: z.record(z.string()).optional(),
+            stdin: z.string().optional(),
+            sessionId: z.string().optional()
+        }),
+        handler: async (a, ctx) => {
+            const s = getSession(a.sessionId);
+            const effCwd = path.resolve(a.cwd ?? s?.cwd ?? cfg.roots[0]);
+            const policy = commandPolicyCheck({ command: a.command, cwd: effCwd }, cfg);
+            ctx?.log?.debug?.('[terminalRun] policy', { command: a.command, cwd: effCwd, policy });
+            const res = await run_command(a);
+            ctx?.log?.info?.('[terminalRun] result', {
+                command: a.command,
+                cwd: res.cwd,
+                exitCode: res.exitCode,
+                durationMs: res.durationMs,
+                stdoutBytes: Buffer.byteLength(res.stdout || ''),
+                stderrBytes: Buffer.byteLength(res.stderr || ''),
+                policy: res.policy,
+            });
+            return res;
+        }
+    };
+    const cdTool = {
+        name: 'terminalCd',
+        description: [
+            'Change the working directory for subsequent terminal operations.',
+            'Accepts a path relative to the current directory or absolute within the configured roots.',
+            'If no session exists, creates one and returns sessionId.',
+            'Use before terminalRun when you need to run multiple commands in the same folder.'
+        ].join(' '),
+        schema: z.object({ path: z.string(), sessionId: z.string().optional() }),
+        handler: async ({ path: relPath, sessionId }, ctx) => {
+            const s = getSession(sessionId);
+            const base = s?.cwd ?? cfg.roots[0];
+            const target = path.resolve(base, relPath);
+            const allowed = isPathAllowed(target, cfg, 'exec');
+            ctx?.log?.debug?.('[terminalCd] request', { base, path: relPath, target, allowed });
+            const res = cd({ path: relPath, sessionId });
+            ctx?.log?.info?.('[terminalCd] result', res);
+            return res;
+        }
+    };
+    const readFileTool = {
+        name: 'terminalReadFile',
+        description: [
+            'Read a small text file from the sandboxed workspace.',
+            'Prefer this instead of running `cat` when you only need file contents.',
+            'Path must be inside allowed roots; returns UTF-8 text by default.'
+        ].join(' '),
+        schema: z.object({ path: z.string(), encoding: z.enum(['utf8', 'base64']).optional(), sessionId: z.string().optional() }),
+        handler: async (a, ctx) => {
+            const s = getSession(a.sessionId);
+            const base = s?.cwd ?? cfg.roots[0];
+            const abs = path.resolve(base, a.path);
+            const allowed = isPathAllowed(abs, cfg, 'read');
+            ctx?.log?.debug?.('[terminalReadFile] request', { base, path: a.path, abs, allowed });
+            const res = await read_file(a);
+            ctx?.log?.info?.('[terminalReadFile] result', { abs, bytes: Buffer.byteLength(res.contents || ''), encoding: a.encoding || 'utf8' });
+            return res;
+        }
+    };
+    // Do not expose start_session as a tool by default to keep the model API simple.
+    return { start_session, run_command, cd, read_file, tools: [runCommandTool, cdTool, readFileTool] };
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@sisu-ai/tool-terminal",
+  "version": "1.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -b"
+  },
+  "dependencies": {
+    "minimatch": "^9.0.3",
+    "zod": "^3.23.8"
+  },
+  "peerDependencies": {
+    "@sisu-ai/core": "1.0.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/finger-gun/sisu",
+    "directory": "packages/tools/terminal"
+  },
+  "homepage": "https://github.com/finger-gun/sisu#readme",
+  "bugs": {
+    "url": "https://github.com/finger-gun/sisu/issues"
+  }
+}