hermes-workflow 0.1.3__py3-none-any.whl

hermes_workflow/__init__.py

@@ -0,0 +1,37 @@
+# src/hermes_workflow/__init__.py
+"""hermes-workflow: declarative workflow primitive over Hermes Kanban."""
+import pathlib
+
+from hermes_workflow.version import PLUGIN_VERSION
+from hermes_workflow import tools, hooks
+
+
+def register(ctx):
+    """Wire every hermes-workflow surface into the Hermes plugin context.
+
+    Tools + CLI + slash are orchestrator-context mutators (they self-refuse inside
+    a worker). Both hooks are bound to ``ctx`` via a closure because Hermes' hook
+    invoke does NOT pass ctx (post_tool_call fan-out + pre_tool_call completion gate).
+    """
+    for name, fn, schema in tools.TOOL_SPECS:
+        ctx.register_tool(name=name, toolset="workflow", schema=schema,
+                          handler=tools.make_tool_handler(ctx, fn))
+
+    ctx.register_hook("post_tool_call", lambda **kw: hooks.on_tool_done(ctx=ctx, **kw))
+    ctx.register_hook("pre_tool_call", lambda **kw: hooks.on_tool_pre(ctx=ctx, **kw))
+
+    ctx.register_cli_command("workflow", help="manage hermes-workflow runs",
+                             setup_fn=tools.cli_setup,
+                             handler_fn=lambda args: tools.cli_dispatch(ctx, args))
+    ctx.register_command("workflow", lambda raw: tools.slash_dispatch(ctx, raw),
+                         description="Manage hermes-workflow runs",
+                         args_hint="<start|status|validate|reconcile|approve|abandon>")
+
+    # Bundled skills are shipped in Phase 4; guard the (currently absent) dir so
+    # register stays crash-free until then.
+    skills_dir = pathlib.Path(__file__).parent / "skills"
+    if skills_dir.is_dir():
+        for child in sorted(p for p in skills_dir.iterdir() if (p / "SKILL.md").exists()):
+            ctx.register_skill(child.name, child / "SKILL.md")
+
+    getattr(ctx, "log", None) and ctx.log.info("hermes-workflow %s registered", PLUGIN_VERSION)

hermes_workflow/board.py

