#!/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 --project --context run-context.yaml [--dry-run] kab_run_workflow.py start --workflow --project --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 kab_run_workflow.py review continue|stop|rerun [--note "..."] kab_run_workflow.py outputs --out `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: "" 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())