akm-cli 0.9.0-rc.0 → 0.9.0-rc.2

package/dist/schemas/akm-task.json

@@ -0,0 +1,87 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://itlackey.github.io/akm/schemas/akm-task.json",
+  "title": "AKM Scheduled Task",
+  "description": "Strict version-2 YAML task definition. Exactly one target is required.",
+  "type": "object",
+  "required": ["version", "schedule"],
+  "additionalProperties": false,
+  "properties": {
+    "version": { "const": 2 },
+    "name": { "type": "string" },
+    "description": { "type": "string" },
+    "when_to_use": { "type": "string" },
+    "tags": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+    "schedule": { "type": "string", "minLength": 1 },
+    "enabled": { "type": "boolean" },
+    "workflow": { "type": "string", "minLength": 1 },
+    "prompt": { "type": "string", "minLength": 1 },
+    "command": {
+      "oneOf": [
+        { "type": "string", "minLength": 1 },
+        { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } }
+      ]
+    },
+    "params": { "type": "object" },
+    "engine": { "type": "string", "minLength": 1 },
+    "model": { "type": "string", "minLength": 1 },
+    "timeoutMs": { "type": ["integer", "null"], "minimum": 1 },
+    "llm": { "$ref": "#/definitions/llm" }
+  },
+  "oneOf": [
+    {
+      "required": ["workflow"],
+      "not": { "anyOf": [{ "required": ["prompt"] }, { "required": ["command"] }, { "required": ["engine"] }, { "required": ["model"] }, { "required": ["timeoutMs"] }, { "required": ["llm"] }] }
+    },
+    {
+      "required": ["prompt"],
+      "not": { "anyOf": [{ "required": ["workflow"] }, { "required": ["command"] }, { "required": ["params"] }] }
+    },
+    {
+      "required": ["command"],
+      "not": { "anyOf": [{ "required": ["workflow"] }, { "required": ["prompt"] }, { "required": ["params"] }, { "required": ["engine"] }, { "required": ["model"] }, { "required": ["llm"] }] }
+    }
+  ],
+  "definitions": {
+    "llm": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "temperature": { "type": "number" },
+        "maxTokens": { "type": "integer", "minimum": 1 },
+        "supportsJsonSchema": { "type": "boolean" },
+        "extraParams": { "$ref": "#/definitions/extraParams" },
+        "contextLength": { "type": "integer", "minimum": 1 },
+        "enableThinking": { "type": "boolean" }
+      }
+    },
+    "extraParams": {
+      "type": "object",
+      "description": "Provider-specific request fields. Top-level AKM-owned fields are forbidden; credential-shaped keys are forbidden recursively after lowercase/non-alphanumeric normalization.",
+      "propertyNames": {
+        "not": {
+          "enum": ["model", "messages", "temperature", "maxtokens", "responseformat", "stream", "streamoptions", "enablethinking", "authorization", "headers", "apikey", "token", "password", "secret", "cookie", "setcookie"]
+        }
+      },
+      "additionalProperties": { "$ref": "#/definitions/extraParamValue" },
+      "x-akm-protectedTopLevelNormalizedKeys": ["model", "messages", "temperature", "maxtokens", "responseformat", "stream", "streamoptions", "enablethinking"],
+      "x-akm-recursivelyForbiddenNormalizedKeys": ["authorization", "headers", "apikey", "token", "password", "secret", "cookie", "setcookie"]
+    },
+    "extraParamValue": {
+      "anyOf": [
+        { "type": ["string", "number", "boolean", "null"] },
+        { "type": "array", "items": { "$ref": "#/definitions/extraParamValue" } },
+        {
+          "type": "object",
+          "propertyNames": {
+            "not": {
+              "enum": ["authorization", "headers", "apikey", "token", "password", "secret", "cookie", "setcookie"]
+            }
+          },
+          "additionalProperties": { "$ref": "#/definitions/extraParamValue" },
+          "x-akm-recursivelyForbiddenNormalizedKeys": ["authorization", "headers", "apikey", "token", "password", "secret", "cookie", "setcookie"]
+        }
+      ]
+    }
+  }
+}

package/dist/schemas/akm-workflow.json