@@ -0,0 +1,126 @@
+# src/hermes_workflow/board.py
+"""Board adapter: two surfaces over the Hermes Kanban.
+
+WorkerBoard wraps the worker/hook *model-tool* surface (kanban_create/link/
+comment/show) via ``ctx.dispatch_tool(name, args) -> JSON string``. Every call
+gets an explicit ``board`` injected so it never relies on ambient env routing.
+
+HostBoard wraps the orchestrator/CLI *host* surface (kb.* functions) for the
+operations that have NO model tool — archive/unlink (Hermes finding Y) — plus a
+board-wide list/reclaim. It is constructed with an already board-scoped conn.
+"""
+import json
+
+from hermes_workflow.version import SENTINEL_ROOT_ASSIGNEE
+
+
+class WorkerBoard:
+    """Model-tool surface, reached through a dispatch context.
+
+    ``ctx`` only needs ``dispatch_tool(tool_name, args, **kwargs) -> str``.
+    """
+
+    def __init__(self, ctx, board):
+        self.ctx = ctx
+        self.board = board
+
+    def _call(self, tool, args):
+        """Dispatch a kanban tool with an explicit board, return parsed JSON.
+
+        Immutability: build a NEW args dict — never mutate the caller's.
+        """
+        payload = {**args, "board": self.board}
+        return json.loads(self.ctx.dispatch_tool(tool, payload))
+
+    def create(self, *, title, parents=(), assignee=SENTINEL_ROOT_ASSIGNEE,
+               workspace_kind="scratch", workspace_path=None, body="",
+               skills=None, idempotency_key=None):
+        # Always pass workspace_kind explicitly: if BOTH workspace_kind and
+        # workspace_path are omitted, _handle_create INHERITS the calling
+        # worker's workspace (kanban_tools.py:746-794). Passing them keeps the
+        # child's workspace deterministic.
+        r = self._call("kanban_create", {
+            "title": title,
+            "assignee": assignee,
+            "parents": list(parents) if parents else [],
+            "workspace_kind": workspace_kind,
+            "workspace_path": workspace_path,
+            "body": body,
+            "skills": skills,
+            "idempotency_key": idempotency_key,
+        })
+        if not r.get("ok"):
+            raise BoardError(f"kanban_create failed: {r}")
+        return r["task_id"]
+
+    def link(self, parent_id, child_id):
+        r = self._call("kanban_link", {"parent_id": parent_id, "child_id": child_id})
+        if not r.get("ok"):
+            raise BoardError(f"kanban_link failed: {r}")
+        return r
+
+    def comment(self, task_id, body):
+        r = self._call("kanban_comment", {"task_id": task_id, "body": body})
+        if not r.get("ok"):
+            raise BoardError(f"kanban_comment failed: {r}")
+        return r
+
+    def complete(self, *, task_id, summary=None):
+        r = self._call("kanban_complete", {"task_id": task_id, "summary": summary})
+        if not r.get("ok"):
+            raise BoardError(f"kanban_complete failed: {r}")
+        return r
+
+    def show(self, task_id):
+        """Return a FLAT card dict.
+
+        kanban_show (kanban_tools.py:339-412) returns a NESTED shape:
+        ``{"task": {...}, "parents": [...], "children": [...], "runs": [...],
+        "comments": [...], ...}`` — NOT an _ok envelope. Downstream Phase-2 code
+        (RunView/materializer/hooks) wants a single flat card, so this is the
+        one place we normalize: merge the ``task`` sub-dict up to the top level
+        and re-attach the link/run/comment lists.
+        """
+        raw = self._call("kanban_show", {"task_id": task_id})
+        if "task" not in raw:
+            # Error envelope ({"error": ...}/{"ok": false}) or a missing card.
+            raise BoardError(f"kanban_show returned no task for {task_id!r}: {raw}")
+        task = raw["task"]
+        return {
+            **task,
+            "parents": raw.get("parents", []),
+            "children": raw.get("children", []),
+            "runs": raw.get("runs", []),
+            "comments": raw.get("comments", []),
+            "events": raw.get("events", []),
+        }
+
+
+class HostBoard:
+    """Host kb.* surface for orchestrator/CLI-only operations.
+
+    The ``conn`` is already board-scoped, so kb.* calls take no ``board=``
+    kwarg. ``board`` is retained for identity/logging.
+    """
+
+    def __init__(self, kb, conn, board):
+        self.kb = kb
+        self.conn = conn
+        self.board = board
+
+    def list(self):
+        """Board-wide sweep (the conn is already board-scoped)."""
+        return self.kb.list_tasks(self.conn)
+
+    def archive(self, task_id):
+        return self.kb.archive_task(self.conn, task_id)
+
+    def unlink(self, parent_id, child_id):
+        return self.kb.unlink_tasks(self.conn, parent_id, child_id)
+
+    def reclaim(self, task_id):
+        return self.kb.reclaim_task(self.conn, task_id)
+
+
+class BoardError(RuntimeError):
+    """Raised when a kanban model-tool call returns a non-ok / error payload."""

hermes_workflow/engine/graph.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+from dataclasses import dataclass, field
+from hermes_workflow.engine.interpolate import interpolate
+from hermes_workflow.engine.model import Template, Stage
+from hermes_workflow.lanes.presets import lane_skill
+
+GATE_ASSIGNEE = "_workflow_gate"   # mirrors version.SENTINEL_GATE_ASSIGNEE
+
+
+@dataclass(frozen=True)
+class Identity:
+    stage_id: str
+    fan_index: int
+    attempt: int = 0
+
+
+@dataclass
+class CardSpec:
+    identity: Identity
+    title: str
+    body: str
+    assignee: str
+    workspace: str
+    parent_identities: list      # list[Identity]; NOTE: list (a test asserts == [Identity(...)])
+    skills: list = field(default_factory=list)
+    gate: bool = False
+
+
+def _expanded(stage: Stage, completed: dict):
+    """The source stage's emitted item list, or None if the source isn't done yet."""
+    src = completed.get(stage.expand.over_stage)
+    if src is None:
+        return None  # source not done -> stage not materializable
+    return list(src.get(stage.expand.over_key, []))
+
+
+def _parents_for(stage: Stage, t: Template, completed: dict) -> list:
+    """Parent identities: for each needed stage, every instance that exists/should exist."""
+    parents = []
+    for dep in stage.needs:
+        dep_stage = t.stage(dep)
+        if dep_stage.expand:
+            items = _expanded(dep_stage, completed)
+            if items is None:
+                continue
+            if items:
+                parents += [Identity(dep, i, 0) for i in range(len(items))]
+            else:
+                # empty fan-out: gate the consumer on the fan-out SOURCE instead
+                parents.append(Identity(dep_stage.expand.over_stage, 0, 0))
+        else:
+            parents.append(Identity(dep, 0, 0))
+    return parents
+
+
+def _materializable(stage: Stage, t: Template, completed: dict) -> bool:
+    """A stage is materializable once every fan-out it depends on (incl. its own) has a done source."""
+    for dep in stage.needs:
+        dep_stage = t.stage(dep)
+        if dep_stage.expand and _expanded(dep_stage, completed) is None:
+            return False  # waiting on the fan-out source to complete
+    if stage.expand and _expanded(stage, completed) is None:
+        return False
+    return True
+
+
+def cards_for_run(t: Template, params: dict, bindings: dict, *, completed: dict, existing: set) -> list:
+    specs: list = []
+    for stage in t.stages:
+        if not _materializable(stage, t, completed):
+            continue
+        instances = _expanded(stage, completed) if stage.expand else [None]
+        if instances is None:
+            continue
+        for idx, item in enumerate(instances):
+            ident = Identity(stage.id, idx if stage.expand else 0, 0)
+            if ident in existing:
+                continue
+            evars = {stage.expand.as_var: item} if (stage.expand and item is not None) else {}
+            assignee = bindings.get(stage.role, GATE_ASSIGNEE) if stage.role else GATE_ASSIGNEE
+            lane = t.roles[stage.role].lane if stage.role else None
+            specs.append(CardSpec(
+                identity=ident,
+                title=interpolate(stage.title, params=params, expand_vars=evars),
+                body=interpolate(stage.body, params=params, expand_vars=evars),
+                assignee=assignee,
+                workspace=interpolate(stage.workspace, params=params, expand_vars={}),
+                parent_identities=_parents_for(stage, t, completed),
+                skills=([lane_skill(lane)] if lane and lane_skill(lane) else []),
+                gate=stage.gate == "human",
+            ))
+    return specs

