{"_id":"@agent-smith/feat-shell","_rev":"4-b35c11fe6fedc446ad3c0f950262bcf8","name":"@agent-smith/feat-shell","dist-tags":{"latest":"0.0.5"},"versions":{"0.0.2":{"name":"@agent-smith/feat-shell","version":"0.0.2","license":"MIT","_id":"@agent-smith/feat-shell@0.0.2","maintainers":[{"name":"synw","email":"synwx@protonmail.com"}],"homepage":"https://github.com/synw/agent-smith#readme","bugs":{"url":"https://github.com/synw/agent-smith/issues"},"dist":{"shasum":"62531fd0bf74e17523fd8c4269211459308e0393","tarball":"https://registry.npmjs.org/@agent-smith/feat-shell/-/feat-shell-0.0.2.tgz","fileCount":6,"integrity":"sha512-gc2+oDOj6Ko2q1nztAJLzBqw2iAIGU/z1kaUDPxD950sI+g3jO0G//J0x0w1Ku0WpNHGshX0vZT1P0+cdQYZ/Q==","signatures":[{"sig":"MEQCIED1RI1t3uHveoGGEDvfqhjWwIjMHwWEsfjoODeO1dpFAiACuKoxHX4kKJD8J5K19ouMAJTum/tnhL8M05iVXPe3dQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":13636},"type":"module","gitHead":"dab34885a0d54063281f113e249220188e1e953a","scripts":{"build":"tsc"},"_npmUser":{"name":"synw","email":"synwx@protonmail.com"},"repository":{"url":"git+https://github.com/synw/agent-smith.git","type":"git"},"_npmVersion":"11.13.0","description":"Shell features for Agent Smith cli","directories":{},"_nodeVersion":"24.11.0","dependencies":{"@agent-smith/core":"^0.0.3","@boxlite-ai/boxlite":"^0.9.5"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"devDependencies":{"tslib":"^2.8.1","typescript":"^6.0.3","@types/node":"^25.9.3"},"_npmOperationalInternal":{"tmp":"tmp/feat-shell_0.0.2_1781272401596_0.8700205860742307","host":"s3://npm-registry-packages-npm-production"}},"0.0.3":{"name":"@agent-smith/feat-shell","version":"0.0.3","license":"MIT","_id":"@agent-smith/feat-shell@0.0.3","maintainers":[{"name":"synw","email":"synwx@protonmail.com"}],"homepage":"https://github.com/synw/agent-smith#readme","bugs":{"url":"https://github.com/synw/agent-smith/issues"},"dist":{"shasum":"53af98ffc9b6011af80b36805ca2be5c808ebbba","tarball":"https://registry.npmjs.org/@agent-smith/feat-shell/-/feat-shell-0.0.3.tgz","fileCount":7,"integrity":"sha512-ccx63SyIAxNDsm6dObhqTzcvgqIIGQSkIOYSiwzUscpGepHQSBnEDmRM2ui12dco3eyqJVp8S0p2tcjF0QdD9g==","signatures":[{"sig":"MEUCIGBW2IgjjMuzUdgp5mjBcSGB2WSoIrmG/t/WqaVSucTJAiEAyq5zOnyt0dCGE7rVPsof/if4RGt8CaFge+v17fEM4CI=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":22743},"type":"module","gitHead":"021193886df56e803d347b7ad1cc8de8b1d2810f","scripts":{"build":"tsc"},"_npmUser":{"name":"synw","email":"synwx@protonmail.com"},"repository":{"url":"git+https://github.com/synw/agent-smith.git","type":"git"},"_npmVersion":"11.18.0","description":"Shell features for Agent Smith cli","directories":{},"_nodeVersion":"24.11.0","dependencies":{"@boxlite-ai/boxlite":"^0.9.7"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"devDependencies":{"tslib":"^2.8.1","typescript":"^7.0.2","@types/node":"^26.1.2"},"_npmOperationalInternal":{"tmp":"tmp/feat-shell_0.0.3_1785838980674_0.9822878744296584","host":"s3://npm-registry-packages-npm-production"}},"0.0.4":{"name":"@agent-smith/feat-shell","version":"0.0.4","license":"MIT","_id":"@agent-smith/feat-shell@0.0.4","maintainers":[{"name":"synw","email":"synwx@protonmail.com"}],"homepage":"https://github.com/synw/agent-smith#readme","bugs":{"url":"https://github.com/synw/agent-smith/issues"},"dist":{"shasum":"c72079d9732d533f5f6c35d033812fc900d4f5f8","tarball":"https://registry.npmjs.org/@agent-smith/feat-shell/-/feat-shell-0.0.4.tgz","fileCount":7,"integrity":"sha512-vN3c2XtpzaVM3Y81lBSf2pToLKUOXp+YpDB3jyvl/2SfToI/k2XKjHuOK7xJ4SYjXtNqb+R30cG9YgWJnZkxKA==","signatures":[{"sig":"MEQCICJY6aC/MA0RhPe04fvK2rIDT0DY+SS6RiNkn6C88iQdAiBMW4oY4q6NGKcqTWHl+8Mww97aiIsv3y+oFl5OKY2ZYA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":22819},"type":"module","gitHead":"47151f444f4b2375526d0449ab28d6c432bf0de9","scripts":{"build":"tsc"},"_npmUser":{"name":"synw","email":"synwx@protonmail.com"},"repository":{"url":"git+https://github.com/synw/agent-smith.git","type":"git"},"_npmVersion":"11.18.0","description":"Shell features for Agent Smith cli","directories":{},"_nodeVersion":"24.11.0","dependencies":{"@boxlite-ai/boxlite":"^0.9.7"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"devDependencies":{"tslib":"^2.8.1","typescript":"^7.0.2","@types/node":"^26.1.2"},"_npmOperationalInternal":{"tmp":"tmp/feat-shell_0.0.4_1787313268064_0.44895874740106434","host":"s3://npm-registry-packages-npm-production"}},"0.0.5":{"_id":"@agent-smith/feat-shell@0.0.5","bugs":{"url":"https://github.com/synw/agent-smith/issues"},"dist":{"shasum":"1d7ed7d2a154a50eab2f125a55675b3a2d3bef72","tarball":"https://registry.npmjs.org/@agent-smith/feat-shell/-/feat-shell-0.0.5.tgz","fileCount":8,"integrity":"sha512-tLNlRH1NwvEIEsMVIcWfgh/4VcQQp2xFxFv4IrS4JWX4Q8pmGhN4pe1zVkYbekusIClaPhAT26laobYC3jN6Ng==","signatures":[{"sig":"MEYCIQCDHN8DCgKTA+4+94z6GkKJTWP7KKy+0Fl4vCy/03RppAIhAN3U+H5Pib+G4XoXvNmY5LKAo+xCrDYslhw+7X4qGnUc","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIBm4rR1fePY4l6m8U9Q8cxyYvoC6bpXjSapbcNUxyfj4AiBhWpqRFxMDykiUUAPTANFSnGKj5IO3svRJc+sEk96MFg=="}],"unpackedSize":22902},"name":"@agent-smith/feat-shell","type":"module","gitHead":"3ec4e27c24886b126b8fb872c99c9d851de87514","license":"MIT","scripts":{"build":"tsc"},"version":"0.0.5","_npmUser":{"name":"synw","email":"synwx@protonmail.com"},"homepage":"https://github.com/synw/agent-smith#readme","repository":{"url":"git+https://github.com/synw/agent-smith.git","type":"git"},"_npmVersion":"11.18.0","description":"Shell features for Agent Smith cli","directories":{},"maintainers":[{"name":"synw","email":"synwx@protonmail.com"}],"_nodeVersion":"24.11.0","dependencies":{"@boxlite-ai/boxlite":"^0.9.7"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"devDependencies":{"tslib":"^2.8.1","typescript":"^7.0.2","@types/node":"^26.1.2"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/feat-shell_0.0.5_1789560622179_0.7140032918778181"}}},"time":{"created":"2026-06-12T13:53:21.454Z","modified":"2026-09-16T12:10:22.468Z","0.0.2":"2026-06-12T13:53:21.758Z","0.0.3":"2026-08-04T10:23:00.873Z","0.0.4":"2026-08-21T11:54:28.194Z","0.0.5":"2026-09-16T12:10:22.277Z"},"bugs":{"url":"https://github.com/synw/agent-smith/issues"},"license":"MIT","homepage":"https://github.com/synw/agent-smith#readme","repository":{"url":"git+https://github.com/synw/agent-smith.git","type":"git"},"description":"Shell features for Agent Smith cli","maintainers":[{"name":"synw","email":"synwx@protonmail.com"}],"readme":"# @agent-smith/feat-shell\n\n[](https://www.npmjs.com/package/@agent-smith/feat-shell)\n\n**Sandboxed shell command execution and AI-powered shell command generation for the Agent Smith toolkit.**\n\nPart of the [Agent Smith](https://github.com/lynxai-team/agent-smith) CLI framework — secure, containerized command execution with AI assistance.\n\n## Features\n\n- 🛡️ **Sandboxed Execution** — All commands run in isolated Docker containers preventing host system access\n- 🔒 **Read-Only Mode** — Safe file inspection with `rshell` using readonly workspace mounts\n- 🐍 **Python Isolation** — Execute Python code in dedicated `python:slim` containers with pip support\n- 🦾 **Go Execution** — Run Go commands in isolated `cimg/go:1.25-node` containers\n- 🤖 **AI Command Generation** — Shell agent with qwen4b model for intelligent command execution\n- ♻️ **Container Reuse** — Efficient container lifecycle management with graceful shutdown\n- 🔗 **Workspace Integration** — Host workspace mounted at `/workspace` inside containers\n\n## Documentation\n\n### For AI Agents\n- [Codebase Summary](.agents/documentation/codebase-summary.md) — Architecture, key files, and patterns for the @agent-smith/feat-shell plugin\n- [Shell Plugin Documentation](https://raw.githubusercontent.com/lynxai-team/agent-smith/refs/heads/main/docsite/public/doc/plugins/9.shell.md) — Complete plugin reference with tools, agents, and security guarantees\n\n### For Humans\n- [Shell Plugin](https://lynxai-team.github.io/agent-smith/plugins/shell) — Overview and usage guide for the shell plugin\n\n## Installation\n\n```bash\nnpm i -g @agent-smith/feat-shell\n```\n\nAdd the plugin to your `config.yml` file:\n\n```yaml\nplugins:\n - \"@agent-smith/feat-shell\"\n```\n\nThen run the configuration command:\n\n```bash\nlm conf\n```\n\n## Quick Start\n\n### Execute a Shell Command\n\nUse the shell tool to run commands in a sandboxed Alpine Linux container:\n\n```typescript\nconst result = await agent.run(\"List all files in /workspace\", {\n toolsList: [\"shell\"],\n variables: { workspace: \"/path/to/project\" }\n});\n```\n\n### Safe File Inspection (Read-Only)\n\nUse the rshell tool for read-only operations — perfect for listing files or inspecting content without risk of modification:\n\n```typescript\nconst result = await agent.run(\"Check file permissions\", {\n toolsList: [\"rshell\"],\n variables: { workspace: \"/path/to/project\" }\n});\n```\n\n### Run Python Code\n\nUse the python tool to execute Python scripts with optional package installation:\n\n```typescript\nconst result = await agent.run(\"Analyze data\", {\n toolsList: [\"python\"],\n variables: { workspace: \"/path/to/project\" },\n packages: \"pandas,numpy\",\n code: `import pandas as pd\\ndf = pd.read_csv('/workspace/data.csv')\\nprint(df.head())`\n});\n```\n\n## Usage\n\n### Shell Execution Tools\n\n| Tool | Description | Container Image | Workspace Mount |\n|------|-------------|-----------------|-----------------|\n| `shell` | Execute arbitrary shell commands | `timbru31/node-alpine-git` | Read-write at `/workspace` |\n| `rshell` | Execute read-only shell commands | `timbru31/node-alpine-git` | Read-only at `/workspace` |\n| `python` | Execute Python code with pip support | `python:slim` | Read-write at `/workspace` |\n| `goshell` | Execute Go commands | `cimg/go:1.25-node` | Read-write at `/workspace` |\n\n### Shell Tools — Detailed Usage\n\n#### `shell` — Execute Shell Commands\n\nRuns arbitrary shell commands in an Alpine Linux container with Node.js and Git pre-installed:\n\n```typescript\nimport { Agent, Lm } from \"@agent-smith/agent\";\n\nconst lm = new Lm({ serverUrl: \"http://localhost:8080/v1\" });\nconst agent = new Agent({\n lm,\n onToken: (t) => process.stdout.write(t),\n});\n\nconst result = await agent.run(\"Find all TypeScript files in the project\", {\n toolsList: [\"shell\"],\n variables: { workspace: \"/workspace/my-project\" },\n model: \"qwen4b\",\n params: { temperature: 0.3, max_tokens: 1024 }\n});\n```\n\nThe tool requires a `workspace` or `path` variable to mount the host directory into the container.\n\n#### `rshell` — Execute Read-Only Shell Commands\n\nIdentical to `shell` but mounts the workspace volume in **read-only** mode, preventing any file modifications:\n\n```typescript\nconst result = await agent.run(\"List directory contents and check permissions\", {\n toolsList: [\"rshell\"],\n variables: { workspace: \"/workspace/my-project\" },\n model: \"qwen4b\",\n params: { temperature: 0.3, max_tokens: 1024 }\n});\n```\n\nUse `rshell` when you need to inspect files or run diagnostic commands without risk of accidental changes.\n\n#### `python` — Execute Python Code\n\nRuns Python code in a dedicated `python:slim` container with optional pip package installation:\n\n```typescript\nconst result = await agent.run(\"Process data with pandas\", {\n toolsList: [\"python\"],\n variables: { workspace: \"/workspace/my-project\" },\n packages: \"pandas,requests\",\n code: `\nimport pandas as pd\ndf = pd.read_csv('/workspace/data.csv')\nprint(f\"Rows: {len(df)}, Columns: {len(df.columns)}\")\nprint(df.describe())\n`,\n model: \"qwen4b\",\n params: { temperature: 0.3, max_tokens: 2048 }\n});\n```\n\n**Parameters:**\n- `code` (required) — The Python code to execute\n- `packages` (optional) — Comma-separated list of pip packages to install before running the code\n\n#### `goshell` — Execute Go Commands\n\nRuns shell commands in a Go development container with Go 1.25 and Node.js:\n\n```typescript\nconst result = await agent.run(\"Build the Go project\", {\n toolsList: [\"goshell\"],\n variables: { workspace: \"/workspace/my-go-project\" },\n model: \"qwen4b\",\n params: { temperature: 0.3, max_tokens: 1024 }\n});\n```\n\n### AI Shell Agent\n\nThe plugin provides a pre-configured shell agent (`shellagent`) using the qwen4b model:\n\n```yaml\ndescription: Shell agent\ncategory: system/shell\nmodel: qwen4b\ninferParams:\n min_p: 0\n top_k: 40\n top_p: 0.95\n temperature: 0.7\nctx: 32768\nvariables:\n required:\n workspace:\n description: The local directory path where to operate\ntoolsList:\n - shell\n```\n\nUsage in an agent workflow:\n\n```typescript\nconst result = await agent.run(\"Explore the project structure and report findings\", {\n toolsList: [\"shellagent\"],\n variables: { workspace: \"/workspace/my-project\" },\n model: \"qwen4b\",\n params: { temperature: 0.5, max_tokens: 4096 }\n});\n```\n\nThe shell agent intelligently decides which commands to run and can chain multiple operations together.\n\n### Debug Mode\n\nEnable debug output to see container lifecycle events:\n\n```typescript\nconst result = await agent.run(\"List files\", {\n toolsList: [\"shell\"],\n variables: { workspace: \"/workspace/my-project\" },\n debug: true // prints container open/close events\n});\n```\n\n### Error Handling\n\nAll tools return structured output with exit codes, stdout, and stderr:\n\n```typescript\ntry {\n const result = await agent.run(\"Run a command\", {\n toolsList: [\"shell\"],\n variables: { workspace: \"/workspace/my-project\" }\n });\n // Result format:\n // [Exit code]: 0\n // [Stdout]: ...\n // [Stderr]: ...\n} catch (err) {\n console.error(\"Shell execution failed:\", err.message);\n}\n```\n\nCommon error cases:\n- **Missing workspace**: Returns `[Error]: shell tool missing path or workspace parameter`\n- **Timeout**: Commands running longer than 60 seconds are killed automatically\n- **Container errors**: Exit code and error message are included in the result output\n\n## Complete Example\n\n```typescript\nimport { Agent, Lm } from \"@agent-smith/agent\";\n\nasync function exploreProject(workspace: string) {\n const lm = new Lm({ serverUrl: \"http://localhost:8080/v1\" });\n const agent = new Agent({\n lm,\n onToken: (t) => process.stdout.write(t),\n onError: (err) => { throw new Error(err.message); },\n });\n\n // Use the shell agent to explore the project structure\n const result = await agent.run(\n \"Explore the project: list top-level files, check for package.json, \" +\n \"and report the project type and dependencies\",\n {\n toolsList: [\"shellagent\"],\n variables: { workspace },\n model: \"qwen4b\",\n params: { stream: true, temperature: 0.4, top_k: 20, max_tokens: 4096 },\n }\n );\n\n return result;\n}\n\n// Usage\nexploreProject(\"/workspace/my-project\").then(console.log).catch(console.error);\n```\n\n## API Reference\n\n### Tool Definitions\n\n#### `shell` — Execute Shell Commands\n\n```typescript\n{\n name: \"shell\",\n description: \"Execute shell commands\",\n arguments: {\n command: {\n description: \"The shell command to execute\",\n required: true,\n type: \"string\"\n }\n },\n parallelCalls: false\n}\n```\n\n#### `rshell` — Execute Read-Only Shell Commands\n\n```typescript\n{\n name: \"rshell\",\n description: \"Execute read only shell commands\",\n arguments: {\n command: {\n description: \"The shell command to execute (read-only operations)\",\n required: true,\n type: \"string\"\n }\n },\n parallelCalls: false\n}\n```\n\n#### `python` — Execute Python Code\n\n```typescript\n{\n name: \"python\",\n description: \"Execute some Python code using the python command\",\n arguments: {\n packages: {\n description: \"A list of packages to be install (optional): example: requests,numpy\",\n type: \"string\"\n },\n code: {\n description: \"The code to execute\",\n required: true,\n type: \"string\"\n }\n }\n}\n```\n\n### Return Value Format\n\nAll shell tools return a structured string:\n\n```\n[Exit code]: \n[Stdout]: