@agent-forge/plugin-workspace-files-write

Workspace file write capability plugin for Agent Forge, extracted from the host's src/plugins/workspace-files-write (D-075 S3). It registers one full-control tool, workspace_write, which atomically replaces or patches a host-owned file using opaque file and artifact references; bytes and local paths never cross the capability boundary.

The plugin is deliberately inert at load time. Without a host-bound write seam the tool reports an explicit unsupported result; hosts that want real writes bind createNodeWorkspaceFilesWriteHostAdapterV1 (sandboxed root, artifact resolution, version-checked atomic commits) through their profile machinery. Readonly hosts get no tool registration at all.

Install

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

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

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 { createNodeWorkspaceFilesWriteHostAdapterV1, createWorkspaceFilesWriteCapabilityFactoryV1 } from "@agent-forge/plugin-workspace-files-write";

• createNodeWorkspaceFilesWriteAdapterV1(options?) — host-injection adapter; requires a host write seam, otherwise returns unsupported.
• createNodeWorkspaceFilesWriteHostAdapterV1({ root, resolveFileRef, readArtifact, ... }) — real sandboxed host writer: atomic rename commits, expectedVersion checks, per-path single-flight serialization, committed reporting.
• createWorkspaceFilesWriteCapabilityFactoryV1(adapter?) — registers workspace_write on a full-control CapabilityAPI (defaults to the unbound adapter).
• 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-write (tsgo)
npm test                            # vitest; the entry fidelity test requires `npm run build` first