hermes_workflow/engine/interpolate.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+import re
+
+_TOKEN = re.compile(r"\$\{([^}]+)\}")
+
+
+class InterpolationError(ValueError):
+    pass
+
+
+def interpolate(s: str, *, params: dict, expand_vars: dict) -> str:
+    """Substitute only ${params.*} and ${<expand-var>.*}; raise on any unknown ref/namespace."""
+    def repl(m):
+        ref = m.group(1).strip()
+        ns, _, rest = ref.partition(".")
+        if ns == "params":
+            if rest not in params:
+                raise InterpolationError(f"unknown param {rest!r}")
+            return str(params[rest])
+        if ns in expand_vars:
+            obj = expand_vars[ns]
+            if rest not in obj:
+                raise InterpolationError(f"unknown field {rest!r} on {ns!r}")
+            return str(obj[rest])
+        raise InterpolationError(f"unknown reference namespace {ns!r}")
+    return _TOKEN.sub(repl, s)

hermes_workflow/engine/model.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Param:
+    name: str
+    type: str
+    required: bool = False
+    default: object = None
+
+
+@dataclass(frozen=True)
+class Role:
+    name: str
+    lane: str  # "profile" | "codex"
+
+
+@dataclass(frozen=True)
+class ExpandSpec:
+    over_stage: str
+    over_key: str
+    as_var: str
+
+
+@dataclass(frozen=True)
+class ExpandOut:
+    key: str
+    item: dict          # field_name -> type string
+    max: int = 50
+
+
+@dataclass(frozen=True)
+class Stage:
+    id: str
+    role: str | None = None
+    title: str = ""
+    body: str = ""
+    needs: tuple = ()
+    expand: ExpandSpec | None = None
+    expand_out: ExpandOut | None = None
+    gate: str | None = None          # "human" or None
+    workspace: str = "scratch"       # scratch | dir:<p> | worktree:<p>
+    verify_raw: object = None        # raw `verify:` block, captured so Task 8 can REJECT it (0.2.x)
+
+
+@dataclass(frozen=True)
+class Template:
+    name: str
+    version: str
+    description: str
+    params: dict           # name -> Param
+    roles: dict            # name -> Role
+    stages: tuple          # tuple[Stage]
+
+    def stage(self, sid: str) -> Stage:
+        for s in self.stages:
+            if s.id == sid:
+                return s
+        raise KeyError(sid)

