@itemai/aiop-vfs

TypeScript SDK for the AIOP virtual filesystem service.

What This Package Solves

The SDK gives callers a filesystem-style API over the VFS HTTP service while hiding:

• multi-tenant request headers
• App Key header injection
• upstream Trace ID propagation
• request timeout wiring
• Go/JSON response shape normalization
• projection/search/reindex endpoint details

It is intended to be published and versioned independently from aiop-pa.

Install

npm install @itemai/aiop-vfs

For local standalone development inside this repository:

cd aiop-vfs/sdk-ts
npm install

For local consumption from another project without publishing:

npm install /absolute/path/to/aiop-vfs/sdk-ts

Build

npm run build

Build output:

dist/index.js
dist/index.d.ts
dist/index.js.map
dist/index.d.ts.map

Typecheck

npm run typecheck

Test

npm test

Package Preview

npm run pack:dry-run

Publish

npm publish

prepublishOnly will run the build automatically before publish.

See RELEASING.md for the full release checklist.

Authentication

VFS requires an App Key on every request. Sending only tenantId and userId is rejected with 401.

| Credential | Option | Header | Meaning | | --- | --- | --- | --- | | App Key | getAppKey | X-App-Key | An application acts on the namespace named by the request context |

The App Key authenticates the caller; the namespace it operates on comes from getContext, which must supply tenantId plus either userId or workspaceId. Obtain an App Key from a VFS operator (see the service's admin API).

IAM bearer tokens are not accepted on the data plane — they authenticate the service's administrative endpoints only. A request carrying just a bearer token is rejected with 401.

Usage

import { createVfsClient } from "@itemai/aiop-vfs";

const client = createVfsClient({
  endpoint: "http://127.0.0.1:18088",
  timeoutMs: 15000,
  getContext: () => ({
    tenantId: "tenant-1",
    userId: "user-1",
    cwd: "/memory",
    project: "memory",
  }),
  getAppKey: () => process.env.VFS_APP_KEY ?? null,
  getTraceId: () => currentTraceContext.getTraceId(),
});

const content = await client.read("/memory/MEMORY.md");
console.log(content);

const searchResults = await client.search("/memory", "transport preferences", {
  mode: "hybrid",
  limit: 5,
});
console.log(searchResults[0]);

getTraceId may return a string synchronously or asynchronously. The SDK trims and sends a non-empty value as X-Trace-Id on each request. It does not create a new ID when the callback is absent or empty; the VFS service handles that case.

VFS namespace isolation supports two modes:

• tenantId + userId: user-scoped namespace, suitable for memory/session-style personal spaces.
• tenantId + workspaceId: workspace-scoped namespace, independent of IAM user identity.

Example for workspace-scoped access:

import { createVfsClient } from "@itemai/aiop-vfs";

const client = createVfsClient({
  endpoint: "http://172.30.9.6:8088",
  timeoutMs: 15000,
  getAppKey: () => process.env.VFS_APP_KEY ?? null,
  getContext: () => ({
    tenantId: "tenant-1",
    workspaceId: "workspace-1",
    cwd: "/wiki",
    project: "knowledge",
  }),
});

const content = await client.read("/wiki/README.md");
console.log(content);

If your application already authenticates its own users (through IAM or anything else), resolve their identity yourself and pass it as the namespace context. The App Key identifies your application; the context says whose data it is acting on.

const client = createVfsClient({
  endpoint: "http://172.30.9.6:8088",
  timeoutMs: 15000,
  getAppKey: () => process.env.VFS_APP_KEY ?? null,
  getContext: () => ({
    tenantId: currentUser.tenantId,
    userId: currentUser.id,
    cwd: "/wiki",
    project: "knowledge",
  }),
});

Supported Operations

• stat
• exists
• ls
• read
• write
• append
• mkdir
• rm
• mv
• grep
• tree
• glob
• listProjections
• search
• reindex
• readJson
• writeJson
• createVfsFsAdapter