{"_id":"@cogineai/mafs-agents","name":"@cogineai/mafs-agents","dist-tags":{"alpha":"0.1.0-alpha.0","latest":"0.1.0-alpha.0"},"versions":{"0.1.0-alpha.0":{"name":"@cogineai/mafs-agents","version":"0.1.0-alpha.0","description":"A Unified Virtual Filesystem For AI Agents","keywords":["bash","fuse","typescript","vfs","ai-agents","agent-sandbox","langchain","virtual-filesystem","llm-agents","agent-tools","claude-code","openai-agents"],"homepage":"https://github.com/cogine-ai/CogineX-mono#readme","bugs":{"url":"https://github.com/cogine-ai/CogineX-mono/issues"},"repository":{"type":"git","url":"git+https://github.com/cogine-ai/CogineX-mono.git","directory":"packages/mafs/typescript/packages/agents"},"license":"Apache-2.0","author":{"name":"lc708","email":"kiedis@foxmail.com"},"publishConfig":{"access":"public"},"type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./openai":{"types":"./dist/openai/index.d.ts","import":"./dist/openai/index.js"},"./langchain":{"types":"./dist/langchain/index.d.ts","import":"./dist/langchain/index.js"},"./pi":{"types":"./dist/pi/index.d.ts","import":"./dist/pi/index.js"},"./vercel":{"types":"./dist/vercel/index.d.ts","import":"./dist/vercel/index.js"},"./mastra":{"types":"./dist/mastra/index.d.ts","import":"./dist/mastra/index.js"}},"dependencies":{"picomatch":"^4.0.4","@cogineai/mafs-core":"0.1.0-alpha.0"},"peerDependencies":{"@mariozechner/pi-ai":"^0.70.0","@mariozechner/pi-coding-agent":"^0.70.0","@mastra/core":"^1.29.0","@openai/agents":"^0.8.0","ai":"^6.0.0","deepagents":"^1.9.0","zod":"^4.0.0"},"devDependencies":{"@mariozechner/pi-ai":"^0.70.2","@mariozechner/pi-coding-agent":"^0.70.2","@mastra/core":"^1.29.1","@openai/agents":"^0.8.0","@types/picomatch":"^4.0.3","ai":"^6.0.170","deepagents":"^1.9.0","tsup":"^8.5.0","typescript":"^6.0.0","vitest":"^3.0.0","zod":"^4.0.0","@cogineai/mafs-node":"0.1.0-alpha.0"},"scripts":{"build":"tsup","test":"vitest run","typecheck":"tsc --noEmit"},"_id":"@cogineai/mafs-agents@0.1.0-alpha.0","_integrity":"sha512-z5AwcB/G0/c34iWqpVA9/s50SAQBizFron7m3k4NaBI+W1iYPU4ImnDoHSIQ/NifetU941gS0taH2+Rln2JUeA==","_resolved":"/private/var/folders/w3/1jnv2n65319gjrn7xmghv87m0000gn/T/9320771b44de08db4ffe58ac372fe174/cogineai-mafs-agents-0.1.0-alpha.0.tgz","_from":"file:cogineai-mafs-agents-0.1.0-alpha.0.tgz","_nodeVersion":"22.16.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-z5AwcB/G0/c34iWqpVA9/s50SAQBizFron7m3k4NaBI+W1iYPU4ImnDoHSIQ/NifetU941gS0taH2+Rln2JUeA==","shasum":"f9627e4bf5f94ef5882ae24b6f19ada2f6a0f1b7","tarball":"https://registry.npmjs.org/@cogineai/mafs-agents/-/mafs-agents-0.1.0-alpha.0.tgz","fileCount":23,"unpackedSize":122684,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIDQco8nrRvUWhX5oT+Znw4qtTFpgmXyL32PhET8zw3GBAiEA3NtmmycqtR0HK4dH2tOeNjgTD8SjanTLBSX+oSqHQoU="}]},"_npmUser":{"name":"lc708","email":"kiedis@foxmail.com"},"directories":{},"maintainers":[{"name":"lc708","email":"kiedis@foxmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mafs-agents_0.1.0-alpha.0_1779464755288_0.8218193303814672"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-22T15:45:55.079Z","0.1.0-alpha.0":"2026-05-22T15:45:55.463Z","modified":"2026-05-22T15:45:55.748Z"},"maintainers":[{"name":"lc708","email":"kiedis@foxmail.com"}],"description":"A Unified Virtual Filesystem For AI Agents","homepage":"https://github.com/cogine-ai/CogineX-mono#readme","keywords":["bash","fuse","typescript","vfs","ai-agents","agent-sandbox","langchain","virtual-filesystem","llm-agents","agent-tools","claude-code","openai-agents"],"repository":{"type":"git","url":"git+https://github.com/cogine-ai/CogineX-mono.git","directory":"packages/mafs/typescript/packages/agents"},"author":{"name":"lc708","email":"kiedis@foxmail.com"},"bugs":{"url":"https://github.com/cogine-ai/CogineX-mono/issues"},"license":"Apache-2.0","readme":"# @cogineai/mafs-agents\n\n[![npm version](https://img.shields.io/npm/v/%40cogineai%2Fmafs-agents.svg)](https://www.npmjs.com/package/@cogineai/mafs-agents)\n[![License](https://img.shields.io/npm/l/%40cogineai%2Fmafs-agents.svg)](https://github.com/cogine-ai/CogineX-mono/blob/main/packages/mafs/LICENSE)\n\nAgent-framework adapters for **MAFS — A Unified Virtual File System for AI Agents**.\n\nEach adapter wraps a `Workspace` from [`@cogineai/mafs-core`](../core) (or [`@cogineai/mafs-node`](../node) / [`@cogineai/mafs-browser`](../browser)) into the tool/sandbox shape that a specific agent framework expects. Same workspace, every framework, no per-framework reimplementation.\n\nThe package itself has no top-level export; integrations live under subpath imports.\n\n| Subpath                            | Framework                                                                       | Adapter                                        |\n| ---------------------------------- | ------------------------------------------------------------------------------- | ---------------------------------------------- |\n| `@cogineai/mafs-agents/openai`    | [OpenAI Agents SDK](https://github.com/openai/openai-agents)                    | `MafsEditor`, `MafsShell`, `buildSystemPrompt` |\n| `@cogineai/mafs-agents/vercel`    | [Vercel AI SDK](https://sdk.vercel.ai/docs)                                     | `mafsTools(ws)`                                |\n| `@cogineai/mafs-agents/langchain` | [LangChain](https://js.langchain.com/)                                          | Workspace-backed tool registry                 |\n| `@cogineai/mafs-agents/mastra`    | [Mastra](https://mastra.ai)                                                     | `mafsTools(ws)`                                |\n| `@cogineai/mafs-agents/pi`        | [Mariozechner pi-coding-agent](https://github.com/mariozechner/pi-coding-agent) | `mafsExtension(ws)`, `mafsOperations(ws)`      |\n\n## Install\n\n```bash\nnpm install @cogineai/mafs-agents\n```\n\nPlus the relevant peer for whichever framework you're using:\n\n| Adapter     | Peer dependency                                                     |\n| ----------- | ------------------------------------------------------------------- |\n| `openai`    | `@openai/agents` (`^0.8`)                                           |\n| `vercel`    | `ai` (`^6`), `zod` (`^4`)                                           |\n| `langchain` | `@langchain/core` and a langchain agent runtime (e.g. `deepagents`) |\n| `mastra`    | `@mastra/core` (`^1.29`)                                            |\n| `pi`        | `@mariozechner/pi-ai`, `@mariozechner/pi-coding-agent` (`^0.70`)    |\n\nYou'll also need a workspace from `@cogineai/mafs-node`, `@cogineai/mafs-browser`, or `@cogineai/mafs-core`.\n\n## Quick start — Vercel AI SDK + RAM workspace\n\n```ts\nimport { generateText } from 'ai'\nimport { openai } from '@ai-sdk/openai'\nimport { MountMode, RAMResource, Workspace } from '@cogineai/mafs-node'\nimport { mafsTools } from '@cogineai/mafs-agents/vercel'\nimport { buildSystemPrompt } from '@cogineai/mafs-agents/openai'\n\nconst ws = new Workspace({ '/': new RAMResource() }, { mode: MountMode.WRITE })\n\nconst { text } = await generateText({\n  model: openai('gpt-5.4-mini'),\n  system: buildSystemPrompt({ mountInfo: { '/': 'In-memory filesystem' } }),\n  prompt: 'Create /hello.txt containing \"hi\", then read it back.',\n  tools: mafsTools(ws),\n  maxSteps: 8,\n})\n\nconsole.log(text)\nawait ws.close()\n```\n\n## Quick start — Mastra agent over a RAM workspace\n\n```ts\nimport { Agent } from '@mastra/core/agent'\nimport { MountMode, RAMResource, Workspace } from '@cogineai/mafs-node'\nimport { mafsTools } from '@cogineai/mafs-agents/mastra'\nimport { buildSystemPrompt } from '@cogineai/mafs-agents/openai'\n\nconst ws = new Workspace({ '/': new RAMResource() }, { mode: MountMode.WRITE })\n\nconst agent = new Agent({\n  id: 'mafs-ram-agent',\n  name: 'Mafs RAM Agent',\n  instructions: buildSystemPrompt({ mountInfo: { '/': 'In-memory filesystem' } }),\n  model: 'openai/gpt-5.4-mini',\n  tools: mafsTools(ws),\n})\n\nconst result = await agent.generate(\n  'Create /hello.txt and /numbers.csv with sample data, then list / and cat each file.',\n  { maxSteps: 20 },\n)\nconsole.log(result.text)\n```\n\n## Quick start — OpenAI Agents SDK with `apply_patch` over a workspace\n\n```ts\nimport { Agent, Runner } from '@openai/agents'\nimport { MountMode, RAMResource, Workspace } from '@cogineai/mafs-node'\nimport { MafsEditor, MafsShell, buildSystemPrompt } from '@cogineai/mafs-agents/openai'\n\nconst ws = new Workspace({ '/': new RAMResource() }, { mode: MountMode.WRITE })\n\nconst agent = new Agent({\n  name: 'Mafs Coder',\n  model: 'gpt-5.4-mini',\n  instructions: buildSystemPrompt({ mountInfo: { '/': 'In-memory filesystem' } }),\n  shell: new MafsShell(ws),\n  editor: new MafsEditor(ws),\n})\n\nawait Runner.run(agent, 'Write a small script /run.sh that prints hi and run it.')\n```\n\n## Quick start — pi-coding-agent extension\n\n```ts\nimport { runAgent } from '@mariozechner/pi-coding-agent'\nimport { MountMode, RAMResource, Workspace } from '@cogineai/mafs-node'\nimport { mafsExtension } from '@cogineai/mafs-agents/pi'\n\nconst ws = new Workspace({ '/': new RAMResource() }, { mode: MountMode.WRITE })\n\nawait runAgent({\n  prompt: 'Create /hello.txt and read it back.',\n  extensions: [mafsExtension(ws, { cwd: '/' })],\n})\n```\n\n## How adapters compose with workspaces\n\nAll five adapters operate over the same `Workspace` instance. That means:\n\n- One mount tree powers every framework you wire in. Switching from Vercel AI SDK to Mastra to OpenAI Agents SDK doesn't change what the agent sees.\n- Side effects (file writes, shell exec) flow through `Workspace.fs.*` and `Workspace.execute`, so the cache, ops registry, and snapshot/clone mechanisms work uniformly.\n- You can hand the same `Workspace` to multiple agents simultaneously; the workspace serializes mutating operations internally.\n\nThe `prompt.ts` helper (`buildSystemPrompt`) generates a tool-aware system prompt from `Workspace.filePrompt` (auto-built from the resource registry), so prompts stay in sync with what's actually mounted.\n\n## Companion packages\n\n- [`@cogineai/mafs-cli`](../cli) — `coginex` + `mafs` binaries.\n- [`@cogineai/mafs-core`](../core) — runtime-agnostic primitives.\n- [`@cogineai/mafs-node`](../node) — Node resources + FUSE.\n- [`@cogineai/mafs-browser`](../browser) — browser/edge bundle.\n- [`@cogineai/mafs-server`](../server) — `mafs-daemon` HTTP server.\n\n## License & attribution\n\nApache-2.0. MAFS is a fork of [Mirage](https://github.com/strukto-ai/mirage); see the project-level [`NOTICE`](https://github.com/cogine-ai/CogineX-mono/blob/main/packages/mafs/NOTICE) for attribution and the relationship to upstream.\n","readmeFilename":"README.md","_rev":"1-e1e03e940d0d9234fd9a055777ed1366"}