hermes_workflow/engine/provenance.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+import base64
+import json
+from dataclasses import dataclass, asdict
+
+_SENTINEL_OPEN = "<!--hermes-workflow:sentinel "
+_SENTINEL_CLOSE = "-->"
+_SNAPSHOT_OPEN = "<!--hermes-workflow:snapshot "
+
+
+def _encode(obj) -> str:
+    # Base64 alphabet is [A-Za-z0-9+/=], which cannot contain '-->', so the
+    # first '-->' after the open marker is always the genuine terminator.
+    return base64.b64encode(json.dumps(obj).encode("utf-8")).decode("ascii")
+
+
+def _decode(raw: str):
+    return json.loads(base64.b64decode(raw.encode("ascii"), validate=True).decode("utf-8"))
+
+
+@dataclass(frozen=True)
+class Sentinel:
+    workflow_root: str
+    stage_id: str
+    fan_index: int
+    attempt: int
+    template_id: str
+    template_version: str
+    plugin_version: str
+    schema_version: str
+
+
+@dataclass(frozen=True)
+class CompiledSnapshot:
+    template_yaml: str
+    params: dict
+    bindings: dict
+    plugin_version: str
+    schema_version: str
+    base_ref: str | None = None
+
+
+def embed_sentinel(body: str, s: Sentinel) -> str:
+    return f"{_SENTINEL_OPEN}{_encode(asdict(s))}{_SENTINEL_CLOSE}\n{body}"
+
+
+def extract_sentinel(body: str) -> Sentinel | None:
+    i = body.find(_SENTINEL_OPEN)
+    if i < 0:
+        return None
+    j = body.find(_SENTINEL_CLOSE, i)
+    if j < 0:
+        return None
+    raw = body[i + len(_SENTINEL_OPEN):j].strip()
+    try:
+        return Sentinel(**_decode(raw))
+    except Exception:
+        return None
+
+
+def build_root_body(template_yaml: str, params: dict, bindings: dict,
+                    plugin_version: str, schema_version: str, base_ref=None) -> str:
+    payload = {"template_yaml": template_yaml, "params": params, "bindings": bindings,
+               "plugin_version": plugin_version, "schema_version": schema_version,
+               "base_ref": base_ref}
+    return f"{_SNAPSHOT_OPEN}{_encode(payload)}{_SENTINEL_CLOSE}\n# hermes-workflow run\n"
+
+
+def parse_root_body(body: str) -> CompiledSnapshot:
+    # RAISES by design on a malformed/non-snapshot body: callers
+    # (tools.py::_root_snapshot, hooks.py) wrap this in try/except and rely on
+    # it raising. A corrupt root snapshot must wedge loudly (fail-closed at the
+    # veto / WorkflowError at reconcile), never fail soft. Do NOT add a
+    # swallowing try/except here.
+    i = body.find(_SNAPSHOT_OPEN)
+    j = body.find(_SENTINEL_CLOSE, i)
+    payload = _decode(body[i + len(_SNAPSHOT_OPEN):j].strip())
+    return CompiledSnapshot(**payload)
+
+
+def is_version_compatible(snapshot, supported) -> bool:
+    """Total: never raises. Returns False for anything it cannot positively confirm.
+
+    (Spike 1: a raising gate fails OPEN at the host, so we must fail CLOSED by
+    returning False.) The try/except wraps both ``set(supported)`` and the
+    membership test so a bad ``supported`` (e.g. None) yields False, not an error.
+    """
+    if isinstance(supported, (str, bytes)):
+        return False  # a bare string would set()-split per character -> false-accept
+    try:
+        return getattr(snapshot, "schema_version", None) in set(supported)
+    except Exception:
+        return False

hermes_workflow/engine/reconcile.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+from dataclasses import dataclass
+
+_STATUS_RANK = {"done": 5, "running": 4, "ready": 3, "todo": 2, "blocked": 1, "archived": 0}
+
+
+@dataclass(frozen=True)
+class CardRow:
+    card_id: str
+    status: str
+    latest_run_id: int | None = None
+    created_at: float = 0.0
+
+
+def pick_winner(rows: list[CardRow]) -> CardRow:
+    """Deterministic winner among duplicates sharing one sentinel identity.
+    A 'done' duplicate wins unconditionally (status rank); tiebreak by
+    latest_run_id -> created_at -> min(card_id). Falls back to status rank
+    when none is 'done'.
+    """
+    if not rows:
+        raise ValueError("pick_winner: no rows")
+    # Sort key for min(): negate the higher-is-better fields (status rank, run_id,
+    # created_at) so the largest wins; card_id stays plain so the smallest (min) wins.
+    return min(rows, key=lambda r: (
+        -_STATUS_RANK.get(r.status, 0),
+        -(r.latest_run_id if r.latest_run_id is not None else -1),
+        -r.created_at,
+        r.card_id,
+    ))

hermes_workflow/engine/template.py

