Commands and Capabilities

A command in Fabric Harness is a shell-level capability you explicitly grant to a session — not a generic "run anything" door. Use defineCommand from @fabric-harness/node to declare one.

Declaring commands

import { defineCommand } from '@fabric-harness/node';

const npm = defineCommand('npm');
const git = defineCommand('git');
const gh  = defineCommand('gh', {
  env: {
    GH_TOKEN: process.env.GH_TOKEN,
  },
});

A defineCommand declaration captures:

• the binary name,
• environment variables to inject,
• working directory defaults,
• timeouts and stdin handling.

Granting commands per call

await session.prompt('Fix the failing tests', {
  commands: [npm, git, gh],
});

The model can only run shell commands whose binary matches one of the declared commands. Anything else fails with a capability error.

Secrets

Use secret() to mark a value as a credential reference. The runtime resolves it at exec time and never echoes it into model context. Exported from @fabric-harness/sdk.

import { defineCommand, secret } from '@fabric-harness/sdk';

const gh = defineCommand('gh', {
  env: { GH_TOKEN: secret('GH_TOKEN') },
});

secret() is intentionally a token, not the value: it can be passed around without leaking its content into logs, traces, or the LLM context.

Capability policy

Use policy to enforce filesystem, command, tool, network, timeout, and approval rules. Policies can be set on init(), a session, or an individual prompt; narrower call-level policy is combined with definition-level controls.

await session.prompt('Fix the tests', {
  policy: {
    filesystem: {
      read: ['/workspace/**'],
      write: ['/workspace/src/**', '/workspace/tests/**'],
    },
    commandPolicy: {
      allow: ['npm test', 'git diff', 'git status'],
      requireApproval: ['git push', 'npm publish', 'terraform apply'],
    },
    network: {
      mode: 'allowlist',
      hosts: ['api.github.com'],
    },
    maxCommandTimeoutMs: 120_000,
  },
});

The runtime applies policy at both the tool layer and the sandbox boundary. See Policies and approvals for deny rules, approval routing, and composition behavior.