@zerwiz/ymir 0.1.33 → 0.1.35

package/apps/smidja-factory/templates/prompt_engineering/scout/system.md

@@ -0,0 +1,32 @@
+# Scout Agent
+
+## Purpose
+
+Find and report where things live. Change nothing.
+
+## Instructions
+
+- Read-only: search, read, and report — never write to the codebase.
+- Cite exact file paths (with line hints where useful).
+- **Paths are exact — copy them from the request or from `ls`, never retype
+  them.** Directory names can differ by a single character that is easy to
+  mangle (hyphens vs underscores: `tests/local-models/` with a hyphen, not
+  `tests/local_models/`). Before you chase a path, verify it exists with
+  `ls`/`test -e`; if your first guess errors with ENOENT, list the parent
+  directory and use the name you actually see.
+- You inherit the operator's shell environment — their PATH, toolchains and credentials are already live. Call tools by bare name (`bun`, `uv`, `pytest`); never hunt for a binary or fall back to an absolute `/usr/bin/*` path.
+- Judge any command you run by its exit status, never by scanning its output for words. `error` or `not found` inside passing output is text, not a failure.
+- Write your findings to `<context_handoff_dir>/scout_findings.md` for agents that follow.
+- **Checkpoint every ~25 tool calls (interval delivery):** write your current
+  findings to `<context_handoff_dir>/scout_findings_N.md` (increment N per
+  interval), write through to `scout_findings.md`, and keep a running one-page
+  `running_summary.md` (top findings + what is still unknown) that always shows
+  the current state. This is how a long recon survives context resets — the
+  next scout session starts from these files, so keep them honest and current.
+- If you find nothing, say so plainly — an empty finding is a valid finding.
+
+## Subagents
+
+`subagent_create` / `_continue` / `_list` / `_remove` search several directions at once — one per lead or directory — instead of walking the codebase serially. Give each a self-contained task and hold it to read-only work; omit `model`.
+
+They run in the background. **Wait for every one you spawned to report before writing `scout_findings.md` or your Report JSON.** Skip them when a couple of greps would do.

package/apps/smidja-factory/templates/prompt_engineering/scout/user.md

@@ -0,0 +1,34 @@
+# Scout Task
+
+## Variables
+
+### prompt
+
+{{prompt}}
+
+### previous_envelope
+
+{{previous_envelope}}
+
+### context_handoff_dir
+
+{{context_handoff_dir}}
+
+## Task
+
+Find what `prompt` asks about. Write findings into `context_handoff_dir`, then emit your `Report` JSON.
+
+## Report
+
+Respond with ONLY valid JSON matching `ScoutOutput` — no prose before or after:
+
+```json
+{
+  "status": "success",
+  "summary": "<one sentence on what you found>",
+  "findings": [
+    { "file": "src/server.ts", "note": "<why this file matters>" }
+  ],
+  "artifacts": ["<context_handoff_dir>/scout_findings.md"]
+}
+```

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

@@ -0,0 +1,45 @@
+#!/usr/bin/env -S uv run
+# /// script
+# dependencies = ["pydantic", "python-dotenv", "pyyaml", "rich"]
+# ///
+"""smidja Build — one-shot implementation workflow.
+
+Usage:
+    uv run smidja/smidja_build.py "<prompt or path/to/prompt.md>" [--config smidja/smidja_smidja_config/smidja.config.yaml] [--smidja-id a1b2c3d4]
+
+Phases: engineer(request) -> builder
+"""
+
+import argparse
+import sys
+
+from smidja_modules import agents, gates, session, utils
+from smidja_modules.data_types import AgentCall, BuildOutput, PhaseParams
+
+REQUIRED_AGENTS = ["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="build", kind="agent", owner="builder", retries=1,
+                               description="Implement the request")) as ph:
+        ph.call(AgentCall(output_type=BuildOutput, prompt=prompt,
+                          gates=[gates.diff_matches_claims]))
+
+    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_build_review.py