@@ -0,0 +1,111 @@
+from __future__ import annotations
+import re
+import yaml
+from hermes_workflow.engine.model import Param, Role, ExpandSpec, ExpandOut, Stage, Template
+
+_WS_TOKEN = re.compile(r"\$\{([^}]+)\}")
+
+
+class TemplateError(ValueError):
+    pass
+
+
+def parse_template(text: str) -> Template:
+    try:
+        raw = yaml.safe_load(text)
+    except yaml.YAMLError as e:
+        raise TemplateError(f"invalid YAML: {e}") from e
+    if not isinstance(raw, dict):
+        raise TemplateError("template must be a YAML mapping")
+    params = {n: Param(n, p.get("type", "string"), bool(p.get("required", False)), p.get("default"))
+              for n, p in (raw.get("params") or {}).items()}
+    roles = {n: Role(n, r.get("lane", "profile")) for n, r in (raw.get("roles") or {}).items()}
+    stages = []
+    for s in raw.get("stages") or []:
+        exp = s.get("expand")
+        expand = None
+        if exp:
+            over = exp["over"]
+            if "." not in over:
+                raise TemplateError(f"stage {s.get('id')!r}: expand.over must be '<stage>.<key>', got {over!r}")
+            st, key = over.split(".", 1)   # "<stage>.<key>"
+            expand = ExpandSpec(st, key, exp["as"])
+        eo = s.get("expand_out")
+        expand_out = ExpandOut(eo["key"], eo.get("item", {}), int(eo.get("max", 50))) if eo else None
+        stages.append(Stage(
+            id=s["id"], role=s.get("role"), title=s.get("title", ""), body=s.get("body", ""),
+            needs=tuple(s.get("needs", [])), expand=expand, expand_out=expand_out,
+            gate=s.get("gate"), workspace=s.get("workspace", "scratch"),
+            verify_raw=s.get("verify"),
+        ))
+    return Template(raw["name"], str(raw["version"]), raw.get("description", ""),
+                    params, roles, tuple(stages))
+
+
+def validate_template(t: Template) -> None:
+    """Deterministic gatekeeper. Raises TemplateError on the first rule violation."""
+    ids = [s.id for s in t.stages]
+    dupes = sorted({sid for sid in ids if ids.count(sid) > 1})
+    if dupes:
+        raise TemplateError(f"duplicate stage id(s): {', '.join(dupes)}")
+    id_set = set(ids)
+    expand_sources = {s.expand.over_stage for s in t.stages if s.expand}
+
+    for s in t.stages:
+        # gate vs role
+        if s.gate is not None:
+            if s.gate != "human":
+                raise TemplateError(
+                    f"stage {s.id}: only 'gate: human' is supported in 0.1.0, got {s.gate!r}")
+            if s.role is not None:
+                raise TemplateError(f"stage {s.id}: a gate stage must not declare a role")
+        elif s.role is None:
+            raise TemplateError(f"stage {s.id}: non-gate stage needs a role")
+        if s.role is not None and s.role not in t.roles:
+            raise TemplateError(f"stage {s.id}: unknown role {s.role!r}")
+
+        for dep in s.needs:
+            if dep not in id_set:
+                raise TemplateError(f"stage {s.id}: needs unknown stage {dep!r}")
+
+        if s.verify_raw is not None:
+            raise TemplateError(f"stage {s.id}: verify.command/retry is deferred to 0.2.x")
+
+        if s.expand:
+            src = t.stage(s.expand.over_stage) if s.expand.over_stage in id_set else None
+            if src is None:
+                raise TemplateError(
+                    f"stage {s.id}: expand.over references unknown stage {s.expand.over_stage!r}")
+            if not src.expand_out or src.expand_out.key != s.expand.over_key:
+                raise TemplateError(
+                    f"stage {s.id}: expand.over key must match source expand_out.key")
+            if s.id in expand_sources:
+                raise TemplateError(f"stage {s.id}: nested expand is forbidden in 0.1.0")
+
+        for tok in _WS_TOKEN.findall(s.workspace):
+            if not tok.strip().startswith("params."):
+                raise TemplateError(
+                    f"stage {s.id}: workspace may only use ${{params.*}}, got {tok!r}")
+        if s.expand and s.workspace.split(":", 1)[0] == "scratch":
+            raise TemplateError(f"stage {s.id}: fan-out stages must not use scratch workspace")
+
+    _check_cycle(t)
+
+
+def _check_cycle(t: Template) -> None:
+    graph = {s.id: set(s.needs) for s in t.stages}
+    visiting, done = set(), set()
+
+    def dfs(n):
+        if n in done:
+            return
+        if n in visiting:
+            raise TemplateError(f"dependency cycle at stage {n!r}")
+        visiting.add(n)
+        for m in graph.get(n, ()):
+            dfs(m)
+        visiting.discard(n)
+        done.add(n)
+
+    for n in graph:
+        dfs(n)