@struktoai/mirage-claude-managed-agents 0.0.8-alpha.1 → 0.0.8

package/README.md

@@ -5,6 +5,14 @@
       <img src="https://raw.githubusercontent.com/strukto-ai/mirage/main/assets/mirage-header-light.svg" width="100%" alt="Mirage: A Virtual Terminal for AI Agents" />
     </picture>
   </a>
+  <a href="https://agentvfs.org">
+    <picture>
+      <source media="(max-width: 767px) and (prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/strukto-ai/mirage/main/assets/agentvfs-banner-narrow-dark.svg">
+      <source media="(max-width: 767px)" srcset="https://raw.githubusercontent.com/strukto-ai/mirage/main/assets/agentvfs-banner-narrow-light.svg">
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/strukto-ai/mirage/main/assets/agentvfs-banner-dark.svg">
+      <img src="https://raw.githubusercontent.com/strukto-ai/mirage/main/assets/agentvfs-banner-light.svg" width="100%" alt="AgentVFS: the open, vendor-neutral virtual filesystem interface for AI agents" />
+    </picture>
+  </a>
 </h1>
 
 <p align="center">
@@ -16,6 +24,8 @@
         <img src="https://img.shields.io/badge/made by-strukto.ai-0C0C0C?labelColor=F0ECE2" /></a>
     <a href="https://github.com/strukto-ai/mirage/blob/main/LICENSE" alt="License">
         <img src="https://img.shields.io/badge/license-Apache--2.0-0C0C0C?labelColor=F0ECE2" /></a>
+    <a href="https://doi.org/10.5281/zenodo.23504502" alt="DOI">
+        <img src="https://img.shields.io/badge/DOI-10.5281%2Fzenodo.23504502-0C0C0C?labelColor=F0ECE2" alt="DOI 10.5281/zenodo.23504502" /></a>
     <a href="https://discord.gg/u8BPQ65KsS" alt="Discord">
         <img src="https://img.shields.io/badge/discord-join-0C0C0C?labelColor=F0ECE2&logo=discord&logoColor=0C0C0C" /></a>
     <br/>
@@ -40,7 +50,7 @@
   <a href="https://github.com/strukto-ai/mirage/blob/main/readme/README.ko.md"><img alt="README 한국어" src="https://img.shields.io/badge/%ED%95%9C%EA%B5%AD%EC%96%B4-F0ECE2"></a>
 </p>
 
-Mirage is **a Virtual Terminal for AI Agents**. The virtual filesystem delivers broad data context, virtualized CLIs give an agent more flexibility on tool use, dynamic runtimes save underlying infrastructure cost and are more token efficient, and fine-grained control over an agent's actions and even over what it can see gives the best security. Together these parts form one virtualized terminal, giving the best agent performance, cost efficiency and security.
+Mirage is **a Virtual Terminal for AI Agents**: one shell over data, CLIs and runtimes. Unix tools reach every service, and `grep` runs on each service's own search, such as Gmail's or Slack's. Mirage routes each command to the runtime that fits it, so most lines run in-process and only heavy work reaches a sandbox, which cuts infrastructure cost and tokens. The terminal itself is light: a workspace takes **about 100 KB** of memory and each new session **about 10 KB**, so one process serves many agents at once. Profiles decide what an agent can run and even what it can see, and scriptable policies refuse anything those rules cannot express.
 
 <p align="center">
   <picture>
