workgraph 0.3.3__py3-none-any.whl

workgraph/codex.py

@@ -0,0 +1,232 @@
+"""The Codex harness: argv, result reading, and transcript rendering."""
+
+import json
+import tempfile
+from collections.abc import Iterator, Sequence
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Any
+
+import tomlkit
+from rich.text import Text
+
+from workgraph.harness import (
+    AgentInvocation,
+    NodeFailure,
+    iter_jsonl_events,
+    read_last_value,
+    split_lines,
+)
+
+# USD per million tokens: uncached input, cached input, cache write, output.
+# A Pro model offers no cached input discount, so its cached rate is its input rate.
+# Source: https://developers.openai.com/api/docs/pricing, read 2026-09-05.
+MODEL_RATES: dict[str, tuple[float, float, float, float]] = {
+    "gpt-6-astra": (10.00, 1.00, 12.50, 50.00),
+    "gpt-5.6-sol": (4.00, 0.40, 5.00, 20.00),
+    "gpt-5.6": (4.00, 0.40, 5.00, 20.00),  # the documented alias of gpt-5.6-sol
+    "gpt-daybreak-blue-latest": (4.00, 0.40, 5.00, 20.00),  # the Daybreak alias of gpt-5.6-sol
+    "gpt-5.6-cyber": (12.50, 1.25, 15.625, 75.00),
+    "gpt-daybreak-red-latest": (12.50, 1.25, 15.625, 75.00),  # the Daybreak alias of gpt-5.6-cyber
+    "gpt-5.6-terra": (2.00, 0.20, 2.50, 12.00),
+    "gpt-5.6-luna": (0.20, 0.02, 0.25, 1.20),
+    "gpt-5.5": (5.00, 0.50, 0.0, 30.00),
+    "gpt-5.5-pro": (30.00, 30.00, 0.0, 180.00),
+    "gpt-5.4": (2.50, 0.25, 0.0, 15.00),
+    "gpt-5.4-mini": (0.75, 0.075, 0.0, 4.50),
+    "gpt-5.4-nano": (0.20, 0.02, 0.0, 1.25),
+    "gpt-5.4-pro": (30.00, 30.00, 0.0, 180.00),
+    "gpt-5.3-codex": (1.75, 0.175, 0.0, 14.00),
+    "gpt-5.2": (1.75, 0.175, 0.0, 14.00),
+    "gpt-5.1": (1.25, 0.125, 0.0, 10.00),
+    "gpt-5": (1.25, 0.125, 0.0, 10.00),
+    "gpt-5-mini": (0.25, 0.025, 0.0, 2.00),
+    "gpt-5-nano": (0.05, 0.005, 0.0, 0.40),
+    "gpt-5-pro": (15.00, 15.00, 0.0, 120.00),
+}
+
+
+def _build_strict_schema(outcome_schema: dict[str, Any]) -> dict[str, Any]:
+    """Adapt the outcome schema to OpenAI strict mode, which Codex structured output requires.
+
+    Strict mode forbids extra properties and requires every property, so an absent handoff
+    comes back as null.
+    """
+    properties = dict(outcome_schema["properties"])
+    properties["handoff"] = {**properties["handoff"], "type": ["string", "null"]}
+    return {
+        **outcome_schema,
+        "properties": properties,
+        "required": list(properties),
+        "additionalProperties": False,
+    }
+
+
+def _format_toml_string(value: str) -> str:
+    """Format a string as the TOML basic string a `-c` override takes.
+
+    A JSON string with raw non-ASCII characters is a TOML basic string, and ensure_ascii=False
+    avoids the surrogate-pair escapes TOML rejects.
+    """
+    return json.dumps(value, ensure_ascii=False)
+
+
+@contextmanager
+def build_argv(invocation: AgentInvocation) -> Iterator[list[str]]:
+    """Yield the argv that runs the agent through the Codex CLI.
+
+    The outcome schema lives in a temporary file for the duration of the with block.
+    """
+    session = invocation.session
+    with tempfile.NamedTemporaryFile("w", suffix=".json") as schema_file:
+        schema_file.write(json.dumps(_build_strict_schema(invocation.outcome_schema)))
+        schema_file.flush()
+        # A resumed session already holds the developer instructions, and `codex exec resume`
+        # has no --sandbox flag, so the sandbox goes as a configuration override.
+        session_dependent_argv = (
+            [
+                "--sandbox",
+                invocation.sandbox,
+                "-c",
+                f"developer_instructions={_format_toml_string(invocation.agent_definition['prompt'])}",
+            ]
+            if session is None
+            else ["-c", f"sandbox_mode={_format_toml_string(invocation.sandbox)}"]
+        )
+        argv = [
+            "codex",
+            "exec",
+            *([] if session is None else ["resume", session]),
+            "--json",
+            # The target directory of a run is any directory; codex exec refuses a non-git one.
+            "--skip-git-repo-check",
+            "--model",
+            invocation.model,
+            "-c",
+            f"model_reasoning_effort={_format_toml_string(invocation.effort)}",
+            *session_dependent_argv,
+            "--output-schema",
+            schema_file.name,
+        ]
+        if invocation.web_search is not None:
+            web_search = tomlkit.inline_table()
+            web_search["value"] = invocation.web_search
+            argv += ["-c", f"tools.web_search={tomlkit.item(web_search['value']).as_string()}"]
+        # The prompt is any text; `--` keeps one starting with a hyphen out of the options.
+        yield [*argv, "--", invocation.prompt]
+
+
+def _read_auth_mode() -> str:
+    """Return the Codex login mode; without a readable auth file, Codex runs on an API key."""
+    auth_file = Path.home() / ".codex" / "auth.json"
+    try:
+        return str(json.loads(auth_file.read_text()).get("auth_mode", "apikey"))
+    except (OSError, ValueError, AttributeError):
+        return "apikey"
+
+
+def _estimate_cost_usd(model: str, usage: Any) -> float:
+    """Estimate the USD cost of the usage at list API prices for the model.
+
+    Cost is secondary to the run: an unknown model or unexpected usage yields 0, never a failure.
+    """
+    if model not in MODEL_RATES or not isinstance(usage, dict):
+        return 0.0
+    input_rate, cached_rate, cache_write_rate, output_rate = MODEL_RATES[model]
+    if _read_auth_mode() == "chatgpt":
+        # A ChatGPT login pays nothing for cache writes.
+        cache_write_rate = 0.0
+    try:
+        input_tokens = int(usage["input_tokens"])
+        cached_tokens = int(usage.get("cached_input_tokens", 0))
+        cache_write_tokens = int(usage.get("cache_write_input_tokens", 0))
+        output_tokens = int(usage["output_tokens"])
+    except (KeyError, TypeError, ValueError):
+        return 0.0
+    # Reasoning tokens are a breakdown of the output tokens, not an addition.
+    uncached_tokens = input_tokens - cached_tokens - cache_write_tokens
+    if min(uncached_tokens, cached_tokens, cache_write_tokens, output_tokens) < 0:
+        return 0.0
+    return (
+        uncached_tokens * input_rate
+        + cached_tokens * cached_rate
+        + cache_write_tokens * cache_write_rate
+        + output_tokens * output_rate
+    ) / 1_000_000
+
+
+def read_result(invocation: AgentInvocation, stdout_lines: Sequence[str]) -> tuple[Any, float]:
+    """Return the structured output of the last agent message and the estimated cost."""
+    agent_node_name = invocation.agent_node_name
+    last_agent_message = None
+    usage = None
+    for event in iter_jsonl_events(stdout_lines):
+        event_type = event.get("type")
+        if event_type in ("turn.failed", "error"):
+            # A turn.failed carries its message under `error`; an error event carries it directly.
+            error = event.get("error")
+            error_message = event.get("message") or (
+                error.get("message") if isinstance(error, dict) else error
+            )
+            raise NodeFailure(f"node '{agent_node_name}': agent reported an error: {error_message}")
+        item = event.get("item")
+        if (
+            event_type == "item.completed"
+            and isinstance(item, dict)
+            and item.get("type") == "agent_message"
+            and isinstance(item.get("text"), str)
+        ):
+            last_agent_message = item["text"]
+        if event_type == "turn.completed":
+            usage = event.get("usage")
+    if last_agent_message is None:
+        raise NodeFailure(f"node '{agent_node_name}': agent output holds no agent message")
+    try:
+        structured_output = json.loads(last_agent_message)
+    except json.JSONDecodeError:
+        structured_output = None
+    return structured_output, _estimate_cost_usd(invocation.model, usage)
+
+
+def read_session(stdout_lines: Sequence[str]) -> str | None:
+    """Return the session the last thread.started event names by its Codex thread id."""
+    thread_events = (
+        event for event in iter_jsonl_events(stdout_lines) if event.get("type") == "thread.started"
+    )
+    return read_last_value(thread_events, "thread_id")
+
+
+def _read_narration(agent_message_text: str) -> str | None:
+    """Return the handoff of a schema-shaped agent message, else the text itself.
+
+    Under --output-schema Codex shapes every agent message like the outcome, so the narration
+    of a message sits in its handoff.
+    """
+    try:
+        handoff: str | None = json.loads(agent_message_text)["handoff"]
+    except (json.JSONDecodeError, TypeError, KeyError):
+        return agent_message_text
+    return handoff
+
+
+def render_transcript(stdout_lines: Sequence[str]) -> list[Text]:
+    """Render the narration of the agent messages, command executions, and file changes.
+
+    Reasoning and every other item are dropped.
+    """
+    completed_items = [
+        event["item"]
+        for event in iter_jsonl_events(stdout_lines)
+        if event.get("type") == "item.completed" and isinstance(event.get("item"), dict)
+    ]
+    transcript_rows: list[Text] = []
+    for item in completed_items:
+        match item.get("type"):
+            case "agent_message":
+                transcript_rows += split_lines(_read_narration(item["text"]))
+            case "command_execution":
+                transcript_rows.append(Text(f"▸ command_execution: {item['command']}", "bold"))
+            case "file_change":
+                paths = ", ".join(change["path"] for change in item["changes"])
+                transcript_rows.append(Text(f"▸ file_change: {paths}", "bold"))
+    return transcript_rows

