@agent-forge/plugin-workspace-files

Workspace files capability plugin for Agent Forge, extracted from the host's src/plugins/workspace-files (D-075 S3). It registers three read-only tools — workspace_list, workspace_read, workspace_find — which operate purely through opaque host-owned workspace references; the model never supplies or receives a local path.

The plugin has no standalone filesystem binding at load time. Without host-injected list/read/find seams the tools report an explicit unsupported result; hosts that want real file access bind their own opaque-ref file host through their profile machinery.

Install

# from a local checkout
agent-forge plugin install ./plugins/workspace-files

# from npm
agent-forge plugin install @ai-agent-forge/plugin-workspace-files

The package ships two manifests: agent-forge.json (ecosystem manifest for the deterministic plugin resolver) and plugin.json (host-load manifest consumed by loadCapabilityPluginFromManifest, entry ./dist/entry.js).

Library surface

import { createNodeWorkspaceFilesAdapterV1, createWorkspaceFilesCapabilityFactoryV1 } from "@agent-forge/plugin-workspace-files";

• createNodeWorkspaceFilesAdapterV1(options?) — read-only adapter; requires host-injected list/read/find callbacks to produce results, otherwise returns unsupported.
• sanitizeWorkspaceFilesTextV1(value, maximum?) — redacts credentials and host paths from previews.
• createWorkspaceFilesCapabilityFactoryV1(adapter) — registers the three workspace tools on a CapabilityAPI.
• Default export of dist/entry.js — the precomposed factory used by external plugin loading.

Development

npm install --ignore-scripts        # repo root, creates the workspace symlink
npm run build                       # plugins/workspace-files (tsgo)
npm test                            # vitest; the entry fidelity test requires `npm run build` first