Security Boundaries and Performance

This page covers two concerns: what an agent is allowed to touch, and how quickly an action should complete. Read it before connecting the CLI to your own agent’s primary workflow.

Security boundaries

Normal commands go through an allowlist. Never expose arbitrary evaluation to an agent or a skill’s primary workflow.

Commands that accept --json can read a JSON literal, @file.json, or @- for standard input. Prefer standard input for runtime values such as dynamic Token IDs so the shell cannot rewrite JSON quoting.

debug-eval is a manual debugging back door and is disabled by default. It only runs when the following environment variable is set:

$env:ARCANE_FVTT_DEBUG_EVAL = "1"
npm run fvtt:cdp -- --port 9230 --target-url autofvtt.criticalrole.top debug-eval --expr --script "game.world.id"

Use debug-eval for temporary setting reads, A/B exploration, or inspection of Foundry runtime data structures. Once the approach is proven, move the logic into a formal allowlisted command.

Performance constraints

The real-time combat-agent target is:

One action from request to returned result <= 10s

Confirmed performance factors:

  • Chrome clamps short timers to roughly one second on hidden or background pages, turning sub-second Foundry/midi workflows into ten-second-plus operations.
  • A dedicated Chrome launcher, or --foreground, restores completeItemUse to approximately 0.5–0.9 seconds.
  • The main remaining overhead comes from npm/tsx/CDP connect and process startup. Production paths should use the compiled node dist/cli.js or a resident process.

Performance notes live in the legacy Arcane-Desk engineering repository:

docs/foundry-automation/direct-cdp-combat-performance-optimization.md

Detailed design

The interface design, planned commands, and known issues live in:

docs/foundry-automation/direct-cdp-fvtt-cli-design.md