@barnum/barnum 0.0.0-main-04a1bb17 → 0.2.0

package/barnum-config-schema.json

@@ -1,14 +1,14 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "title": "ConfigFile",
-  "description": "Top-level Barnum configuration file format.\n\nDefines a workflow as a directed graph of steps. Each step processes tasks and can spawn follow-up tasks on other steps.",
+  "description": "Top-level Barnum configuration file format.\n\nThis is the raw parsed format. Call `resolve()` to get the runtime `Config`.",
   "type": "object",
   "required": [
     "steps"
   ],
   "properties": {
     "$schema": {
-      "description": "Optional JSON Schema URL for editor validation (e.g., `\"./node_modules/@barnum/barnum/barnum-config-schema.json\"`). Ignored at runtime.",
+      "description": "JSON Schema reference for editor validation (ignored at runtime).",
       "writeOnly": true,
       "type": [
         "string",
@@ -16,7 +16,7 @@
       ]
     },
     "entrypoint": {
-      "description": "Name of the step that starts the workflow. When set, the CLI accepts `--entrypoint-value` to provide the initial task value (defaults to `{}`). When omitted, `--initial-state` must provide explicit `[{\"kind\": \"StepName\", \"value\": ...}]` tasks.",
+      "description": "Entry point step name. If specified, the workflow starts with this step and `--entrypoint-value` can be used to provide the initial value (defaults to `{}`). If not specified, `--initial-state` must be provided on the command line.",
       "default": null,
       "type": [
         "string",
@@ -24,7 +24,7 @@
       ]
     },
     "options": {
-      "description": "Global runtime options (timeout, retries, concurrency). Individual steps can override these via their own `options` field.",
+      "description": "Runtime options.",
       "default": {
         "max_concurrency": null,
         "max_retries": 0,
@@ -39,7 +39,7 @@
       ]
     },
     "steps": {
-      "description": "The steps that make up this workflow. Each step defines how to process a task and which steps it can spawn follow-up tasks on.",
+      "description": "Step definitions forming the task queue.",
       "type": "array",
       "items": {
         "$ref": "#/definitions/StepFile"
@@ -49,18 +49,20 @@
   "additionalProperties": false,
   "definitions": {
     "ActionFile": {
-      "description": "How a step processes tasks. Set `\"kind\": \"Pool\"` to send tasks to AI agents, or `\"kind\": \"Command\"` to run a local shell script.",
+      "description": "How a step processes tasks (config file format).",
       "oneOf": [
         {
-          "description": "Send the task to the agent pool. An AI agent receives the task's `value` along with the `instructions` (markdown prompt) and produces a JSON array of follow-up tasks.",
+          "description": "Send to the agent pool for processing.",
           "type": "object",
           "required": [
-            "instructions",
             "kind"
           ],
           "properties": {
             "instructions": {
-              "description": "Markdown prompt shown to the agent processing this task. This is the core of what tells the agent what to do. Use `{\"inline\": \"...\"}` to write the markdown directly, or `{\"link\": \"path/to/file.md\"}` to reference an external file.",
+              "description": "Markdown instructions shown to agents.",
+              "default": {
+                "inline": ""
+              },
               "allOf": [
                 {
                   "$ref": "#/definitions/MaybeLinked_for_String"
@@ -76,7 +78,7 @@
           }
         },
         {
-          "description": "Run a local shell command instead of sending to an agent. Use this for deterministic transformations, fan-out, or glue logic.",
+          "description": "Run a local command.",
           "type": "object",
           "required": [
             "kind",
@@ -90,32 +92,7 @@
               ]
             },
             "script": {
-              "description": "Shell script to execute.\n\n**Input (stdin):** JSON object: `{\"kind\": \"<step name>\", \"value\": <payload>}`. Use `jq '.value'` to extract the payload, or `jq -r '.value.fieldName'` for a specific field.\n\n**Output (stdout):** JSON array of follow-up tasks to spawn: `[{\"kind\": \"NextStep\", \"value\": {...}}, ...]`. Each `kind` must be a step name listed in this step's `next` array. Return `[]` to spawn no follow-ups.",
-              "type": "string"
-            }
-          }
-        }
-      ]
-    },
-    "FinallyHook": {
-      "description": "Finally hook. Runs after a task and all its descendants complete.\n\nIn JSON: `{\"kind\": \"Command\", \"script\": \"./finally-hook.sh\"}`\n\n**stdin:** The task's original value payload as JSON. **stdout:** JSON array of follow-up tasks: `[{\"kind\": \"StepName\", \"value\": {...}}, ...]`. Return `[]` for no follow-ups.",
-      "oneOf": [
-        {
-          "description": "Run a shell command as the finally hook.",
-          "type": "object",
-          "required": [
-            "kind",
-            "script"
-          ],
-          "properties": {
-            "kind": {
-              "type": "string",
-              "enum": [
-                "Command"
-              ]
-            },
-            "script": {
-              "description": "Shell script to execute. Receives the task's original value as JSON on stdin, must write a JSON array of follow-up tasks on stdout.",
+              "description": "Shell script to execute.\n\n**Input (stdin):** JSON object with the structure `{\"kind\": \"<step name>\", \"value\": <parameters>}`. Use `jq '.value'` to extract parameters or `jq -r '.value.fieldName'` for specific fields.\n\n**Output (stdout):** JSON array of next tasks, e.g. `[{\"kind\": \"NextStep\", \"value\": {...}}]`. Return `[]` to spawn no follow-up tasks.",
               "type": "string"
             }
           }
@@ -123,7 +100,7 @@
       ]
     },
     "MaybeLinked_for_String": {
-      "description": "Content that can be inline or linked to a file.\n\nIn config files: - `{\"inline\": <value>}` → content provided directly in the config - `{\"link\": \"path\"}` → content loaded from a file (path relative to the config file)",
+      "description": "Content that can be inline or linked to a file.\n\nIn config files: - `{\"inline\": <value>}` → inline content - `{\"link\": \"path\"}` → link to file",
       "anyOf": [
         {
           "description": "Inline content.",
@@ -133,20 +110,20 @@
           ],
           "properties": {
             "inline": {
-              "description": "The content value, provided directly in the config file.",
+              "description": "The inline content.",
               "type": "string"
             }
           }
         },
         {
-          "description": "Link to a file whose contents will be loaded at runtime.",
+          "description": "Link to a file.",
           "type": "object",
           "required": [
             "link"
           ],
           "properties": {
             "link": {
-              "description": "Relative path to the file (resolved relative to the config file's directory).",
+              "description": "Path to the file.",
               "type": "string"
             }
           }
@@ -154,7 +131,7 @@
       ]
     },
     "Options": {
-      "description": "Global runtime options for task execution. All fields have sensible defaults.",
+      "description": "Runtime options for task execution.",
       "type": "object",
       "properties": {
         "max_concurrency": {
@@ -197,87 +174,42 @@
       },
       "additionalProperties": false
     },
-    "PostHook": {
-      "description": "Post-action hook. Inspects or modifies the action's outcome.\n\nIn JSON: `{\"kind\": \"Command\", \"script\": \"./post-hook.sh\"}`\n\n**stdin:** Tagged JSON describing the outcome (`\"kind\": \"Success\"`, `\"Timeout\"`, `\"Error\"`, or `\"PreHookError\"`). On success, includes an `input`, `output`, and `next` (follow-up tasks) field. **stdout:** Same tagged JSON, possibly modified (e.g., filtering `next`).",
-      "oneOf": [
-        {
-          "description": "Run a shell command as the post hook.",
-          "type": "object",
-          "required": [
-            "kind",
-            "script"
-          ],
-          "properties": {
-            "kind": {
-              "type": "string",
-              "enum": [
-                "Command"
-              ]
-            },
-            "script": {
-              "description": "Shell script to execute. Receives the action outcome as JSON on stdin, must write the (possibly modified) outcome as JSON on stdout.",
-              "type": "string"
-            }
-          }
-        }
-      ]
-    },
-    "PreHook": {
-      "description": "Pre-action hook. Transforms the task value before the action runs.\n\nIn JSON: `{\"kind\": \"Command\", \"script\": \"./pre-hook.sh\"}`\n\n**stdin:** Task value payload (e.g., `{\"path\": \"/src\"}`). **stdout:** Modified value payload (same shape).",
-      "oneOf": [
-        {
-          "description": "Run a shell command as the pre hook.",
-          "type": "object",
-          "required": [
-            "kind",
-            "script"
-          ],
-          "properties": {
-            "kind": {
-              "type": "string",
-              "enum": [
-                "Command"
-              ]
-            },
-            "script": {
-              "description": "Shell script to execute. Receives the task's value as JSON on stdin, must write the (possibly modified) value as JSON on stdout.",
-              "type": "string"
-            }
-          }
-        }
-      ]
-    },
     "SchemaRef": {
-      "description": "A JSON Schema for validating task payloads. Can be provided inline or loaded from a file.\n\n- Inline: write the JSON Schema object directly, e.g. `{\"type\": \"object\", \"properties\": {...}}` - Linked: `{\"link\": \"path/to/schema.json\"}` to reference an external file (path relative to config file)",
+      "description": "Reference to a JSON Schema (inline or external file).\n\nIn config files: - `{\"link\": \"path\"}` → link to schema file - Object → inline JSON Schema",
       "anyOf": [
         {
-          "description": "Reference to an external JSON Schema file. The path is relative to the config file's directory.",
+          "description": "Link to a JSON Schema file.",
           "type": "object",
           "required": [
             "link"
           ],
           "properties": {
             "link": {
-              "description": "Relative path to the JSON Schema file (e.g., `\"schemas/task.json\"`).",
+              "description": "Path to the schema file.",
               "type": "string"
             }
           }
         },
         {
-          "description": "Inline JSON Schema object (any valid JSON Schema)."
+          "description": "Inline JSON Schema."
         }
       ]
     },
     "StepFile": {
-      "description": "A named step in the workflow. Steps are the nodes of the task graph.\n\nExecution order for each task: `pre` hook → `action` → `post` hook. The `finally` hook runs after the task **and all of its descendant tasks** complete.",
+      "description": "A step in the config file (may have unresolved references).",
       "type": "object",
       "required": [
-        "action",
         "name"
       ],
       "properties": {
         "action": {
-          "description": "How this step processes tasks — either send to the agent pool (`Pool`) or run a local shell command (`Command`).",
+          "description": "How to execute the step.",
+          "default": {
+            "instructions": {
+              "inline": ""
+            },
+            "kind": "Pool"
+          },
           "allOf": [
             {
               "$ref": "#/definitions/ActionFile"
@@ -285,23 +217,19 @@
           ]
         },
         "finally": {
-          "description": "Shell script that runs after this task **and all tasks it spawned (recursively)** have completed.\n\n**stdin:** The task's original `value` payload as JSON (same as what the pre hook received — just the value, not the full task wrapper).\n\n**stdout:** A JSON array of follow-up tasks to spawn: `[{\"kind\": \"StepName\", \"value\": {...}}, ...]`. Each `kind` must be a valid step name. Return `[]` to spawn no follow-ups.\n\nUse this for cleanup, aggregation, or spawning a final summarization step after an entire subtree of work completes.",
+          "description": "Finally hook (runs after all children complete).",
           "default": null,
-          "anyOf": [
-            {
-              "$ref": "#/definitions/FinallyHook"
-            },
-            {
-              "type": "null"
-            }
+          "type": [
+            "string",
+            "null"
           ]
         },
         "name": {
-          "description": "Unique name for this step (e.g., `\"Analyze\"`, `\"Implement\"`, `\"Review\"`). This is the string used as `kind` when creating tasks: `{\"kind\": \"ThisStepName\", \"value\": {...}}`.",
+          "description": "Step name (e.g., `Analyze`, `Implement`).",
           "type": "string"
         },
         "next": {
-          "description": "Step names this step is allowed to spawn follow-up tasks on. Each string must match the `name` of another step in this config. An empty array means this is a terminal step (no follow-ups).",
+          "description": "Valid next steps.",
           "default": [],
           "type": "array",
           "items": {
@@ -309,7 +237,7 @@
           }
         },
         "options": {
-          "description": "Per-step options that override the global `options`. Only the fields you set here take effect; everything else falls through to the global defaults.",
+          "description": "Per-step options that override global options.",
           "default": {
             "max_retries": null,
             "retry_on_invalid_response": null,
@@ -323,31 +251,23 @@
           ]
         },
         "post": {
-          "description": "Shell script that runs **after** the action completes (or fails).\n\n**stdin:** A tagged JSON object describing the outcome. The `kind` field indicates what happened:\n\n- `{\"kind\": \"Success\", \"input\": <value>, \"output\": <agent_output>, \"next\": [<tasks>]}` — Action succeeded. `next` contains the follow-up tasks to spawn. - `{\"kind\": \"Timeout\", \"input\": <value>}` — Action timed out. - `{\"kind\": \"Error\", \"input\": <value>, \"error\": \"<message>\"}` — Action failed. - `{\"kind\": \"PreHookError\", \"input\": <value>, \"error\": \"<message>\"}` — Pre hook failed.\n\n**stdout:** The same tagged JSON object, possibly modified. Typically you modify the `next` array in `Success` to filter, rewrite, or add follow-up tasks.",
+          "description": "Post-execution hook script.",
           "default": null,
-          "anyOf": [
-            {
-              "$ref": "#/definitions/PostHook"
-            },
-            {
-              "type": "null"
-            }
+          "type": [
+            "string",
+            "null"
           ]
         },
         "pre": {
-          "description": "Shell script that runs **before** the action.\n\n**stdin:** The task's `value` payload as JSON (e.g., `{\"path\": \"/src\"}`). This is just the value — not the full `{\"kind\": ..., \"value\": ...}` wrapper.\n\n**stdout:** The (possibly modified) value payload as JSON. Must be the same shape. The modified value is what the action receives.\n\nUse this to enrich or transform the task before the action sees it (e.g., adding timestamps, resolving paths, fetching metadata).",
+          "description": "Pre-execution hook script.",
           "default": null,
-          "anyOf": [
-            {
-              "$ref": "#/definitions/PreHook"
-            },
-            {
-              "type": "null"
-            }
+          "type": [
+            "string",
+            "null"
           ]
         },
         "value_schema": {
-          "description": "JSON Schema that validates the `value` payload for tasks on this step. When set, tasks whose `value` doesn't conform are rejected. When omitted, any JSON value is accepted.",
+          "description": "JSON Schema for validating the step's value payload. None means any JSON value is accepted.",
           "default": null,
           "anyOf": [
             {
@@ -362,11 +282,11 @@
       "additionalProperties": false
     },
     "StepOptions": {
-      "description": "Per-step option overrides. Only set the fields you want to override; omitted fields inherit from the global `options`.",
+      "description": "Per-step options that override global defaults.",
       "type": "object",
       "properties": {
         "max_retries": {
-          "description": "Maximum retries for tasks on this step (overrides global `max_retries`).",
+          "description": "Maximum retries for this step (overrides global).",
           "default": null,
           "type": [
             "integer",
@@ -376,7 +296,7 @@
           "minimum": 0.0
         },
         "retry_on_invalid_response": {
-          "description": "Whether to retry when an agent returns an invalid response on this step (overrides global `retry_on_invalid_response`).",
+          "description": "Whether to retry on invalid response for this step (overrides global).",
           "default": null,
           "type": [
             "boolean",
@@ -384,7 +304,7 @@
           ]
         },
         "retry_on_timeout": {
-          "description": "Whether to retry when an agent times out on this step (overrides global `retry_on_timeout`).",
+          "description": "Whether to retry on timeout for this step (overrides global).",
           "default": null,
           "type": [
             "boolean",
@@ -392,7 +312,7 @@
           ]
         },
         "timeout": {
-          "description": "Timeout in seconds for tasks on this step (overrides global `timeout`).",
+          "description": "Timeout in seconds for this step (overrides global).",
           "default": null,
           "type": [
             "integer",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@barnum/barnum",
-  "version": "0.0.0-main-04a1bb17",
+  "version": "0.2.0",
   "description": "Barnum CLI - workflow engine for agents.",
   "main": "index.js",
   "bin": {