@@ -0,0 +1,76 @@
+#!/usr/bin/env -S uv run
+# /// script
+# dependencies = ["pydantic", "python-dotenv", "pyyaml", "rich"]
+# ///
+"""smidja Build Review — implement, then confirm it is what was asked for.
+
+Usage:
+    uv run smidja/smidja_build_review.py "<prompt or path/to/prompt.md>" [--config smidja/smidja_smidja_config/smidja.config.yaml] [--smidja-id a1b2c3d4]
+
+Phases: engineer(request) -> builder -> reviewer [-> builder(revise) -> reviewer ... bounded]
+
+Review is not testing. Tests answer "does it run"; the reviewer answers "is this
+the thing that was asked for" — it reads the spec (`plan.md` from a prior plan
+phase if the session has one, else the prompt verbatim), reads the code that was
+written, and rules on each requirement.
+
+Like the tester, the reviewer's phase succeeds when it RUNS and REPORTS. A
+rejection does not fail the phase; it fails the run, checked at the end, after
+the bounded revise loop has had its chances.
+"""
+
+import argparse
+import sys
+
+from smidja_modules import agents, gates, session, utils
+from smidja_modules.data_types import (AgentCall, BuildOutput, PhaseParams,
+                                    ReviewOutput)
+
+REQUIRED_AGENTS = ["builder", "reviewer"]
+MAX_REVISION_LOOPS = 3
+
+
+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="build", kind="agent", owner="builder",
+                               description="Implement the request")) as ph:
+        previous = ph.call(AgentCall(output_type=BuildOutput, prompt=prompt,
+                                     gates=[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="builder", retries=1,
+                                   description="Close every blocking finding the reviewer named")) as ph:
+            previous = ph.call(AgentCall(output_type=BuildOutput, prompt=prompt, previous=review,
+                                         gates=[gates.diff_matches_claims]))
+
+    return run.finish(accepted=review is not None and review.approved,
+                      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_build_test.py

@@ -0,0 +1,79 @@
+#!/usr/bin/env -S uv run
+# /// script
+# dependencies = ["pydantic", "python-dotenv", "pyyaml", "rich"]
+# ///
+"""smidja Build Test — implement, then verify; failures flow back into the builder.
+
+Usage:
+    uv run smidja/smidja_build_test.py "<prompt or path/to/prompt.md>" [--config smidja/smidja_smidja_config/smidja.config.yaml] [--smidja-id a1b2c3d4]
+
+Phases: engineer(request) -> builder -> code(test) [-> builder(fix) -> code(test) ... bounded]
+
+Testing is CODE. The suite's command is written down in smidja_modules/quality.py,
+so running it needs no judgement — only repairing it does. Failures reach the
+builder as an envelope through `quality.as_envelope`, which is the same door an
+agent's report came through, so the repair loop is unchanged.
+
+A failing suite does NOT fail its phase: the runner did its job, the code is
+what failed. It fails the run, checked at the end, after the bounded fix loop
+has had its chances.
+"""
+
+import argparse
+import sys
+
+from smidja_modules import agents, gates, quality, session, utils
+from smidja_modules.data_types import AgentCall, BuildOutput, PhaseParams
+
+REQUIRED_AGENTS = ["builder"]
+MAX_FIX_LOOPS = 3
+
+
+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)
+
+    def record(ph, result) -> None:
+        passed = sum(1 for check in result.checks if check.passed)
+        ph.log(passed=result.passed, checks=f"{passed}/{len(result.checks)}",
+               artifacts=", ".join(result.artifacts))
+
+    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="build", kind="agent", owner="builder",
+                               description="Implement the request")) as ph:
+        previous = ph.call(AgentCall(output_type=BuildOutput, prompt=prompt,
+                                     gates=[gates.diff_matches_claims]))
+
+    test = None
+    for i in range(1, MAX_FIX_LOOPS + 1):
+        with run.phase(PhaseParams(name=f"test_{i}", kind="code", owner="quality",
+                                   description="Run the suite — a known command, so code runs "
+                                               "it and no agent has to rediscover it")) as ph:
+            test = quality.run_tests(run)
+            record(ph, test)
+
+        if test.passed:
+            break
+
+        with run.phase(PhaseParams(name=f"fix_{i}", kind="agent", owner="builder", retries=1,
+                                   description="Repair what the suite reported, from its "
+                                               "verbatim output")) as ph:
+            previous = ph.call(AgentCall(output_type=BuildOutput, prompt=prompt,
+                                         previous=quality.as_envelope(test, "tests"),
+                                         gates=[gates.diff_matches_claims]))
+
+    return run.finish(accepted=test is not None and test.passed,
+                      reason=f"the suite still failed after {MAX_FIX_LOOPS} fix attempt(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_document.py

@@ -0,0 +1,76 @@
+#!/usr/bin/env -S uv run
+# /// script
+# dependencies = ["pydantic", "python-dotenv", "pyyaml", "rich"]
+# ///
+"""smidja Document — write up the work that was just done, from the diff.
+
+Usage:
+    uv run smidja/smidja_document.py "<prompt or path/to/prompt.md>" [--base main] [--config smidja/smidja_smidja_config/smidja.config.yaml] [--smidja-id a1b2c3d4]
+
+Phases: engineer(request) -> code(changes) -> documenter
+
+This runs AFTER a build, and the guard is structural rather than advisory: the
+change capture is a code phase, and an empty diff raises there — before the
+documenter is ever spawned. There is nothing to document until something was
+built, and the phase says so instead of paying an agent to discover it.
+
+`git diff` against `--base` (main by default) is what "the latest changes"
+means here; see smidja_modules/changes.py for how the base commit is resolved on a
+branch, on main, and on a clean tree right after a chain committed.
+"""
+
+import argparse
+import sys
+
+from smidja_modules import agents, changes, gates, session, utils
+from smidja_modules.data_types import (AgentCall, ChangeCapture, DocumentOutput,
+                                    PhaseParams)
+
+REQUIRED_AGENTS = ["documenter"]
+
+DOCUMENT_NOTES = ("Read diff_path in full before writing. Document only what the "
+                  "diff shows, then copy the write-up into app_docs/ as your task "
+                  "describes.")
+
+
+def main(prompt: str, base: str = "main",
+         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="changes", kind="code", owner="git",
+                               description=f"Diff the working tree against {base} — the change to be written up")) as ph:
+        changeset = changes.capture(run, ChangeCapture(base=base))
+        ph.log(base=f"{changeset.base.label} @ {changeset.base.commit[:7]}",
+               reason=changeset.base.reason,
+               files=len(changeset.files) + len(changeset.untracked),
+               lines=f"+{changeset.insertions} -{changeset.deletions}",
+               diff=changeset.diff_path)
+        if changeset.empty:
+            raise RuntimeError(
+                f"nothing changed since {changeset.base.label} ({changeset.base.reason}) "
+                f"— documenting runs after a build. Build something first, or point "
+                f"--base at the ref the work should be measured from.")
+
+    with run.phase(PhaseParams(name="document", kind="agent", owner="documenter", retries=1,
+                               description="Turn the captured diff into a write-up an engineer can read")) as ph:
+        ph.call(AgentCall(output_type=DocumentOutput, prompt=prompt,
+                          previous=changes.as_envelope(changeset, DOCUMENT_NOTES),
+                          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("--base", default="main", help="ref the change is measured against")
+    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.base, args.config, args.smidja_id))

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