workgraph/definitions/agents/wg_code-review.md

@@ -0,0 +1,14 @@
+---
+name: wg_code-review
+description: Reviews the branch's diff against the merge-base for standards and spec.
+tools: Bash, Read, Glob, Grep, Skill, Task
+---
+Invoke the `/mattpocock-skills:code-review` skill over the branch's diff
+against the merge-base with the default branch. The skill runs the Standards
+and Spec axes in parallel sub-agents.
+
+Your job is this review only. The workflow's other nodes implement and open
+the PR: do not change code and do not open a PR.
+
+Report `pass` when both axes are clean. Otherwise report `fail` and list
+every finding in the handoff.

workgraph/definitions/agents/wg_design.md

@@ -0,0 +1,57 @@
+---
+name: wg_design
+description: Makes sure the change the run input names has an agent brief.
+tools: Bash, Read, Glob, Grep
+---
+The run input names a GitHub issue in this repository, or a task with no
+issue. Read the issue with `gh issue view <number> --comments`. Take the
+owner and the repo from `git remote -v`. Where `gh` is unavailable, read
+`https://api.github.com/repos/<owner>/<repo>/issues/<number>` and its
+`/comments` with `curl`, and post or edit through the same API with `curl`
+and the `GITHUB_TOKEN` environment variable. Do not modify the repository.
+
+An agent brief is the issue body or an issue comment whose text contains the
+heading `## Agent Brief`. Its link is the issue URL
+(`https://github.com/<owner>/<repo>/issues/<number>`) when the brief is in the
+body, and the comment's `html_url`
+(`https://github.com/<owner>/<repo>/issues/<number>#issuecomment-<id>`) when
+the brief is in a comment. `gh api repos/<owner>/<repo>/issues/<number>/comments`
+gives the comment ids, bodies, and `html_url` values. When several comments
+hold a brief, the last one is the brief.
+
+## The four cases
+
+1. No handoff and the issue carries a brief: do no other work. Report `done`
+   with the brief's link on one line as the handoff.
+2. No handoff and the issue carries no brief: read the code the issue
+   touches, write the brief, and post it with
+   `gh issue comment <number> --body-file <file>` from a temporary file
+   outside the repository. Read the new comment's link with
+   `gh api repos/<owner>/<repo>/issues/<number>/comments --jq '.[-1].html_url'`
+   and report `done` with that link as the handoff.
+3. A handoff with `received` and `feedback`: `received` holds the brief's
+   link. `feedback` holds the feedback on the rejected brief. Rewrite the
+   brief to address every point of the feedback, keeping the first line and
+   the seven sections. Edit it in place with
+   `gh api --method PATCH repos/<owner>/<repo>/issues/comments/<id> -F body=@<file>`
+   for a comment and `gh issue edit <number> --body-file <file>` for the body.
+   Report `done` with the same link as the handoff.
+4. The run input names no issue: write the brief from the run input and the
+   code, and report `done` with the whole brief as the handoff. A later
+   handoff then carries the brief itself under `received`; revise it to
+   address every point of `feedback` and report the revised brief inline
+   again.
+
+## Brief shape
+
+Write the brief under the AGENTS.md writing rules. Its first line is
+`> *This was generated by AI as the design node.*`. The heading
+`## Agent Brief` follows, then seven sections:
+
+- **Category**: the kind of change.
+- **Summary**: one sentence.
+- **Current behavior**: what the code does today.
+- **Desired behavior**: what it does after the change.
+- **Key interfaces**: the names and types the change touches.
+- **Acceptance criteria**: a checklist of independently verifiable items.
+- **Out of scope**: what the change leaves alone.

workgraph/definitions/agents/wg_implement.md

@@ -0,0 +1,39 @@
+---
+name: wg_implement
+description: Implements a GitHub issue in the current repository.
+tools: Bash, Read, Edit, Write, Glob, Grep, Skill
+---
+The run input names a GitHub issue in this repository, or a task with no
+issue. Read the issue with `gh issue view <number> --comments`. Take the
+owner and the repo from `git remote -v`. Where `gh` is unavailable, read
+`https://api.github.com/repos/<owner>/<repo>/issues/<number>` and its
+`/comments` with `curl`.
+
+## The plan
+
+The plan comes from the first of these that holds:
+
+1. The handoff, when it is one line holding an issue comment link
+   (`https://github.com/<owner>/<repo>/issues/<number>#issuecomment-<id>`).
+   Read the plan with
+   `gh api repos/<owner>/<repo>/issues/comments/<id> --jq .body`.
+2. Else the issue's last comment whose text contains the heading
+   `## Implementation Plan`, from
+   `gh api repos/<owner>/<repo>/issues/<number>/comments`.
+3. Else the plan in the prompt, for a run whose input names no issue.
+
+Follow the plan task by task, one commit per task, with the task's commit
+summary. On re-entry from `test` or `review-loop`, the handoff is not the
+plan, so locate the plan on the issue and still address every finding the
+handoff carries.
+
+Implement what the issue asks:
+
+- Follow the repository standards in AGENTS.md.
+- Use the `/mattpocock-skills:tdd` skill where possible.
+- Run typechecking and single test files regularly, and the full test suite
+  once at the end.
+- Commit the work to the current branch.
+
+Report `done` when the implementation and its tests are complete and
+committed.

workgraph/definitions/agents/wg_overengineering-review.md

@@ -0,0 +1,13 @@
+---
+name: wg_overengineering-review
+description: Reviews the branch's diff against the merge-base for over-engineering.
+tools: Bash, Read, Glob, Grep, Skill
+---
+Invoke the `/ponytail:ponytail-review` skill over the branch's diff against
+the merge-base with the default branch.
+
+Your job is this review only. The workflow's other nodes implement and open
+the PR: do not change code and do not open a PR.
+
+Report `pass` when there are no findings. Otherwise report `fail` and list
+the findings in the handoff.

workgraph/definitions/agents/wg_plan.md

@@ -0,0 +1,79 @@
+---
+name: wg_plan
+description: Makes sure the change the run input names has an implementation plan.
+tools: Bash, Read, Glob, Grep
+---
+The run input names a GitHub issue in this repository, or a task with no
+issue. Read the issue with `gh issue view <number> --comments`. Take the
+owner and the repo from `git remote -v`. Where `gh` is unavailable, read
+`https://api.github.com/repos/<owner>/<repo>/issues/<number>` and its
+`/comments` with `curl`, and post or edit through the same API with `curl`
+and the `GITHUB_TOKEN` environment variable. Do not modify the repository.
+
+The handoff on entry from `approve-design` carries the link of the issue's
+agent brief, or the brief itself when the run input names no issue. The brief
+is the body or the comment at the link, under the heading `## Agent Brief`.
+The plan follows the brief: its tasks implement the brief's desired behavior
+and stay inside its scope.
+
+An implementation plan is an issue comment whose text contains the heading
+`## Implementation Plan`. Its link is the comment's `html_url`
+(`https://github.com/<owner>/<repo>/issues/<number>#issuecomment-<id>`).
+`gh api repos/<owner>/<repo>/issues/<number>/comments` gives the comment ids,
+bodies, and `html_url` values. When several comments hold a plan, the last one
+is the plan.
+
+## The four cases
+
+1. The handoff holds the brief's link and the issue carries a plan: do no
+   other work. Report `done` with the plan's link on one line as the handoff.
+2. The handoff holds the brief's link and the issue carries no plan: read the
+   brief, read the code the issue touches, write the plan, and post it with
+   `gh issue comment <number> --body-file <file>` from a temporary file
+   outside the repository. Read the new comment's link with
+   `gh api repos/<owner>/<repo>/issues/<number>/comments --jq '.[-1].html_url'`
+   and report `done` with that link on one line as the handoff.
+3. A handoff with `received` and `feedback`: `received` holds the plan's link.
+   `feedback` holds the feedback on the rejected plan. Rewrite the plan to
+   address every point of the feedback, keeping the first line and the
+   heading. Edit it in place with
+   `gh api --method PATCH repos/<owner>/<repo>/issues/comments/<id> -F body=@<file>`.
+   Report `done` with the same link as the handoff.
+4. The run input names no issue: write the plan from the brief and the code,
+   and report `done` with the whole plan as the handoff. A later handoff then
+   carries the plan itself under `received`; revise it to address every point
+   of `feedback` and report the revised plan inline again.
+
+## Plan shape
+
+Write the plan under the AGENTS.md writing rules. Use file paths, never
+line numbers. Do not use code blocks.
+
+The plan's first line is `> *This was generated by AI as the plan node.*`.
+The heading `## Implementation Plan` follows, then:
+
+1. Header:
+   - **Goal**: one sentence.
+   - **Approach**: two or three sentences.
+   - **Issue**: `#<number>`.
+2. **Files**: every file created or modified, one line each on its
+   responsibility.
+3. **Tasks**, in order. A task is the smallest unit with its own test cycle
+   that a reviewer could reject on its own. Setup, configuration, and
+   documentation belong to the task that needs them. Each task lists:
+   - the files it touches;
+   - the interfaces it consumes from earlier tasks and produces for later
+     ones, with exact names and types;
+   - its tests, described by behavior;
+   - its commit summary.
+
+Do not write placeholders: no "TBD", no "add error handling", no "similar
+to task N", no reference to a name that no task defines.
+
+## Self-check
+
+Before reporting, check the plan against the brief:
+
+- every acceptance criterion of the brief maps to a task;
+- no placeholder remains;
+- a name used in several tasks is the same in all of them.

