Automation Scripts

An automation library artifact or surface deployment is a version 1 JSON file in the project.

Location

{ProjectPath}/.fire/automations/{automation-id}.json

The files are project-owned. A library script's ID matches the Automation canvas record. A Tools-page or Power Strip placement has a fresh deployment ID and retains its source automation as metadata.

Current Format

{
  "id": "automation-id",
  "name": "Summarize and Save",
  "version": 1,
  "deployedAt": "2026-08-12T20:00:00Z",
  "sourceViewId": "automation-id",
  "sourceAutomationId": "automation-id",
  "scopeId": "project:Research",
  "hostSurface": "agents_page",
  "hostSlotRef": null,
  "agents": [
    {
      "id": "summarizer-node-id",
      "agentId": "summarizer-tool-id",
      "deploymentId": "summarizer-node-deployment-id",
      "name": "Summarize Documents",
      "order": 0
    },
    {
      "id": "writer-node-id",
      "agentId": "writer-tool-id",
      "deploymentId": "writer-node-deployment-id",
      "name": "Save Summary",
      "order": 1
    }
  ],
  "edges": [
    {
      "sourceId": "summarizer-node-id",
      "targetId": "writer-node-id",
      "type": "chain"
    }
  ],
  "execution": {
    "mode": "sequential"
  },
  "inputs": [
    {
      "type": "folder",
      "path": "C:\\Projects\\Research"
    }
  ]
}

Placement Metadata

sourceAutomationId identifies the reusable library automation. scopeId is global or project:{Project Name}. hostSurface is automation_library for the canvas-published script, agents_page for a Tools-page placement, or acfm for a Power Strip slot. hostSlotRef carries a destination slot identity when one exists.

Older version 1 scripts without these fields still load as library scripts.

agents

agents is the executable list. Deployment calculates its order from the canvas connections.

Each entry has a unique automation-node ID, a reusable Tool definition ID in agentId, and an isolated settings instance in deploymentId. The runner iterates the list exactly as saved, loads the current definition, and applies that node's deployment settings. The same Tool definition can appear more than once with different settings.

A missing tool is logged and skipped rather than treated as a hard failure.

edges

edges preserves the canvas's tool connections.

The runner does not use them for scheduling, routing, branching, or merging. They are informational after deployment, because order was already flattened into agents.

execution

The only current mode is sequential.

There is no condition model, failure policy, retry policy, parallelism setting, or node-state model.

inputs

Bindings contain:

  • type — folder or file
  • path — a filesystem path

The current Automations page does not expose a binding editor. Internal callers can create file or folder bindings, and redeployment preserves existing bindings by default.

At run time:

  • Explicit caller input wins.
  • Otherwise, existing bindings become context sources.
  • Missing paths are skipped.
  • If no usable input remains, the runner starts empty.

Bindings are normally absolute, machine-specific paths.

Live Definitions and Isolated Node Settings

The script stores definition and deployment IDs, not definition snapshots. Creating a Tools-page or Power Strip placement clones every node's deployment settings and remaps the copied edges, so changing one placement does not change another placement's settings.

Consequences:

  • Editing a Tool definition's execution flow changes future runs without redeployment.
  • Changing one node's settings affects only that node and placement.
  • Deleting a Tool definition leaves a broken reference that the runner skips.
  • There is no saved tool revision or definition hash.
  • Historical script behavior is not reproducible from the JSON alone.

Editor Data Not Included

Scripts do not contain:

  • Card positions
  • Zoom or pan
  • Document cards
  • Current selection
  • Tool output previews
  • Canvas status

Those stay with the project's canvas record.

Editing

The intended authoring path is the Automation canvas followed by Deploy. Editing the JSON directly bypasses canvas validation and can create a mismatch between agents and edges. The runner trusts the saved agents order and does not recompute it.