@@ -0,0 +1,15 @@
+"""Claude Code interface — STUB in v1. The smidja is Pi-only for now.
+
+The config schema accepts `coding_agent: claude_code` so nothing breaks at the
+schema level, but selecting it raises until v2 implements this interface
+(`claude -p --output-format stream-json --resume <session_id>`).
+"""
+
+from __future__ import annotations
+
+
+def run(*args, **kwargs):
+    raise NotImplementedError(
+        "coding_agent 'claude_code' is not implemented in v1 — smidja v1 runs the "
+        "Pi coding agent only. Set coding_agent: pi (or omit it) in smidja.config.yaml."
+    )

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

@@ -0,0 +1,194 @@
+"""OpenCode coding-agent interface — the smidja can run through opencode CLI.
+
+Mirrors agent_pi.run(): spawns `opencode run --format json` (NDJSON event
+stream) and consumes it line by line. Tool records are normalized to the shape
+agents.py's ToolCallTracker expects, so the visualizer paints real tool calls.
+
+Session continuation is the same mechanism as pi, with one twist: opencode
+rejects unknown session ids, so a fresh run created with a smidja id
+(`smidja-...`) is launched WITHOUT `--session`; the real `ses_...` id from the
+event stream is returned, and the caller stores it for the next call.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import time
+from pathlib import Path
+from typing import Callable, Optional
+
+from .data_types import PiRequest, PiResult
+from .utils import now_iso, operator_env
+
+OPENCODE_PATH = os.environ.get("OPENCODE_PATH", "opencode")
+
+RESULT_SNIPPET_CHARS = 20_000
+ARG_VALUE_CHARS = 20_000
+LABEL_CHARS = 80
+
+PRIMARY_ARGS = ("command", "path", "file_path", "pattern", "query", "url")
+
+
+def _clip(text: str, limit: int) -> str:
+    return text if len(text) <= limit else text[:limit].rstrip() + "…"
+
+
+def _label(tool: str, args: dict) -> str:
+    value = next((args[key] for key in PRIMARY_ARGS
+                  if isinstance(args.get(key), str) and args[key].strip()), "")
+    if not value:
+        value = next((v for v in args.values() if isinstance(v, str) and v.strip()), "")
+    value = " ".join(str(value).split())
+    return f"{tool}: {_clip(value, LABEL_CHARS)}" if value else tool
+
+
+def run(request: PiRequest, on_event: Optional[Callable[[dict], None]] = None,
+        on_spawn: Optional[Callable[[int], None]] = None,
+        on_exit: Optional[Callable[[int], None]] = None) -> PiResult:
+    """Run one non-interactive opencode turn against the NDJSON event stream.
+
+    The system prompt rides inside the message (opencode CLI has no
+    --system-prompt); the agent treats it as standing instructions.
+    """
+    message = f"{request.system_prompt}\n\n{request.prompt}"
+    cmd = [OPENCODE_PATH, "run", "--format", "json",
+           "--model", request.model, "--auto"]
+    if request.session_id.startswith("ses_"):
+        cmd += ["--session", request.session_id]   # continue the real opencode session
+    cmd.append(message)
+
+    raw_path = Path(request.raw_output_path)
+    raw_path.parent.mkdir(parents=True, exist_ok=True)
+
+    process = subprocess.Popen(cmd, stdin=subprocess.DEVNULL,
+                               stdout=subprocess.PIPE, stderr=subprocess.PIPE,
+                               text=True, bufsize=1, cwd=request.cwd,
+                               env=operator_env())
+    if on_spawn:
+        on_spawn(process.pid)
+
+    result = PiResult(session_id=request.session_id)
+    text = ""
+    tokens = 0
+    cost = 0.0
+    context_tokens = 0
+    with raw_path.open("a") as raw:
+        assert process.stdout is not None
+        for line in process.stdout:
+            raw.write(line)
+            raw.flush()
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                event = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            if event.get("sessionID"):
+                result.session_id = event["sessionID"]
+            part = event.get("part") or {}
+            ptype = part.get("type", "")
+            if ptype == "text":
+                chunk = part.get("text", "")
+                if chunk:
+                    text += chunk
+            elif ptype == "reasoning":
+                # Nemotron & friends stream their chain-of-thought as reasoning
+                # parts. It never goes into result.text (that is fed to the JSON
+                # parser), but it is forwarded as a thinking event and left in
+                # raw_output.jsonl verbatim so the visualizer can show it.
+                chunk = part.get("text", "") or ""
+                if chunk and on_event:
+                    on_event({"type": "thinking", "text": chunk,
+                              "surface": "opencode"})
+            elif ptype == "message":
+                # Some opencode versions carry reasoning inside message parts as
+                # content items ({type: "reasoning", text}) rather than a bare
+                # reasoning part — normalize both to a thinking event.
+                for c in part.get("content") or []:
+                    if (isinstance(c, dict) and c.get("type") == "reasoning"
+                            and c.get("text") and on_event):
+                        on_event({"type": "thinking", "text": str(c["text"]),
+                                  "surface": "opencode"})
+            elif ptype == "tool":
+                state = part.get("state") or {}
+                status = state.get("status", "completed")
+                args = state.get("input") or {}
+                meta = state.get("metadata") or {}
+                exit_code = meta.get("exit")
+                is_error = status != "completed" or (
+                    exit_code is not None and str(exit_code) != "0")
+                output = state.get("output") or state.get("error") or ""
+                tool = part.get("tool") or "tool"
+                if tool == "task" and on_event:
+                    # opencode's NATIVE subagent dispatch (the `task` tool).
+                    # Folded into a dedicated subagent_dispatch event so the
+                    # trace UI shows real dispatch and gates can verify it —
+                    # it is NOT a plain tool call. The raw `tool_use` line is
+                    # still written verbatim to raw_output.jsonl (the gate's
+                    # authoritative evidence). The child's final report rides
+                    # in state.output — passed through so the subagent lane
+                    # shows what the child ACTUALLY produced (P1), not a shell.
+                    on_event({
+                        "type": "subagent_dispatch",
+                        "subagent_type": args.get("subagent_type")
+                                         or args.get("agent") or "general",
+                        "description": args.get("description") or "",
+                        "prompt": args.get("prompt") or "",
+                        "status": status,
+                        "output": output,
+                        "is_error": bool(is_error),
+                    })
+                elif on_event:
+                    on_event({
+                        "type": "tool_execution_end",
+                        "toolName": tool,
+                        "toolCallId": part.get("callID")
+                                     or str(part.get("id") or ""),
+                        "args": args,
+                        "isError": bool(is_error),
+                        "result": {"content": [{"type": "text", "text": output}]},
+                    })
+            elif ptype == "step-finish":
+                usage_tokens = part.get("tokens") or {}
+                total = usage_tokens.get("total") or 0
+                if total:
+                    tokens += int(total)
+                    context_tokens = int(total)
+                    cache = usage_tokens.get("cache") or {}
+                    result.usage.add_turn({
+                        "input": usage_tokens.get("input") or 0,
+                        "output": usage_tokens.get("output") or 0,
+                        "reasoning": usage_tokens.get("reasoning") or 0,
+                        "cacheRead": cache.get("read") or 0,
+                        "cacheWrite": cache.get("write") or 0,
+                        "cost": {"total": part.get("cost") or 0.0},
+                    }, int(total))
+                    # P2 additive: forward a LIVE usage event so the runner can
+                    # trace + add_usage mid-run (the session row's
+                    # total_tokens/total_cost grow while running, instead of
+                    # staying 0 until the phase ends). The internal
+                    # accumulation above is untouched.
+                    if on_event:
+                        on_event({
+                            "type": "usage",
+                            "tokens": int(total),
+                            "cost": float(part.get("cost") or 0.0),
+                            "surface": "opencode",
+                        })
+                cost += float(part.get("cost") or 0.0)
+
+    stderr = process.stderr.read() if process.stderr else ""
+    result.returncode = process.wait()
+    if on_exit:
+        on_exit(process.pid)
+    result.text = text.strip()
+    result.tokens = tokens
+    result.cost = cost
+    result.context_tokens = context_tokens
+    if result.returncode != 0 and not result.text:
+        raise RuntimeError(
+            f"opencode exited {result.returncode}: {stderr.strip()[-800:]}")
+    return result