workgraph/definitions/agents/wg_pr.md

@@ -0,0 +1,33 @@
+---
+name: wg_pr
+description: Squashes the branch to one commit and creates or updates the pull request.
+tools: Bash, Read, Glob, Grep
+---
+The run input names a GitHub issue in this repository.
+
+1. Run `git fetch origin main`, then squash the branch to exactly one
+   commit on top of `origin/main` with a rebase or `git commit --amend`,
+   then `git push --force-with-lease`. Never use the local `main`: it is
+   stale. The branch carries only this run's commits; never rewrite
+   history containing someone else's commits.
+2. Rewrite the commit message to fit the rules below, amend, and push
+   again. Do not just validate — fix any violation yourself.
+3. Create the pull request for the branch with `gh pr create`, or update
+   the existing one with `gh pr edit`. Never merge it.
+4. When the prompt carries a handoff from `summary`, add a `Not addressed`
+   section to the PR body that lists every finding in it.
+
+Rules for the commit message and the PR text:
+
+- Commit message: one summary line, then at most one paragraph of 3–5
+  sentences, then a final line `Closes #<number>` that names the issue
+  from the run input.
+- PR title: the commit summary line, verbatim.
+- PR description: the first line is `Closes #<number>`, naming the issue
+  from the run input. The rest is more detailed than the commit message,
+  at most 3 sections plus the `Not addressed` section, formatted with
+  markdown; itemized lists replace long paragraphs and sentences.
+- Everywhere: simple sentences, active voice, and one term per concept —
+  reuse the terms the repository already uses instead of varying them.
+
+Report `done` when the PR exists and matches the branch.

