@cogineai/mafs-agents

Agent-framework adapters for MAFS — A Unified Virtual File System for AI Agents.

Each adapter wraps a Workspace from @cogineai/mafs-core (or @cogineai/mafs-node / @cogineai/mafs-browser) into the tool/sandbox shape that a specific agent framework expects. Same workspace, every framework, no per-framework reimplementation.

The package itself has no top-level export; integrations live under subpath imports.

| Subpath | Framework | Adapter | | ---------------------------------- | ------------------------------------------------------------------------------- | ---------------------------------------------- | | @cogineai/mafs-agents/openai | OpenAI Agents SDK | MafsEditor, MafsShell, buildSystemPrompt | | @cogineai/mafs-agents/vercel | Vercel AI SDK | mafsTools(ws) | | @cogineai/mafs-agents/langchain | LangChain | Workspace-backed tool registry | | @cogineai/mafs-agents/mastra | Mastra | mafsTools(ws) | | @cogineai/mafs-agents/pi | Mariozechner pi-coding-agent | mafsExtension(ws), mafsOperations(ws) |

Install

npm install @cogineai/mafs-agents

Plus the relevant peer for whichever framework you're using:

| Adapter | Peer dependency | | ----------- | ------------------------------------------------------------------- | | openai | @openai/agents (^0.8) | | vercel | ai (^6), zod (^4) | | langchain | @langchain/core and a langchain agent runtime (e.g. deepagents) | | mastra | @mastra/core (^1.29) | | pi | @mariozechner/pi-ai, @mariozechner/pi-coding-agent (^0.70) |

You'll also need a workspace from @cogineai/mafs-node, @cogineai/mafs-browser, or @cogineai/mafs-core.

Quick start — Vercel AI SDK + RAM workspace

import { generateText } from 'ai'
import { openai } from '@ai-sdk/openai'
import { MountMode, RAMResource, Workspace } from '@cogineai/mafs-node'
import { mafsTools } from '@cogineai/mafs-agents/vercel'
import { buildSystemPrompt } from '@cogineai/mafs-agents/openai'

const ws = new Workspace({ '/': new RAMResource() }, { mode: MountMode.WRITE })

const { text } = await generateText({
  model: openai('gpt-5.4-mini'),
  system: buildSystemPrompt({ mountInfo: { '/': 'In-memory filesystem' } }),
  prompt: 'Create /hello.txt containing "hi", then read it back.',
  tools: mafsTools(ws),
  maxSteps: 8,
})

console.log(text)
await ws.close()

Quick start — Mastra agent over a RAM workspace

import { Agent } from '@mastra/core/agent'
import { MountMode, RAMResource, Workspace } from '@cogineai/mafs-node'
import { mafsTools } from '@cogineai/mafs-agents/mastra'
import { buildSystemPrompt } from '@cogineai/mafs-agents/openai'

const ws = new Workspace({ '/': new RAMResource() }, { mode: MountMode.WRITE })

const agent = new Agent({
  id: 'mafs-ram-agent',
  name: 'Mafs RAM Agent',
  instructions: buildSystemPrompt({ mountInfo: { '/': 'In-memory filesystem' } }),
  model: 'openai/gpt-5.4-mini',
  tools: mafsTools(ws),
})

const result = await agent.generate(
  'Create /hello.txt and /numbers.csv with sample data, then list / and cat each file.',
  { maxSteps: 20 },
)
console.log(result.text)

Quick start — OpenAI Agents SDK with apply_patch over a workspace

import { Agent, Runner } from '@openai/agents'
import { MountMode, RAMResource, Workspace } from '@cogineai/mafs-node'
import { MafsEditor, MafsShell, buildSystemPrompt } from '@cogineai/mafs-agents/openai'

const ws = new Workspace({ '/': new RAMResource() }, { mode: MountMode.WRITE })

const agent = new Agent({
  name: 'Mafs Coder',
  model: 'gpt-5.4-mini',
  instructions: buildSystemPrompt({ mountInfo: { '/': 'In-memory filesystem' } }),
  shell: new MafsShell(ws),
  editor: new MafsEditor(ws),
})

await Runner.run(agent, 'Write a small script /run.sh that prints hi and run it.')

Quick start — pi-coding-agent extension

import { runAgent } from '@mariozechner/pi-coding-agent'
import { MountMode, RAMResource, Workspace } from '@cogineai/mafs-node'
import { mafsExtension } from '@cogineai/mafs-agents/pi'

const ws = new Workspace({ '/': new RAMResource() }, { mode: MountMode.WRITE })

await runAgent({
  prompt: 'Create /hello.txt and read it back.',
  extensions: [mafsExtension(ws, { cwd: '/' })],
})

How adapters compose with workspaces

All five adapters operate over the same Workspace instance. That means:

• 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.
• Side effects (file writes, shell exec) flow through Workspace.fs.* and Workspace.execute, so the cache, ops registry, and snapshot/clone mechanisms work uniformly.
• You can hand the same Workspace to multiple agents simultaneously; the workspace serializes mutating operations internally.

The 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.

Companion packages

• @cogineai/mafs-cli — coginex + mafs binaries.
• @cogineai/mafs-core — runtime-agnostic primitives.
• @cogineai/mafs-node — Node resources + FUSE.
• @cogineai/mafs-browser — browser/edge bundle.
• @cogineai/mafs-server — mafs-daemon HTTP server.

License & attribution

Apache-2.0. MAFS is a fork of Mirage; see the project-level NOTICE for attribution and the relationship to upstream.