@@ -54,24 +64,56 @@ Here is an example of launching Mirage inside an application:
 ```python
 ws = Workspace(
     {
-        "/tmp":   (RAMVFS(), MountMode.EXEC),
-        "/redis": (RedisVFS(url=redis_url), MountMode.WRITE),
+        "/s3":    (S3VFS(S3Config(bucket="my-bucket")), MountMode.WRITE),
         "/slack": (SlackVFS(SlackConfig(token=slack_bot_token)), MountMode.EXEC),
+        "/gmail": (GmailVFS(GmailConfig(**google_credentials)), MountMode.READ),
     },
-    # monty captures python, so scripts run sandboxed inside the workspace
-    runtimes=[MontyRuntime(captures=["python", "python3"]), "workspace"],
+    # Install the Slack CLI, run by name and listed by `man` and `which` like any program
+    clis={"slack": (SLACK, {"token": slack_bot_token})},
+    # the analyst profile hides /s3/secrets and denies posting to Slack and curl
+    profiles={
+        "analyst": {
+            "paths": {"hide": ["/s3/secrets"]},
+            "commands": {"deny": ["slack send-message", "curl"]},
+        },
+    },
+    runtimes=[
+        MontyRuntime(captures=["python", "python3"]),
+        E2BRuntime(
+            captures=["python", "python3"],
+            config={"sandbox_id": sandbox_id, "mount_type": "ssh"},
+        ),
+    ],
+    # route the underlying computation: numpy lines run in the e2b sandbox, the rest on monty
+    route_policy=lambda ctx: "e2b" if "numpy" in ctx.line else None,
 )
 
-# one grep sweeps every source
-await ws.shell("grep -rln session /redis /tmp")
+# Add an agent using the analyst profile
+alice = await ws.session("alice", profile="analyst")
+
+# one grep sweeps S3, Slack and Gmail, on each service's own search where it has one
+await alice.shell("grep -rlw invoice /s3 /slack /gmail")
 
-# run a script that lives in Slack, file the report into Redis
-await ws.shell("python3 /slack/channels/general_.../files/example__F....py > /redis/report.txt")
+# run a script that lives in Slack on monty, file the report into S3
+await alice.shell("python3 /slack/channels/general__C0123/2026-10-21/files/report__F0456.py > /s3/report.txt")
 
-# install a typed CLI under a head word: dispatched by name, not by path,
-# and discoverable through `man`, `type` and `which` like any other program
-ws.register_cli("slack", SLACK, {"token": slack_bot_token})
-await ws.shell('slack send-message --channel general --text "report is up"')
+# numpy is not in monty, so the route policy sends this line to e2b
+await alice.shell("python3 -c 'import numpy; print(numpy.arange(10).sum())'")
+```
+
+And what `alice` sees in the shell:
+
+```console
+$ grep -rlw invoice /s3 /slack /gmail
+/s3/billing/2026-10.csv
+/gmail/INBOX/2026-10-21/Invoice_1042__18f3a9c2b7d1e0f4.gmail.json
+$ ls /s3
+billing
+report.txt
+$ cat /s3/secrets/aws.txt
+cat: /s3/secrets/aws.txt: No such file or directory
+$ slack send-message --channel general --text "report is up"
+slack: Permission denied
 ```
 
 ## About
@@ -81,6 +123,7 @@ await ws.shell('slack send-message --channel general --text "report is up"')
 - **Virtual command line tools (CLIs).** `git`, `slack` and `ntn` are answered by Mirage itself, so an agent drives the service with nothing installed, across different runtimes and machines, and one tool can be virtualized into two or more, each under its own name with its own credentials.
 - **Routed, dynamic runtimes.** Python, JavaScript and any other command can be sent to a configured runtime, in process, sandboxed or remote, which decouples computation from storage and lets either change without touching the other.
 - **The virtualized Mirage shell.** It binds the filesystem, the CLIs and the runtimes into one command line, so pipes, redirection, variables, jobs and history work across all three.
+- **Lightweight by design.** A workspace, the virtual terminal itself, takes about 100 KB of memory and each new session about 10 KB, so one process serves many agents without a container or VM per agent.
 - **Profiles designed for agents.** `allow`, `ask` and `deny` govern commands and CLIs, while `hide` and `show` govern files and folders, so a hidden path is not merely unreadable but absent from the filesystem the agent sees.
 - **A scriptable policy engine.** A policy script can prohibit any dangerous action before it runs, and the same stack gates every VFS op and session write, so neither a file nor an environment variable leaks.
 - **Notifications wired into the VFS and agents.** External changes become an event stream on the mount, so a new Slack reply surfaces as a change to the chat file in the virtual filesystem, and the agent reacts to it instead of rescanning the tree.
@@ -158,8 +201,8 @@ in Mirage can resolve straight to a credential held in one of them.
 
 ## Installation
 
-- **Python** ≥ 3.11 for the `mirage-ai` package and the `mirage` CLI
-- **Node.js** ≥ 20 for the TypeScript SDK
+- **Python** ≥ 3.12 for the `mirage-ai` package and the `mirage` CLI
+- **Node.js** 22.20+ on Node 22, 24.12+ on Node 24, or 25+ for the TypeScript SDK
 
 ### Python
 
@@ -181,58 +224,109 @@ Both runtime packages pull in `@struktoai/mirage-core` automatically.
 ### CLI
 
 ```bash
-curl -fsSL https://strukto.ai/mirage/install.sh | sh
-# or
 npm install -g @struktoai/mirage-cli
 # or
-uvx mirage-ai
+uvx --from mirage-ai mirage
 # or
 npx @struktoai/mirage-cli
 ```
 
