{"_id":"@cogineai/mafs-core","name":"@cogineai/mafs-core","dist-tags":{"alpha":"0.1.0-alpha.0","latest":"0.1.0-alpha.0"},"versions":{"0.1.0-alpha.0":{"name":"@cogineai/mafs-core","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/core"},"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"}},"devDependencies":{"@aws-sdk/client-s3":"^3.0.0","@modelcontextprotocol/sdk":"^1.0.0","hyparquet-writer":"^0.13.0","pyodide":"^0.29.3","tree-sitter-bash":"^0.25.1","tsup":"^8.5.0","typescript":"^6.0.0","vitest":"^3.0.0"},"dependencies":{"@aws-sdk/client-s3":"^3.0.0","@modelcontextprotocol/sdk":"^1.0.0","apache-arrow":"^21.1.0","h5wasm":"^0.10.1","hyparquet":"^1.25.6","jq-wasm":"1.1.0-jq-1.8.1","web-tree-sitter":"^0.26.8"},"peerDependencies":{"pyodide":"^0.29.0"},"peerDependenciesMeta":{"pyodide":{"optional":true}},"scripts":{"build":"tsup","test":"vitest run","typecheck":"tsc --noEmit"},"_id":"@cogineai/mafs-core@0.1.0-alpha.0","_integrity":"sha512-2MqqHsP6tYDLH+Hv64YbimPoPqwYUP3qhnS37Zx5Eh372xlcKULCImYI0qIwEW8OSgI0zX4yMbhZHXmtxlQ4lA==","_resolved":"/private/var/folders/w3/1jnv2n65319gjrn7xmghv87m0000gn/T/de1eefdfdf02f7f04b70e777cca7fec9/cogineai-mafs-core-0.1.0-alpha.0.tgz","_from":"file:cogineai-mafs-core-0.1.0-alpha.0.tgz","_nodeVersion":"22.16.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-2MqqHsP6tYDLH+Hv64YbimPoPqwYUP3qhnS37Zx5Eh372xlcKULCImYI0qIwEW8OSgI0zX4yMbhZHXmtxlQ4lA==","shasum":"83978024efce7bc1b28956091cbced174bbf6e42","tarball":"https://registry.npmjs.org/@cogineai/mafs-core/-/mafs-core-0.1.0-alpha.0.tgz","fileCount":19,"unpackedSize":8170961,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDasGOLFgrFiajcdCX1pMCOUczdkcb2Z1zxp9+KmzQVvAIhANxgYtsoo4/TEyY4M2eXQvZxrKG/aD3m5PDhXeH3LvWZ"}]},"_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-core_0.1.0-alpha.0_1779464742838_0.46042070719315586"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-22T15:45:42.670Z","0.1.0-alpha.0":"2026-05-22T15:45:43.000Z","modified":"2026-05-22T15:45:43.200Z"},"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/core"},"author":{"name":"lc708","email":"kiedis@foxmail.com"},"bugs":{"url":"https://github.com/cogine-ai/CogineX-mono/issues"},"license":"Apache-2.0","readme":"# @cogineai/mafs-core\n\n[![npm version](https://img.shields.io/npm/v/%40cogineai%2Fmafs-core.svg)](https://www.npmjs.com/package/@cogineai/mafs-core)\n[![License](https://img.shields.io/npm/l/%40cogineai%2Fmafs-core.svg)](https://github.com/cogine-ai/CogineX-mono/blob/main/packages/mafs/LICENSE)\n\nRuntime-agnostic primitives for **MAFS — A Unified Virtual File System for AI Agents**.\n\nThis is the engine: the `Workspace` class, the `Resource` interface, the ops/commands registry, the shell parser and executor, the cache abstractions, and reusable resource implementations that don't need Node-specific I/O (RAM, S3 over `fetch`, Slack/Discord/GitHub HTTP transports, …). It runs anywhere modern JavaScript runs — Node ≥ 20, browsers, edge runtimes, Bun, Deno, Pyodide.\n\nMost consumers should depend on [`@cogineai/mafs-node`](../node) or [`@cogineai/mafs-browser`](../browser) — both re-export everything here and add runtime-specific pieces. Reach for `mafs-core` only when:\n\n- You're authoring a new resource or runtime adapter,\n- You're embedding MAFS into a non-standard environment (Pyodide, a custom edge worker), or\n- You want the smallest possible bundle and only need RAM-level functionality.\n\n## Install\n\n```bash\nnpm install @cogineai/mafs-core\n```\n\nOptional peer:\n\n```bash\nnpm install pyodide   # only if you'll execute Python inside the workspace\n```\n\n## Quick start\n\n```ts\nimport { MountMode, RAMResource, Workspace } from '@cogineai/mafs-core'\n\nconst ws = new Workspace({ '/data': new RAMResource() }, { mode: MountMode.WRITE })\n\nawait ws.fs.writeFile('/data/hello.txt', 'hello mafs\\n')\nconst result = await ws.execute('cat /data/hello.txt | wc -l')\nconsole.log(result.stdoutText) //=> \"       1\\n\"\n\nawait ws.close()\n```\n\n## What lives here\n\n- **`Workspace`** — the unified VFS façade: `ws.fs.*` for direct file ops, `ws.execute(cmd)` to run a shell pipeline across mounts, `ws.snapshot()` for portability.\n- **`Resource`** — the abstract contract every backend implements (`readdir`, `read`, `write`, `stat`, `unlink`, `glob`, …). `RAMResource`, `DevResource`, and HTTP-only resources (Slack, GitHub, GCS via `fetch`, …) live here; native-binding resources (FUSE, postgres-driver, sherpa-onnx) live in [`@cogineai/mafs-node`](../node).\n- **`OpsRegistry`** — the registry that maps shell commands (`cat`, `grep`, `sort`, `find`, `jq`, …) to per-resource implementations. ~80 builtin RAM ops plus per-resource overrides (S3, Slack, GitHub, …).\n- **Shell layer** — `createShellParser`, `executeNode`, expansion, jobs, redirects, control flow. The full POSIX-ish shell that powers `ws.execute()`.\n- **Cache layer** — `IndexCacheStore` + `FileCache` mixin, with RAM-backed implementations. Redis-backed implementations live in `mafs-node`; consumers can plug their own.\n- **`Session`, `SessionManager`, `ExecutionHistory`** — multi-turn agent state.\n- **Snapshot / clone** — tar-based portable workspace export/import.\n\n## Extending MAFS\n\nAdding a new backend means implementing `Resource`. Once registered, every shell command, agent adapter, and CLI inherits filesystem semantics for free:\n\n```ts\nimport { type Resource, throwUnsupported } from '@cogineai/mafs-core'\n\nexport class MyResource implements Resource {\n  async readdir(path: string): Promise<string[]> {\n    /* … */\n  }\n  async read(path: string): Promise<Uint8Array> {\n    /* … */\n  }\n  async stat(path: string) {\n    /* … */\n  }\n  // The base interface marks unimplemented methods with throwUnsupported()\n  // until you fill them in — useful for read-only or partial backends.\n}\n```\n\nThe same applies to ops (`OpsRegistry.register({ kind: 'cat', resource: 'my', impl })`) and shell builtins.\n\n## API surface\n\n`@cogineai/mafs-core` exports ~1000 named symbols — far too many to list here. Browse the full surface in [`packages/mafs/typescript/packages/core/src/index.ts`](https://github.com/cogine-ai/CogineX-mono/blob/main/packages/mafs/typescript/packages/core/src/index.ts) or rely on your IDE's import suggestions; everything is typed.\n\nThe most-used groupings:\n\n- **Top-level types** — `Workspace`, `Resource`, `MountMode`, `FileStat`, `FileType`, `PathSpec`, `ResourceName`.\n- **Resources** — `RAMResource`, `DevResource`, `S3Resource`, `SlackResource`, `GitHubResource`, `LinearResource`, `NotionResource`, `GDocsResource`, `GSheetsResource`, `GmailResource`, … (40+ resources).\n- **Ops** — `RAM_OPS`, `S3_OPS`, `GITHUB_VFS_OPS`, … (one per resource).\n- **Cache** — `RAMFileCacheStore`, `RAMIndexCacheStore`, `IndexCacheStore`, `IndexEntry`.\n- **Cache parts of resources** — most resource modules export `*_PROMPT` and per-tool helpers (`featherCat`, `parquetGrep`, …) you can compose into your own backends.\n\n## Companion packages\n\n- [`@cogineai/mafs-cli`](../cli) — `coginex` + `mafs` binaries.\n- [`@cogineai/mafs-node`](../node) — Node resources, FUSE, Redis cache.\n- [`@cogineai/mafs-browser`](../browser) — browser bundle.\n- [`@cogineai/mafs-server`](../server) — `mafs-daemon` HTTP server.\n- [`@cogineai/mafs-agents`](../agents) — agent framework adapters.\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-7c149cc806823c98c7cf5495eb687f90"}