workgraph/definitions/agents/wg_summarize-review.md

@@ -0,0 +1,10 @@
+---
+name: wg_summarize-review
+description: Summarizes the findings of the last review as not addressed.
+---
+The prompt carries a handoff from `review` with the findings of the last
+review. Those findings, and only those, are not addressed. Summarize them:
+one bullet per finding, naming its location and what it asks for. When the
+prompt carries no handoff from `review`, report `done` with no handoff.
+
+Report `done` with the summary as the handoff.

workgraph/definitions/workflows/wg.toml

@@ -0,0 +1,101 @@
+start = "design"
+
+[defaults]
+harness = "claude"
+model = "claude-fable-5-1"
+effort = "high"
+
+[nodes.design]
+agent = "wg_design"
+effort = "xhigh"
+outcomes = ["done"]
+
+[nodes.design.transitions]
+done = "approve-design"
+
+[nodes.approve-design]
+gate = "Plan from this design?"
+
+[nodes.approve-design.transitions]
+accept = "plan"
+reject = "design"
+
+[nodes.plan]
+agent = "wg_plan"
+effort = "xhigh"
+outcomes = ["done"]
+
+[nodes.plan.transitions]
+done = "approve-plan"
+
+[nodes.approve-plan]
+gate = "Implement this plan?"
+
+[nodes.approve-plan.transitions]
+accept = "implement"
+reject = "plan"
+
+[nodes.implement]
+agent = "wg_implement"
+model = "claude-opus-5"
+outcomes = ["done"]
+
+[nodes.implement.transitions]
+done = "test"
+
+[nodes.test]
+command = "sh -c 'uv run ruff check && uv run ruff format --check && uv run mypy && uv run pytest'"
+
+[nodes.test.limits]
+visits = 5
+reset = "pass"
+
+[nodes.test.transitions]
+pass = "review"
+fail = "implement"
+
+[nodes.review]
+map = ["code-review", "overengineering-review"]
+resolve = "all"
+
+[nodes.review.transitions]
+pass = "pr"
+fail = "review-loop"
+
+# Holds the review limit so the LIMIT diversion carries the review findings.
+[nodes.review-loop]
+command = "true"
+
+[nodes.review-loop.limits]
+visits = 2
+
+[nodes.review-loop.transitions]
+pass = "implement"
+fail = "implement"
+LIMIT = "summary"
+
+[nodes.code-review]
+agent = "wg_code-review"
+outcomes = ["pass", "fail"]
+
+[nodes.overengineering-review]
+agent = "wg_overengineering-review"
+outcomes = ["pass", "fail"]
+
+[nodes.summary]
+agent = "wg_summarize-review"
+model = "sonnet"
+effort = "medium"
+outcomes = ["done"]
+
+[nodes.summary.transitions]
+done = "pr"
+
+[nodes.pr]
+agent = "wg_pr"
+model = "haiku"
+effort = "medium"
+outcomes = ["done"]
+
+[nodes.pr.transitions]
+done = "END"