@agent-forge/plugin-process-exec

Process execution capability plugin for Agent Forge, extracted from the host's src/plugins/process-exec (D-075 S3). It registers one full-control tool, process_exec, which runs an argv command through a host-selected process adapter and returns bounded, sanitized stdout/stderr previews.

The plugin is deliberately inert at load time. The real Node adapter requires a host-owned absolute cwd (the workspace directory), which no load-time seam can supply, so the standalone entry reports an explicit unsupported result until a host binds createNodeProcessExecAdapterV1({ cwd, ... }) through its own profile machinery. Readonly hosts get no tool registration at all.

Install

# from a local checkout
agent-forge plugin install ./plugins/process-exec

# from npm
agent-forge plugin install @ai-agent-forge/plugin-process-exec

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 { createNodeProcessExecAdapterV1, createProcessExecCapabilityFactoryV1 } from "@agent-forge/plugin-process-exec";

• createNodeProcessExecAdapterV1({ cwd, ... }) — shell-free argv execution with output budgets, previews, timeouts, and cross-platform process-tree termination; cwd is host-owned and requests cannot override it.
• sanitizeProcessTextV1(value, maximum?, cwd?) — redacts credentials and host paths from previews.
• createProcessExecCapabilityFactoryV1(adapter) — registers process_exec on a full-control CapabilityAPI.
• Default export of dist/entry.js — the precomposed unsupported-adapter factory used by external plugin loading.

Development

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