Files
cp1-agents/scripts/kab_run_workflow.py
Jonathan Boniface f659564208 Platform scripts, MCP servers, deployment and docs for the KAB runs
- Scripts to run workflows from a YAML context or run inputs (kab_run_workflow.py, with
  --input name=@file), store per-project discovery connections, bootstrap agent MCP keys,
  refresh the KAB token, publish reports and build estate snapshots.
- Hyperscaler discovery servers extended in place; cloud-knowledge folded into them.
- deploy/crucible-kab-dev.yaml: the Discovery package agent and the Assessment agents.
- Platform issue write-ups and current-wiring notes under docs/platform-issues/.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-05 22:13:25 +00:00

217 lines
10 KiB
Python

#!/usr/bin/env python3
"""Run a saved KAB workflow from the command line: the same API the KAB app uses.
kab_run_workflow.py start --workflow <id> --project <id> --context run-context.yaml [--dry-run]
kab_run_workflow.py start --workflow <id> --project <id> --input engagement_id=ENG-1 --input run_id=RUN-1 \\
--file brief.txt [--dry-run]
A run is normally started from a YAML context file (--context): its `workflow_inputs:` become the run's inputs, and
the whole file is uploaded to the workflow's upload step, so the agents also read its `context:` section. Files its
`uploads:` list names (beside it, e.g. a CMDB export) are uploaded after it, in order.
kab_run_workflow.py status <execution id>
kab_run_workflow.py review <execution id> continue|stop|rerun [--note "..."]
kab_run_workflow.py outputs <execution id> --out <folder>
`review` answers the pause the run is waiting at. It's a person's decision, so it is never made automatically.
The token comes from $KAB_TOKEN or ~/.kab_token, and lasts five minutes: scripts/kab_token.py refreshes it. A run
doesn't need the token once started.
"""
from __future__ import annotations
import argparse
import base64
import secrets
import json
from datetime import datetime, timezone
import os
import sys
import urllib.error
import urllib.request
from pathlib import Path
DEFAULT_API = "https://api.kab-dev.kyndemo.live"
CP1_TENANT = "6ae37d13999438461a529409"
class Kab:
def __init__(self, api: str, tenant: str, project: str | None = None) -> None:
path = Path.home() / ".kab_token"
token = os.getenv("KAB_TOKEN") or (path.read_text().strip() if path.exists() else "")
if not token:
raise SystemExit("No token: run scripts/kab_token.py")
self.api = api.rstrip("/")
self.headers = {"Authorization": f"Bearer {token}", "X-Tenant-ID": tenant, "Content-Type": "application/json"}
if project:
self.headers["X-Project-ID"] = project
def call(self, method: str, path: str, body: dict | None = None):
data = json.dumps(body).encode() if body is not None else None
request = urllib.request.Request(f"{self.api}{path}", data=data, headers=self.headers, method=method)
try:
with urllib.request.urlopen(request, timeout=120) as response:
return json.load(response)
except urllib.error.HTTPError as error:
raise SystemExit(f"{method} {path}: HTTP {error.code}: {error.read()[:500].decode(errors='replace')}")
def start(kab: Kab, args) -> int:
found = kab.call("GET", f"/api/v1/workflow-catalog/workflows/{args.workflow}")
workflow = found.get("workflow", found)
template = workflow.get("template") or workflow
sample = kab.call("GET", f"/api/workflows/{args.workflow}/api-sample")
# Flat: the API applies step-keyed inputs to the first step only, and every step's from_workflow reads these.
# A value written as a JSON list is a list input, e.g. --input 'artifact_ids=["6aec..."]'; `@path` reads the value
# from a file, e.g. --input rate_card_document=@rate-card.json.
def value(v: str):
if v.startswith("@"):
return Path(v[1:]).read_text()
return json.loads(v) if v.lstrip().startswith("[") else v
inputs: dict = {k: value(v) for k, v in (item.split("=", 1) for item in args.input)}
if args.context:
if args.file:
raise SystemExit("Use --context or --file, not both: the upload field takes one file.")
given = load_context(Path(args.context))
clash = sorted(set(given) & set(inputs))
if clash:
raise SystemExit(f"{', '.join(clash)} given both in {args.context} and with --input: keep one.")
if "run_id" in given or "run_id" in inputs:
raise SystemExit("run_id is generated for every run: remove it from the context file and --input.")
inputs.update(given)
generated = new_ids()
inputs["run_id"] = generated["run_id"]
args.upload = ("# Added by kab_run_workflow.py when the run started. Never edit these by hand.\n"
f"generated:\n" + "".join(f" {k}: {v}\n" for k, v in generated.items()) + "\n"
+ Path(args.context).read_text()).encode()
args.file = args.context
args.uploads = context_uploads(Path(args.context))
print(f"Generated: {json.dumps(generated)}")
missing = sorted(f"{i['step_id']}.{i['name']}" for i in sample.get("required", [])
if i["name"] != "file" and i["name"] not in inputs)
if missing:
raise SystemExit(f"Missing inputs: {', '.join(missing)}. Pass them with --input name=value.")
if args.file:
path = Path(args.file)
content = base64.b64encode(getattr(args, "upload", None) or path.read_bytes()).decode()
kind = upload_type(path)
inputs["file"] = [{"name": path.name, "content": f"data:{kind};base64,{content}"}]
for extra in getattr(args, "uploads", []):
data = base64.b64encode(extra.read_bytes()).decode()
inputs["file"].append({"name": extra.name, "content": f"data:{upload_type(extra)};base64,{data}"})
if len(inputs["file"]) > 1:
print(f"Uploads: {', '.join(f['name'] for f in inputs['file'])}")
shown = {k: "<file>" if k == "file" else (f"<{len(v)} characters>" if isinstance(v, str) and len(v) > 200 else v)
for k, v in inputs.items()}
print(f"Workflow: {template.get('name')}\nInputs: {json.dumps(shown)}")
if args.dry_run:
print("Dry run. Nothing started.")
return 0
result = kab.call("POST", "/api/workflows/execute", {"template": template, "inputs": inputs})
print(f"Started: execution_id={result.get('execution_id')} status={result.get('status')}")
return 0
def upload_type(path: Path) -> str:
return {".csv": "text/csv", ".json": "application/json", ".yaml": "application/x-yaml", ".yml": "application/x-yaml",
".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"}.get(path.suffix, "text/plain")
def context_uploads(path: Path) -> list:
"""The files a context file's `uploads:` lists, beside it, uploaded after it in order (e.g. a CMDB export)."""
import yaml
listed = (yaml.safe_load(path.read_text()) or {}).get("uploads") or []
files = []
for entry in listed:
name = entry.get("name") if isinstance(entry, dict) else entry
extra = (path.parent / str(name)).resolve()
if extra.parent != path.parent.resolve() or not extra.is_file():
raise SystemExit(f"{path}: uploads entry {name!r} must be a file in the same folder as the context file")
files.append(extra)
return files
def new_ids() -> dict:
"""A run's unique identifiers: UTC time to the second, then 6 random hex digits, so two starts never collide."""
now = datetime.now(timezone.utc)
run_id = f"RUN-{now:%Y%m%dT%H%M%SZ}-{secrets.token_hex(3)}"
return {"run_id": run_id, "plan_id": f"PLAN-{run_id}", "started_at": f"{now:%Y-%m-%dT%H:%M:%SZ}"}
def load_context(path: Path) -> dict:
"""The run inputs from a YAML context file's `workflow_inputs:`, as the strings the workflow expects."""
try:
import yaml
except ImportError:
raise SystemExit("--context needs PyYAML (pip install pyyaml)")
doc = yaml.safe_load(path.read_text())
if not isinstance(doc, dict) or not isinstance(doc.get("workflow_inputs"), dict):
raise SystemExit(f"{path}: expected a `workflow_inputs:` mapping (and, optionally, `context:`)")
out = {}
for key, value in doc["workflow_inputs"].items():
if isinstance(value, bool):
value = "yes" if value else "no"
if not isinstance(value, (str, int, float)):
raise SystemExit(f"{path}: workflow_inputs.{key} must be a single value")
out[str(key)] = str(value)
return out
def status(kab: Kab, args) -> int:
run = kab.call("GET", f"/api/workflows/status/{args.execution}")
print(json.dumps({k: v for k, v in run.items() if k not in ("result", "inputs", "outputs", "step_results")}, default=str)[:1200])
reviews = kab.call("GET", f"/api/workflows/executions/{args.execution}/reviews")
print("Reviews:", json.dumps(reviews, default=str)[:2500])
return 0
def review(kab: Kab, args) -> int:
reviews = kab.call("GET", f"/api/workflows/executions/{args.execution}/reviews")
pending = reviews.get("pending") or []
if len(pending) != 1:
raise SystemExit(f"Expected one pause, found {len(pending)}: {json.dumps(pending)[:400]}")
checkpoint = pending[0]["checkpoint_id"]
result = kab.call("POST", f"/api/workflows/executions/{args.execution}/reviews/{checkpoint}",
{"decision": args.decision, "note": args.note})
print(json.dumps(result, default=str)[:600])
return 0
def outputs(kab: Kab, args) -> int:
folder = Path(args.out)
folder.mkdir(parents=True, exist_ok=True)
found = kab.call("GET", f"/api/workflows/executions/{args.execution}/steps")
(folder / "steps.json").write_text(json.dumps(found, indent=1, default=str))
print(f"Wrote {folder / 'steps.json'}")
return 0
def main() -> int:
parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
parser.add_argument("--api", default=DEFAULT_API)
parser.add_argument("--tenant", default=CP1_TENANT)
commands = parser.add_subparsers(dest="command", required=True)
run = commands.add_parser("start")
run.add_argument("--workflow", required=True)
run.add_argument("--project", required=True)
run.add_argument("--input", action="append", default=[], metavar="name=value")
run.add_argument("--file")
run.add_argument("--context", help="a YAML run context file: workflow_inputs become the run inputs; the file is uploaded")
run.add_argument("--dry-run", action="store_true")
run.set_defaults(handler=start, execution=None)
for name, handler in (("status", status), ("outputs", outputs), ("review", review)):
command = commands.add_parser(name)
command.add_argument("execution")
command.set_defaults(handler=handler)
if name == "review":
command.add_argument("decision", choices=["continue", "stop", "rerun"])
command.add_argument("--note", default="")
if name == "outputs":
command.add_argument("--out", required=True)
args = parser.parse_args()
kab = Kab(args.api, args.tenant, getattr(args, "project", None))
return args.handler(kab, args)
if __name__ == "__main__":
sys.exit(main())