Agent Workflow Governance

Decide whether a named agent may run a workflow against explicitly assigned targets, and keep the reasons beside the result. Identity, activation, visible files, per-tool permissions and capability grants are separate records.

This is an independently usable library extracted from the TypeScript Skeleton rebuild. It opens an empty workspace through its public API; the full desktop application is not required. Origin

Follow a permission changing

Node.js 20+, from this checkout:

npm ci
npm run demo
npm run check
npm test

The example creates a document reviewer and one synthetic file assignment. The captured result exposes the actual checks and target preview:

1. Inactive agent: blocked.
2. Activate it, assign the target and grant its read tool permission: complete.
3. Deny the same tool/path: blocked.
4. Reopen the workspace and request again: still blocked.

The demo prints its temporary evidence directory for local inspection; that machine path is omitted from the public capture. “Complete” here means the built-in handler recorded the authorized target set. It did not read the file.

Consume it outside this checkout

Build and pack this repository, then install the archive in a new Node project:

npm run build
npm pack --pack-destination ..
mkdir ../governance-consumer
cd ../governance-consumer
npm init -y
npm install ../agent-workflow-governance-0.1.0.tgz

Save this as example.mjs, then run node example.mjs:

import { openGovernance } from "agent-workflow-governance";
const { agents, executor } = await openGovernance("./workspace");
await agents.createAgent({ instanceId: "example.reviewer", definition: {
  definitionId: "example.definition", label: "Example reviewer",
  remit: "Review explicitly assigned documents", toolManifest: ["filesystem.read"], triggers: ["manual"]
} });
const [workflow] = await agents.listWorkflows("example.reviewer");
const run = await agents.requestWorkflowRun("example.reviewer", workflow.workflowId, executor);
console.log(run.status); // blocked: new agents begin inactive

Use a new workspace or new identity when repeating creation; duplicate IDs are rejected. This is a local archive installation, not a claim that the package is on the npm registry.

Follow the decision

openGovernance constructs storage, coordination, agents and executor services. AgentsDomainService owns creation and request checks:

Record	Question
Agent definition + active instance	Which identity/tools are declared, and is it active?
File assignment/keycard	Which targets are visible to this instance?
Per-tool file permission	May each requested tool operate on each visible target?
Capability grant + package authorizer	Is a requested published package both granted and allowed by its owner?
Workflow run evidence	Which checks passed/failed, and what did the executor record?

Visibility alone does not grant tool permission. Adding package IDs also requires an explicit package authorizer; the library does not silently assume one exists.

Integration limits

The bundled executor is a target/evidence handler, not a general tool runner or an operating-system sandbox. A real tool integration must consume and enforce the checked target set; these records do not prevent arbitrary code elsewhere from accessing a file. There is no login/authentication service.

Use a single writer per workspace. Atomic JSON replacement protects readers from partially written records; a workflow spanning multiple records is not a database transaction. A useful next integration is one bounded read-only tool with tests proving denial prevents the actual file read.

Mechanism · Consumer checks · Security · License