@@ -0,0 +1,372 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://itlackey.github.io/akm/schemas/akm-workflow.json",
+  "title": "AKM Workflow Program",
+  "description": "YAML workflow program for the akm CLI (Agent Knowledge Management). Files live under workflows/ with extension .yaml or .yml. Hand-authored alongside src/workflows/program/schema.ts; the enum vocabularies and patterns here are pinned against the TypeScript constants by tests/workflows/program-parser.test.ts — update both together.",
+  "type": "object",
+  "required": ["version", "name", "steps"],
+  "additionalProperties": false,
+  "properties": {
+    "version": {
+      "const": 2,
+      "description": "Workflow program format version. Only 2 is valid."
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Workflow name."
+    },
+    "description": {
+      "type": "string",
+      "description": "Optional human-readable description."
+    },
+    "params": {
+      "type": "object",
+      "maxProperties": 128,
+      "description": "Run parameters: param name -> JSON Schema declaration. Names must be ${{ params.<name> }}-addressable identifiers.",
+      "propertyNames": {
+        "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
+      },
+      "additionalProperties": {
+        "$ref": "#/definitions/jsonSchemaObject"
+      }
+    },
+    "defaults": {
+      "$ref": "#/definitions/defaults"
+    },
+    "budget": {
+      "$ref": "#/definitions/budget"
+    },
+    "steps": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 256,
+      "items": {
+        "$ref": "#/definitions/step"
+      }
+    }
+  },
+  "definitions": {
+    "identifier": {
+      "type": "string",
+      "pattern": "^[A-Za-z_][A-Za-z0-9_-]*$",
+      "description": "Step id: a letter or underscore first, then letters, digits, underscores, or dashes (no dots, no leading digit). This is exactly the ${{ steps.<id>.output }}-addressable grammar; dots are reserved for the .output path separator and the engine's internal <stepId>.gate node id."
+    },
+    "timeout": {
+      "description": "Duration: \"<n>ms\" | \"<n>s\" | \"<n>m\" | \"none\" (bare integers are milliseconds).",
+      "oneOf": [
+        {
+          "type": "string",
+          "pattern": "^([0-9]+(ms|s|m)?|none)$"
+        },
+        {
+          "type": "integer",
+          "minimum": 1
+        }
+      ]
+    },
+    "onError": {
+      "description": "Failure policy: fail the step on the first unit failure (default), or record failures and let the gate decide.",
+      "enum": ["fail", "continue"]
+    },
+    "llm": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "temperature": { "type": "number" },
+        "max_tokens": { "type": "integer", "minimum": 1 },
+        "supports_json_schema": { "type": "boolean" },
+        "extra_params": { "$ref": "#/definitions/extraParams" },
+        "context_length": { "type": "integer", "minimum": 1 },
+        "enable_thinking": { "type": "boolean" }
+      }
+    },
+    "extraParams": {
+      "type": "object",
+      "description": "Provider-specific request fields. Top-level AKM-owned fields are forbidden; credential-shaped keys are forbidden recursively after lowercase/non-alphanumeric normalization.",
+      "propertyNames": {
+        "not": {
+          "enum": ["model", "messages", "temperature", "maxtokens", "responseformat", "stream", "streamoptions", "enablethinking", "authorization", "headers", "apikey", "token", "password", "secret", "cookie", "setcookie"]
+        }
+      },
+      "additionalProperties": { "$ref": "#/definitions/extraParamValue" },
+      "x-akm-protectedTopLevelNormalizedKeys": ["model", "messages", "temperature", "maxtokens", "responseformat", "stream", "streamoptions", "enablethinking"],
+      "x-akm-recursivelyForbiddenNormalizedKeys": ["authorization", "headers", "apikey", "token", "password", "secret", "cookie", "setcookie"]
+    },
+    "extraParamValue": {
+      "anyOf": [
+        { "type": ["string", "number", "boolean", "null"] },
+        { "type": "array", "items": { "$ref": "#/definitions/extraParamValue" } },
+        {
+          "type": "object",
+          "propertyNames": {
+            "not": {
+              "enum": ["authorization", "headers", "apikey", "token", "password", "secret", "cookie", "setcookie"]
+            }
+          },
+          "additionalProperties": { "$ref": "#/definitions/extraParamValue" },
+          "x-akm-recursivelyForbiddenNormalizedKeys": ["authorization", "headers", "apikey", "token", "password", "secret", "cookie", "setcookie"]
+        }
+      ]
+    },
+    "reducer": {
+      "description": "How a map step folds per-item unit results into the step artifact.",
+      "enum": ["collect", "vote"]
+    },
+    "isolation": {
+      "description": "Filesystem isolation for file-mutating units (enforcement lands in R2).",
+      "enum": ["none", "worktree"]
+    },
+    "failureReason": {
+      "description": "Persisted AgentFailureReason taxonomy (src/integrations/agent/spawn.ts).",
+      "enum": [
+        "timeout",
+        "spawn_failed",
+        "non_zero_exit",
+        "parse_error",
+        "cooldown",
+        "llm_rate_limit",
+        "llm_content_filter",
+        "llm_invalid_json",
+        "content_policy_reject",
+        "unsupported_type",
+        "no_change",
+        "aborted"
+      ]
+    },
+    "jsonSchemaObject": {
+      "type": "object",
+      "description": "A JSON Schema declaration (validated as a schema by the compiler, not here)."
+    },
+    "retry": {
+      "type": "object",
+      "description": "Bounded retry on transient failures, keyed on the persisted failure_reason taxonomy.",
+      "required": ["max", "on"],
+      "additionalProperties": false,
+      "properties": {
+        "max": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Maximum retry attempts per unit."
+        },
+        "on": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "$ref": "#/definitions/failureReason"
+          }
+        }
+      }
+    },
+    "budget": {
+      "type": "object",
+      "description": "Run-level budget ceilings, enforced by the engine per run (journal-seeded). Hitting a ceiling fails the step hard, regardless of on_error.",
+      "additionalProperties": false,
+      "properties": {
+        "max_tokens": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Ceiling on total reported token usage across the run (seeded from journaled unit rows)."
+        },
+        "max_units": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 10000,
+          "description": "Ceiling on total dispatched units across the run (seeded from journaled unit rows)."
+        }
+      }
+    },
+    "defaults": {
+      "type": "object",
+      "description": "Run-level defaults, overridable per unit.",
+      "additionalProperties": false,
+      "properties": {
+        "engine": {
+          "type": "string",
+          "minLength": 1
+        },
+        "model": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Model alias (tier) or exact id; resolved per-harness at dispatch."
+        },
+        "timeout": {
+          "$ref": "#/definitions/timeout"
+        },
+        "on_error": {
+          "$ref": "#/definitions/onError"
+        },
+        "llm": {
+          "$ref": "#/definitions/llm"
+        }
+      }
+    },
+    "unit": {
+      "type": "object",
+      "description": "A single dispatchable unit: instructions plus dispatch overrides.",
+      "required": ["instructions"],
+      "additionalProperties": false,
+      "properties": {
+        "engine": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Named engine selected at workflow start."
+        },
+        "model": {
+          "type": "string",
+          "minLength": 1
+        },
+        "llm": {
+          "$ref": "#/definitions/llm"
+        },
+        "timeout": {
+          "$ref": "#/definitions/timeout"
+        },
+        "retry": {
+          "$ref": "#/definitions/retry"
+        },
+        "on_error": {
+          "$ref": "#/definitions/onError"
+        },
+        "instructions": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Instruction template. ${{ … }} expressions are parsed against the closed grammar: params.<name> | steps.<id>.output.<path> | item | item_index."
+        },
+        "output": {
+          "$ref": "#/definitions/jsonSchemaObject"
+        },
+        "env": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "description": "Env asset refs injected into the dispatched unit env."
+        },
+        "isolation": {
+          "$ref": "#/definitions/isolation"
+        }
+      }
+    },
+    "map": {
+      "type": "object",
+      "description": "Fan the unit template out over an expression-addressed item list.",
+      "required": ["over", "unit"],
+      "additionalProperties": false,
+      "properties": {
+        "over": {
+          "type": "string",
+          "minLength": 1,
+          "description": "${{ … }} expression naming the producer of the item list (e.g. ${{ steps.discover.output.files }})."
+        },
+        "concurrency": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Max concurrent units for this step; capped by the engine's global limit."
+        },
+        "reducer": {
+          "$ref": "#/definitions/reducer"
+        },
+        "unit": {
+          "$ref": "#/definitions/unit"
+        }
+      }
+    },
+    "route": {
+      "type": "object",
+      "description": "Route on an explicit ${{ … }} input to a LATER step. Targets must come after the routing step.",
+      "required": ["input", "when"],
+      "additionalProperties": false,
+      "properties": {
+        "input": {
+          "type": "string",
+          "minLength": 1,
+          "description": "${{ … }} expression naming the value to route on."
+        },
+        "when": {
+          "type": "object",
+          "minProperties": 1,
+          "maxProperties": 256,
+          "description": "Match value -> target step id.",
+          "additionalProperties": {
+            "$ref": "#/definitions/identifier"
+          }
+        },
+        "default": {
+          "$ref": "#/definitions/identifier"
+        }
+      }
+    },
+    "gate": {
+      "type": "object",
+      "description": "Completion gate criteria judged against the step artifact.",
+      "required": ["criteria"],
+      "additionalProperties": false,
+      "properties": {
+        "criteria": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "max_loops": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Evaluator-optimizer loop bound (execution lands in R2)."
+        },
+        "required": {
+          "type": "boolean",
+          "description": "When true, the gate must be judged: if no summary-validation judge is available (offline / misconfigured LLM), the step BLOCKS for a human instead of failing open and silently passing. Absent = fail-open default. The engine's --require-gates flag applies this to every criteria-bearing gate for one invocation."
+        }
+      }
+    },
+    "step": {
+      "type": "object",
+      "description": "One step of the gated spine. Exactly one of unit | map | route.",
+      "required": ["id"],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "$ref": "#/definitions/identifier"
+        },
+        "title": {
+          "type": "string",
+          "minLength": 1
+        },
+        "unit": {
+          "$ref": "#/definitions/unit"
+        },
+        "map": {
+          "$ref": "#/definitions/map"
+        },
+        "route": {
+          "$ref": "#/definitions/route"
+        },
+        "output": {
+          "$ref": "#/definitions/jsonSchemaObject"
+        },
+        "gate": {
+          "$ref": "#/definitions/gate"
+        }
+      },
+      "allOf": [
+        {
+          "oneOf": [
+            {
+              "required": ["unit"]
+            },
+            {
+              "required": ["map"]
+            },
+            {
+              "required": ["route"]
+            }
+          ]
+        }
+      ]
+    }
+  }
+}