@zerwiz/ymir 0.1.33 → 0.1.35

package/apps/smidja-factory/templates/smidja/smidja_modules/tracer.py

@@ -0,0 +1,271 @@
+"""Tracer: every event lands in JSONL and SQLite AS IT HAPPENS.
+
+Files are the raw record; smidja.db is the queryable mirror the UI polls.
+No push transport — the flow is always: agents -> sqlite -> web ui.
+WAL mode so the UI can read while smidja processes write.
+"""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+from pathlib import Path
+
+from .data_types import AgentConfig, EventRecord, GateReport, Phase
+from .utils import ensure_dir, new_id, now_iso
+
+SCHEMA = """
+CREATE TABLE IF NOT EXISTS sessions (
+  smidja_id        TEXT PRIMARY KEY,
+  smidja_name      TEXT,                -- smidja script(s) run, e.g. "smidja_plan + smidja_build_test"
+  request       TEXT,
+  status        TEXT,
+  engineer      TEXT,
+  started_at    TEXT, ended_at TEXT,
+  total_tokens  INTEGER DEFAULT 0, total_cost REAL DEFAULT 0,
+  archived      INTEGER DEFAULT 0   -- review triage, set by the UI; never by a run
+);
+CREATE TABLE IF NOT EXISTS phases (
+  phase_id      TEXT PRIMARY KEY,
+  smidja_id        TEXT REFERENCES sessions,
+  seq           INTEGER,
+  name TEXT, kind TEXT, owner TEXT, description TEXT,
+  status        TEXT DEFAULT 'fail',
+  attempt       INTEGER DEFAULT 0, retries INTEGER DEFAULT 0,
+  error         TEXT,
+  started_at    TEXT, ended_at TEXT
+);
+CREATE TABLE IF NOT EXISTS events (
+  event_id      TEXT PRIMARY KEY,
+  smidja_id        TEXT REFERENCES sessions,
+  phase_id      TEXT REFERENCES phases,
+  parent_id     TEXT,
+  type          TEXT,
+  name          TEXT,
+  payload_json  TEXT,
+  tokens        INTEGER,
+  started_at    TEXT, ended_at TEXT
+);
+CREATE TABLE IF NOT EXISTS envelopes (
+  envelope_id   TEXT PRIMARY KEY,
+  smidja_id        TEXT REFERENCES sessions,
+  phase_id      TEXT REFERENCES phases,
+  agent         TEXT,
+  output_type   TEXT,
+  payload_json  TEXT,
+  valid         INTEGER,
+  attempt       INTEGER,
+  created_at    TEXT
+);
+CREATE TABLE IF NOT EXISTS gate_results (
+  id            INTEGER PRIMARY KEY AUTOINCREMENT,
+  smidja_id        TEXT REFERENCES sessions,
+  phase_id      TEXT REFERENCES phases,
+  attempt       INTEGER,
+  gate          TEXT,
+  passed        INTEGER,
+  violations_json TEXT,
+  checks_json   TEXT,               -- [{item, ok, note}] — WHAT the gate verified
+  created_at    TEXT
+);
+CREATE TABLE IF NOT EXISTS processes (
+  id            INTEGER PRIMARY KEY AUTOINCREMENT,
+  smidja_id        TEXT REFERENCES sessions,
+  kind          TEXT,                -- 'smidja' (the workflow process) | 'agent' (a coding-agent child)
+  name          TEXT,                -- '' for the smidja, the agent name for a child
+  pid           INTEGER,
+  command       TEXT,                -- what the pid was, so a recycled pid is not killed by mistake
+  started_at    TEXT, ended_at TEXT  -- ended_at NULL = believed alive
+);
+CREATE TABLE IF NOT EXISTS agent_sessions (
+  smidja_id        TEXT REFERENCES sessions,
+  agent         TEXT,
+  coding_agent  TEXT, model TEXT, color TEXT,
+  session_id    TEXT,
+  context_tokens INTEGER,           -- window occupancy after the agent's last turn
+  context_window INTEGER,           -- the model's ceiling; 0/NULL = unknown
+  created_at    TEXT, last_used_at TEXT,
+  PRIMARY KEY (smidja_id, agent)
+);
+"""
+
+# Columns added after a schema shipped. CREATE TABLE IF NOT EXISTS never
+# revisits an existing table, so additive changes need an explicit ALTER.
+MIGRATIONS = [("agent_sessions", "color", "TEXT"),
+              ("gate_results", "checks_json", "TEXT"),
+              ("sessions", "smidja_name", "TEXT"),
+              ("agent_sessions", "context_tokens", "INTEGER"),
+              ("agent_sessions", "context_window", "INTEGER"),
+              ("sessions", "archived", "INTEGER DEFAULT 0")]
+
+
+class Tracer:
+    def __init__(self, db_path: str | Path, events_jsonl: str | Path):
+        ensure_dir(Path(db_path).parent)
+        self.db_path = str(db_path)
+        self.events_jsonl = Path(events_jsonl)
+        ensure_dir(self.events_jsonl.parent)
+        self.conn = sqlite3.connect(self.db_path, isolation_level=None)
+        self.conn.execute("PRAGMA journal_mode=WAL;")
+        self.conn.execute("PRAGMA synchronous=NORMAL;")
+        self.conn.execute("PRAGMA busy_timeout=5000;")
+        self.conn.executescript(SCHEMA)
+        self._migrate()
+
+    def _migrate(self) -> None:
+        """Additive column migrations, so a db from an older smidja still opens."""
+        for table, column, decl in MIGRATIONS:
+            columns = {row[1] for row in self.conn.execute(f"PRAGMA table_info({table})")}
+            if column not in columns:
+                self.conn.execute(f"ALTER TABLE {table} ADD COLUMN {column} {decl}")
+
+    # ── events ──────────────────────────────────────────────────────────────
+    def event(self, record: EventRecord) -> str:
+        event_id = f"evt_{new_id(12)}"
+        ts = now_iso()
+        line = {"event_id": event_id, "ts": ts, **record.model_dump()}
+        with self.events_jsonl.open("a") as f:
+            f.write(json.dumps(line) + "\n")
+        self.conn.execute(
+            "INSERT INTO events (event_id, smidja_id, phase_id, parent_id, type, name,"
+            " payload_json, tokens, started_at, ended_at) VALUES (?,?,?,?,?,?,?,?,?,?)",
+            (event_id, record.smidja_id, record.phase_id, record.parent_id, record.type,
+             record.name, json.dumps(record.payload), record.tokens,
+             record.started_at or ts, record.ended_at),
+        )
+        return event_id
+
+    # ── sessions ────────────────────────────────────────────────────────────
+    def session_start(self, smidja_id: str, engineer: str, smidja_name: str | None = None) -> None:
+        self.conn.execute(
+            "INSERT INTO sessions (smidja_id, status, engineer, started_at) VALUES (?,?,?,?) "
+            "ON CONFLICT(smidja_id) DO UPDATE SET status='running'",
+            (smidja_id, "running", engineer, now_iso()),
+        )
+        if not smidja_name:
+            return
+        # A joined session chains smidja — record each distinct one, in run order.
+        row = self.conn.execute("SELECT smidja_name FROM sessions WHERE smidja_id=?",
+                                (smidja_id,)).fetchone()
+        names = row[0].split(" + ") if row and row[0] else []
+        if smidja_name not in names:
+            names.append(smidja_name)
+            self.conn.execute("UPDATE sessions SET smidja_name=? WHERE smidja_id=?",
+                              (" + ".join(names), smidja_id))
+
+    def session_request(self, smidja_id: str, request: str) -> None:
+        self.conn.execute("UPDATE sessions SET request=? WHERE smidja_id=?",
+                          (request[:500], smidja_id))
+
+    def session_finish(self, smidja_id: str, ok: bool) -> None:
+        self.conn.execute(
+            "UPDATE sessions SET status=?, ended_at=? WHERE smidja_id=?",
+            ("success" if ok else "fail", now_iso(), smidja_id),
+        )
+        self.processes_end_all(smidja_id)   # nothing of this run is alive any more
+
+    def session_add_usage(self, smidja_id: str, tokens: int, cost: float) -> None:
+        self.conn.execute(
+            "UPDATE sessions SET total_tokens=total_tokens+?, total_cost=total_cost+? WHERE smidja_id=?",
+            (tokens, cost, smidja_id),
+        )
+
+    # ── processes (smidja_id → pid, so a hung run can be found and killed) ─────
+    def process_start(self, smidja_id: str, kind: str, name: str, pid: int,
+                      command: str) -> None:
+        """Record a live process for this run.
+
+        A coding agent that hangs produces no events at all, which is exactly
+        when you need its pid — and `ps` cannot tell you which smidja_id it
+        belongs to. Writing it here makes the trace the answer to "what is this
+        run running, and how do I stop it".
+        """
+        self.conn.execute(
+            "INSERT INTO processes (smidja_id, kind, name, pid, command, started_at)"
+            " VALUES (?,?,?,?,?,?)",
+            (smidja_id, kind, name, pid, command[:500], now_iso()),
+        )
+
+    def process_end(self, smidja_id: str, pid: int) -> None:
+        """Mark the newest live row for this pid as finished."""
+        self.conn.execute(
+            "UPDATE processes SET ended_at=? WHERE id = ("
+            "  SELECT id FROM processes WHERE smidja_id=? AND pid=? AND ended_at IS NULL"
+            "  ORDER BY id DESC LIMIT 1)",
+            (now_iso(), smidja_id, pid),
+        )
+
+    def processes_end_all(self, smidja_id: str) -> None:
+        """Close out every live row for a run — called when the session ends."""
+        self.conn.execute(
+            "UPDATE processes SET ended_at=? WHERE smidja_id=? AND ended_at IS NULL",
+            (now_iso(), smidja_id),
+        )
+
+    # ── phases ──────────────────────────────────────────────────────────────
+    def max_phase_seq(self, smidja_id: str) -> int:
+        """Highest seq already recorded for this session; 0 when it is new.
+
+        A joined run continues the sequence instead of restarting at 1 — which
+        would collide with the first run's phases on both `seq` (breaking
+        ordering) and `phase_id` (silently overwriting a row through the
+        phase_upsert conflict clause).
+        """
+        row = self.conn.execute("SELECT MAX(seq) FROM phases WHERE smidja_id = ?",
+                                (smidja_id,)).fetchone()
+        return row[0] if row and row[0] is not None else 0
+
+    def phase_upsert(self, phase: Phase) -> None:
+        p = phase.params
+        self.conn.execute(
+            "INSERT INTO phases (phase_id, smidja_id, seq, name, kind, owner, description,"
+            " status, attempt, retries, error, started_at, ended_at)"
+            " VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?)"
+            " ON CONFLICT(phase_id) DO UPDATE SET status=excluded.status,"
+            " attempt=excluded.attempt, error=excluded.error, ended_at=excluded.ended_at",
+            (phase.phase_id, phase.smidja_id, phase.seq, p.name, p.kind, p.owner,
+             p.description, phase.status, phase.attempt, p.retries, phase.error,
+             phase.started_at, phase.ended_at),
+        )
+
+    # ── envelopes / gates / agent sessions ──────────────────────────────────
+    def envelope_row(self, phase: Phase, agent: str, output_type: str,
+                     payload_json: str, valid: bool, attempt: int) -> None:
+        self.conn.execute(
+            "INSERT INTO envelopes (envelope_id, smidja_id, phase_id, agent, output_type,"
+            " payload_json, valid, attempt, created_at) VALUES (?,?,?,?,?,?,?,?,?)",
+            (f"env_{new_id(12)}", phase.smidja_id, phase.phase_id, agent, output_type,
+             payload_json, int(valid), attempt, now_iso()),
+        )
+
+    def gate_row(self, phase: Phase, gate: str, report: GateReport, attempt: int) -> None:
+        """The report carries both the verdict and the evidence behind it."""
+        self.conn.execute(
+            "INSERT INTO gate_results (smidja_id, phase_id, attempt, gate, passed,"
+            " violations_json, checks_json, created_at) VALUES (?,?,?,?,?,?,?,?)",
+            (phase.smidja_id, phase.phase_id, attempt, gate, int(report.passed),
+             json.dumps(report.violations),
+             json.dumps([c.model_dump() for c in report.checks]), now_iso()),
+        )
+
+    def agent_session_row(self, smidja_id: str, agent: AgentConfig, session_id: str,
+                          context_tokens: int = 0, context_window: int = 0) -> None:
+        """The agent's config row is the source of truth for its label and color.
+
+        Context is carried here rather than derived from events because the lane
+        wants one number per agent — the latest — and a session that runs the
+        same agent twice overwrites it, exactly like model and session_id.
+        """
+        ts = now_iso()
+        self.conn.execute(
+            "INSERT INTO agent_sessions (smidja_id, agent, coding_agent, model, color,"
+            " session_id, context_tokens, context_window, created_at, last_used_at)"
+            " VALUES (?,?,?,?,?,?,?,?,?,?)"
+            " ON CONFLICT(smidja_id, agent) DO UPDATE SET model=excluded.model,"
+            " color=excluded.color, session_id=excluded.session_id,"
+            " context_tokens=excluded.context_tokens,"
+            " context_window=excluded.context_window,"
+            " last_used_at=excluded.last_used_at",
+            (smidja_id, agent.name, agent.coding_agent, agent.model, agent.color,
+             session_id, context_tokens, context_window, ts, ts),
+        )