-## Quickstart
+To get started, see the quickstarts for
+[Python](https://docs.mirage.strukto.ai/python/quickstart),
+[TypeScript](https://docs.mirage.strukto.ai/typescript/quickstart) and the
+[CLI](https://docs.mirage.strukto.ai/home/access/cli).
 
-### Python
+## Scriptable Policy
+
+A profile can name policy scripts for what its rules cannot express. A script
+reads the command as JSON, can open the files it names, and prints a deny, an
+ask or nothing. This one disables `rm`, and a Python script whose code
+deletes files:
 
 ```python
-from mirage import Workspace
-from mirage.vfs.ram import RAMVFS
-from mirage.vfs.s3 import S3Config, S3VFS
+import json, os
 
-ws = Workspace({
-    "/data": RAMVFS(),
-    "/s3":   S3VFS(S3Config(bucket="my-bucket")),
-})
+ctx = json.loads(os.environ["MIRAGE_POLICY_CTX"])
 
-await ws.shell("cp /s3/report.csv /data/report.csv")
-await ws.shell("grep alert /s3/data/log.jsonl | wc -l")
 
-await ws.snapshot("demo.tar")
-```
+def deletes(path):
+    try:
+        code = open(path).read()
+    except OSError:
+        return False
+    return any(call in code for call in ("os.remove", "os.unlink", "shutil.rmtree"))
 
-### TypeScript
 
-```ts
-import { Workspace, RAMVFS, S3VFS } from '@struktoai/mirage-node'
+if ctx["command"] == "rm" or (
+    ctx["command"].startswith("python") and any(deletes(p) for p in ctx["paths"])
+):
+    print(json.dumps({"kind": "deny", "reason": "deleting files is disabled"}))
+```
 
-const ws = new Workspace({
-  '/data': new RAMVFS(),
-  '/s3': new S3VFS({ bucket: 'my-bucket' }),
-})
+Register it in a profile, here to run on Monty before every command:
 
-await ws.shell('cp /s3/report.csv /data/report.csv')
-await ws.shell('grep alert /s3/data/log.jsonl | wc -l')
+```python
+ws = Workspace(
+    {"/s3": (S3VFS(S3Config(bucket="my-bucket")), MountMode.WRITE)},
+    profiles={
+        "analyst": {
+            "policy": {
+                "pre_command": [{"script": ScriptSource(Path("guard.py").read_text()), "runtime": "monty"}],
+            },
+        },
+    },
+    profile="analyst",
+)
+```
 
-await ws.snapshot('demo.tar')
+```console
+$ cat /s3/clean.py
+import os
+os.remove("/s3/report.txt")
+$ rm /s3/report.txt
+rm: Permission denied
+$ python3 /s3/clean.py
+python3: Permission denied
 ```
 
-### CLI
+See [policy scripts](https://docs.mirage.strukto.ai/home/policy/scripts) for
+the other stages a script can answer at.
+
+## Embedded Terminal
+
+Most of the time an agent does not need a sandbox, only a terminal-like
+interface, and Mirage embeds one in an application server. Each terminal is a
+Mirage session with its own working directory, environment and history, and Python
+runs in-process on Monty, so a terminal starts with no container or VM. Here
+it is in Express; the FastAPI version is in the
+[docs](https://docs.mirage.strukto.ai/home/examples/embedded-terminal).
 
 ```bash
-mirage workspace create ws.yaml --id demo
-mirage shell --workspace_id demo --command "cp /s3/report.csv /data/report.csv"
-mirage workspace snapshot demo demo.tar
-mirage workspace load demo.tar --id demo-restored
+npm install @struktoai/mirage-node @pydantic/monty express
+```
+
+```ts
+import express from 'express'
+import { MontyRuntime, MountMode, RAMVFS, Workspace } from '@struktoai/mirage-node'
+
+const ws = new Workspace(
+  { '/work': new RAMVFS() },
+  { mode: MountMode.EXEC, runtimes: [new MontyRuntime({ captures: ['python', 'python3'] })] },
+)
+const app = express()
+app.use(express.json())
+
+app.post('/sessions/:id', (req, res) => {
+  ws.createSession(req.params.id)
+  res.sendStatus(201)
+})
+
+app.post('/sessions/:id/run', async (req, res) => {
+  const r = await ws.shell(req.body.command, { sessionId: req.params.id })
+  res.json({ stdout: r.stdoutText, stderr: r.stderrText, exitCode: r.exitCode })
+})
+
+app.listen(3000, '127.0.0.1')
 ```
 
 ## Contributors

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@struktoai/mirage-claude-managed-agents",
-  "version": "0.0.8-alpha.1",
+  "version": "0.0.8",
   "description": "Make a Mirage workspace the self-hosted environment of an agent on Claude Managed Agents",
   "keywords": [
     "mirage",
@@ -38,21 +38,21 @@
     "dist"
   ],
   "dependencies": {
-    "@struktoai/mirage-core": "0.0.8-alpha.1"
+    "@struktoai/mirage-core": "0.0.8"
   },
   "peerDependencies": {
-    "@anthropic-ai/sdk": "^0.124.0"
+    "@anthropic-ai/sdk": ">=0.124.0 <2"
   },
   "devDependencies": {
-    "@anthropic-ai/sdk": "^0.124.0",
+    "@anthropic-ai/sdk": "^1.3.0",
     "@types/node": "^22.0.0",
     "tsup": "^8.5.0",
     "typescript": "^6.0.0",
-    "vitest": "^4.1.11",
-    "@struktoai/mirage-node": "0.0.8-alpha.1"
+    "vitest": "^4.1.12",
+    "@struktoai/mirage-node": "0.0.8"
   },
   "scripts": {
-    "build": "tsup",
+    "build": "tsup --config ../../tsup.base.config.ts",
     "test": "vitest run",
     "typecheck": "tsc --noEmit"
   }