package/apps/smidja-factory/templates/smidja/smidja_modules/utils.py

@@ -0,0 +1,77 @@
+"""Small shared helpers. Anything bigger belongs in its own module."""
+
+from __future__ import annotations
+
+import os
+import secrets
+import subprocess
+from datetime import datetime, timezone
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+load_dotenv()
+
+
+def operator_env() -> dict[str, str]:
+    """The engineer's own environment, as their shell would hand it over.
+
+    Agents and quality blocks are meant to see exactly what the operator sees:
+    their PATH, their toolchains, their globally installed packages. Copying
+    os.environ gets almost all the way there — but smidja launch under `uv run`,
+    which prepends its ephemeral venv's bin to PATH and sets VIRTUAL_ENV. That
+    venv holds the smidja's OWN dependencies (pydantic, pyyaml), not the
+    operator's, so anything a subprocess resolves through it — `python3`,
+    `pip`, every globally pip-installed CLI — silently becomes the wrong one.
+
+    Stripping the venv restores parity: `python3` in an agent's bash is the
+    same `python3` the engineer gets in their terminal. The smidja's own imports
+    are unaffected; this env is only ever handed to child processes.
+    """
+    env = os.environ.copy()
+    venv = env.pop("VIRTUAL_ENV", "")
+    if not venv:
+        return env
+    venv_bin = str(Path(venv) / "bin")
+    parts = [p for p in env.get("PATH", "").split(os.pathsep) if p and p != venv_bin]
+    env["PATH"] = os.pathsep.join(parts)
+    return env
+
+
+def new_id(length: int = 8) -> str:
+    return secrets.token_hex(length // 2)
+
+
+def now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat(timespec="milliseconds")
+
+
+def ensure_dir(path: str | Path) -> Path:
+    p = Path(path)
+    p.mkdir(parents=True, exist_ok=True)
+    return p
+
+
+def resolve_prompt(arg: str) -> str:
+    """CLI prompt arg: a file path resolves to its contents, else inline text."""
+    try:
+        p = Path(arg)
+        if p.is_file():
+            return p.read_text()
+    except OSError:
+        pass
+    return arg
+
+
+def engineer_name() -> str:
+    name = os.environ.get("ENGINEER_NAME", "").strip()
+    if name:
+        return name
+    try:
+        out = subprocess.run(["git", "config", "user.name"],
+                             capture_output=True, text=True, timeout=5)
+        if out.returncode == 0 and out.stdout.strip():
+            return out.stdout.strip()
+    except OSError:
+        pass
+    return os.environ.get("USER", "engineer")

package/apps/smidja-factory/templates/smidja/smidja_orchestrate.py

@@ -0,0 +1,162 @@
+#!/usr/bin/env -S uv run
+# /// script
+# dependencies = ["pydantic", "python-dotenv", "pyyaml", "rich"]
+# ///
+"""smidja Orchestrate (variant A) — Kaia dispatches sub-agents, tracks them, reports.
+
+Usage:
+    uv run smidja/smidja_orchestrate.py "<prompt or path/to/prompt.md>" [--config smidja/smidja_smidja_config/smidja.config.yaml] [--smidja-id a1b2c3d4]
+
+Phases: engineer(request) -> orchestrator (Kaia, dispatches sub-agents) -> reviewer [-> revise ...]
+
+The orchestrator agent gets the WHOLE task. It spawns sub-agents (scout,
+planner, builder, reviewer) via its subagent_* tools, tracks their progress,
+and returns an OrchestratorOutput envelope with every changed file. The gate
+`orchestrator_dispatched` verifies it actually used the subagent tools — the
+anti-hallucination guard for the coordinator role.
+
+Like build_review, a rejection does not fail the phase; it fails the run after
+the bounded revise loop.
+"""
+
+import argparse
+import sys
+from pathlib import Path
+
+from smidja_modules import agents, gates, session, utils
+from smidja_modules.data_types import (AgentCall, OrchestratorOutput,
+                                    PhaseParams, ReviewOutput)
+
+REQUIRED_AGENTS = ["orchestrator", "reviewer"]
+MAX_REVISION_LOOPS = 3
+KAIA_MEMORY_URL = "http://127.0.0.1:4602"
+
+
+def kaia_memory_for(project: str, k: int = 5) -> str:
+    """Recall Kaia's remembered lessons for a project from the engram bridge."""
+    import json
+    import urllib.parse
+    import urllib.request
+
+    try:
+        url = f"{KAIA_MEMORY_URL}/recall?q={urllib.parse.quote(project)}&k={k}"
+        with urllib.request.urlopen(url, timeout=3) as r:
+            data = json.load(r)
+        hits = [hit["episode"]["content"] for hit in data.get("results", [])]
+        return "\n".join(f"- {h[:300]}" for h in hits) if hits else ""
+    except Exception:
+        return ""
+
+
+def kaia_observe(content: str, tags: str = "run,lesson", actors: str = "",
+                 salience: float = 0.7) -> str:
+    """WRITE this run's lesson into Kaia's memory.
+
+    The orchestrator reads before dispatch (kaia_memory_for); this is the write
+    that closes the loop. Without it the well stays empty, recollection returns
+    nothing, and every run learns the same lesson again from scratch.
+    """
+    import json
+    import urllib.request
+
+    try:
+        # LISTS, never comma-strings: the store keeps a string as an array of
+        # CHARACTERS, and a later recall then reads "r,u,n" as tags.
+        def _list(v):
+            if isinstance(v, (list, tuple)):
+                return [str(x) for x in v if str(x)]
+            return [x.strip() for x in str(v or "").split(",") if x.strip()]
+        body = json.dumps({"content": content, "tags": _list(tags),
+                           "actors": _list(actors), "salience": salience}).encode()
+        req = urllib.request.Request(f"{KAIA_MEMORY_URL}/observe", data=body,
+                                     headers={"Content-Type": "application/json"},
+                                     method="POST")
+        with urllib.request.urlopen(req, timeout=5) as r:
+            return str(json.load(r).get("id", ""))
+    except Exception as e:  # a lost lesson must be loud, never silent
+        print(f"[kaia] MEMORY WRITE FAILED (this lesson is lost): {e}", file=sys.stderr)
+        return ""
+
+
+def lesson_from(project: str, accepted: bool, review, previous, loops: int,
+                files: list | None = None) -> str:
+    """The lesson, in the shape a later recall can use."""
+    verdict = "ACCEPTED" if accepted else "REJECTED"
+    names = [str(f) for f in (files or [])][:12]
+    try:
+        findings = [(getattr(f, "note", "") or getattr(f, "requirement", "") or str(f))
+                    for f in (getattr(review, "findings", None) or [])][:5]
+    except Exception:
+        findings = []
+    return (f"run on {project}: {verdict} after {loops} review loop(s). "
+            f"changed: {', '.join(names) if names else 'nothing recorded'}. "
+            f"findings: {'; '.join(str(x) for x in findings) if findings else 'none'}")
+
+
+def main(prompt: str, config: str = "smidja/smidja_smidja_config/smidja.config.yaml", smidja_id: str | None = None) -> int:
+    cfg = agents.load_config(config)
+    agents.validate(cfg, REQUIRED_AGENTS)
+    run = session.ensure(cfg, smidja_id)
+
+    with run.phase(PhaseParams(name="request", kind="engineer", owner=run.engineer,
+                               description="Capture the incoming ask")) as ph:
+        ph.log(input=prompt)
+
+    project = Path(run.repo_root).name
+    kaia_mem = kaia_memory_for(project)
+    dispatch = (
+        f"OBJECTIVE (the original ask, unchanged):\n{prompt}\n\n"
+        f"PROJECT: {project}\n"
+        f"WHAT YOU REMEMBER ABOUT THIS PROJECT:\n"
+        f"{kaia_mem if kaia_mem else '(no prior memory yet — first run)'}\n\n"
+        "Dispatch sub-agents to do the work, guided by your memory of what has "
+        "worked or failed on this project before. Track them, then report every "
+        "changed file.")
+
+    with run.phase(PhaseParams(name="orchestrate", kind="agent", owner="orchestrator",
+                               description="Kaia dispatches sub-agents, tracks them, and reports every changed file")) as ph:
+        previous = ph.call(AgentCall(output_type=OrchestratorOutput, prompt=dispatch,
+                                     gates=[gates.orchestrator_dispatched,
+                                            gates.diff_matches_claims]))
+
+    review = None
+    for i in range(1, MAX_REVISION_LOOPS + 1):
+        with run.phase(PhaseParams(name=f"review_{i}", kind="agent", owner="reviewer",
+                                   description="Rule on every requirement in the spec, against the code on disk")) as ph:
+            review = ph.call(AgentCall(output_type=ReviewOutput, prompt=prompt,
+                                       previous=previous,
+                                       gates=[gates.artifacts_exist,
+                                              gates.verdict_consistent]))
+
+        if review.approved:
+            break
+        if i == MAX_REVISION_LOOPS:
+            break
+
+        with run.phase(PhaseParams(name=f"revise_{i}", kind="agent", owner="orchestrator", retries=1,
+                                   description="Kaia closes every blocking finding the reviewer named")) as ph:
+            previous = ph.call(AgentCall(output_type=OrchestratorOutput, prompt=prompt, previous=review,
+                                         gates=[gates.orchestrator_dispatched,
+                                                gates.diff_matches_claims]))
+
+    accepted = review is not None and review.approved
+    # CLOSE THE LOOP: the orchestrator read before dispatch, so it must write after.
+    changed = []
+    try:
+        changed = [getattr(f, "path", None) or str(f)
+                   for f in (getattr(previous, "changed_files", None) or [])]
+    except Exception:
+        changed = []
+    kaia_observe(lesson_from(project, accepted, review, previous, i, changed),
+                 tags="run,lesson", actors=project, salience=0.7)
+    return run.finish(accepted=accepted,
+                      reason=f"the reviewer never approved after {MAX_REVISION_LOOPS} revision(s)")
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("prompt", help="inline text or a path to a prompt file")
+    parser.add_argument("--config", default="smidja/smidja_smidja_config/smidja.config.yaml")
+    parser.add_argument("--smidja-id", default=None, help="join or pin an existing session")
+    args = parser.parse_args()
+    sys.exit(main(utils.resolve_prompt(args.prompt), args.config, args.smidja_id))

package/apps/smidja-factory/templates/smidja/smidja_plan.py

@@ -0,0 +1,45 @@
+#!/usr/bin/env -S uv run
+# /// script
+# dependencies = ["pydantic", "python-dotenv", "pyyaml", "rich"]
+# ///
+"""smidja Plan — one-shot planning workflow.
+
+Usage:
+    uv run smidja/smidja_plan.py "<prompt or path/to/prompt.md>" [--config smidja/smidja_smidja_config/smidja.config.yaml] [--smidja-id a1b2c3d4]
+
+Phases: engineer(request) -> planner
+"""
+
+import argparse
+import sys
+
+from smidja_modules import agents, gates, session, utils
+from smidja_modules.data_types import AgentCall, PhaseParams, PlanOutput
+
+REQUIRED_AGENTS = ["planner"]
+
+
+def main(prompt: str, config: str = "smidja/smidja_smidja_config/smidja.config.yaml", smidja_id: str | None = None) -> int:
+    cfg = agents.load_config(config)
+    agents.validate(cfg, REQUIRED_AGENTS)
+    run = session.ensure(cfg, smidja_id)
+
+    with run.phase(PhaseParams(name="request", kind="engineer", owner=run.engineer,
+                               description="Capture the incoming ask")) as ph:
+        ph.log(input=prompt)
+
+    with run.phase(PhaseParams(name="plan", kind="agent", owner="planner",
+                               description="Turn the request into an implementable plan")) as ph:
+        ph.call(AgentCall(output_type=PlanOutput, prompt=prompt,
+                          gates=[gates.artifacts_exist, gates.files_non_empty]))
+
+    return run.finish()
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("prompt", help="inline text or a path to a prompt file")
+    parser.add_argument("--config", default="smidja/smidja_smidja_config/smidja.config.yaml")
+    parser.add_argument("--smidja-id", default=None, help="join or pin an existing session")
+    args = parser.parse_args()
+    sys.exit(main(utils.resolve_prompt(args.prompt), args.config, args.smidja_id))

package/apps/smidja-factory/templates/smidja/smidja_plan_build.py

@@ -0,0 +1,55 @@
+#!/usr/bin/env -S uv run
+# /// script
+# dependencies = ["pydantic", "python-dotenv", "pyyaml", "rich"]
+# ///
+"""smidja Plan Build — two-agent chain: planner -> envelope -> builder.
+
+Usage:
+    uv run smidja/smidja_plan_build.py "<prompt or path/to/prompt.md>" [--config smidja/smidja_smidja_config/smidja.config.yaml] [--smidja-id a1b2c3d4]
+
+Phases: engineer(request) -> planner -> builder -> git(commit)
+"""
+
+import argparse
+import sys
+
+from smidja_modules import agents, gates, git_helper, session, utils
+from smidja_modules.data_types import AgentCall, BuildOutput, PhaseParams, PlanOutput
+
+REQUIRED_AGENTS = ["planner", "builder"]
+
+
+def main(prompt: str, config: str = "smidja/smidja_smidja_config/smidja.config.yaml", smidja_id: str | None = None) -> int:
+    cfg = agents.load_config(config)
+    agents.validate(cfg, REQUIRED_AGENTS)
+    run = session.ensure(cfg, smidja_id)
+
+    with run.phase(PhaseParams(name="request", kind="engineer", owner=run.engineer,
+                               description="Capture the incoming ask")) as ph:
+        ph.log(input=prompt)
+
+    with run.phase(PhaseParams(name="plan", kind="agent", owner="planner",
+                               description="Turn the request into an implementable plan")) as ph:
+        plan = ph.call(AgentCall(output_type=PlanOutput, prompt=prompt,
+                                 gates=[gates.artifacts_exist, gates.files_non_empty]))
+
+    with run.phase(PhaseParams(name="build", kind="agent", owner="builder",
+                               description="Implement the plan exactly")) as ph:
+        build = ph.call(AgentCall(output_type=BuildOutput, prompt=prompt, previous=plan,
+                                  gates=[gates.diff_matches_claims]))
+
+    with run.phase(PhaseParams(name="commit", kind="code", owner="git",
+                               description="Land the builder's changes, using the message it wrote")) as ph:
+        message = build.commit_message or f"smidja({run.smidja_id}): {build.summary}"
+        ph.log(sha=git_helper.commit_all(message), message=message)
+
+    return run.finish()
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("prompt", help="inline text or a path to a prompt file")
+    parser.add_argument("--config", default="smidja/smidja_smidja_config/smidja.config.yaml")
+    parser.add_argument("--smidja-id", default=None, help="join or pin an existing session")
+    args = parser.parse_args()
+    sys.exit(main(utils.resolve_prompt(args.prompt), args.config, args.smidja_id))