@try-works/dsh-recursive-mode 0.1.3 → 0.1.4

package/references/scripts/recursive-router-configure.ps1

@@ -0,0 +1,27 @@
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory = $true)][string[]]$Set,
+    [string]$RepoRoot = (Get-Location).Path,
+    [switch]$Json,
+    [int]$TimeoutMs = 0
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+
+$python = if ($env:PYTHON) { $env:PYTHON } elseif (Get-Command python -ErrorAction SilentlyContinue) { "python" } else { $null }
+if (-not $python) {
+    Write-Host "[FAIL] Python executable not found in PATH."
+    exit 1
+}
+
+$scriptPath = Join-Path $PSScriptRoot "recursive-router-configure.py"
+$argsList = @($scriptPath, "--repo-root", $RepoRoot)
+foreach ($assignment in $Set) {
+    $argsList += @("--set", $assignment)
+}
+if ($Json) { $argsList += "--json" }
+if ($TimeoutMs -gt 0) { $argsList += @("--timeout-ms", $TimeoutMs) }
+
+& $python @argsList
+exit $LASTEXITCODE

package/references/scripts/recursive-router-configure.py

@@ -0,0 +1,74 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from recursive_router_lib import RouterConfigError, canonicalize_router_role, configure_verified_routes, pretty_json
+
+
+def parse_assignment(raw: str) -> tuple[str, str, str]:
+    if "=" not in raw:
+        raise RouterConfigError(f"Invalid --set value {raw!r}. Expected role=cli:model.")
+    role, target = raw.split("=", 1)
+    role = canonicalize_router_role(role.strip())
+    if ":" not in target:
+        raise RouterConfigError(f"Invalid --set value {raw!r}. Expected role=cli:model.")
+    cli_id, model = target.split(":", 1)
+    cli_id = cli_id.strip()
+    model = model.strip()
+    if not cli_id:
+        raise RouterConfigError(f"Invalid --set value {raw!r}. CLI id must be non-empty.")
+    if not model:
+        raise RouterConfigError(f"Invalid --set value {raw!r}. Model must be non-empty.")
+    return role, cli_id, model
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Verify recursive-router bindings before saving them.")
+    parser.add_argument("--repo-root", default=".", help="Repository root path.")
+    parser.add_argument(
+        "--set",
+        dest="assignments",
+        action="append",
+        required=True,
+        help="Role binding in role=cli:model form. Repeatable. Prefer stage-aligned roles; legacy aliases are accepted.",
+    )
+    parser.add_argument("--json", action="store_true", help="Emit machine-readable JSON.")
+    parser.add_argument(
+        "--timeout-ms",
+        type=int,
+        default=50000,
+        help="Verification timeout in milliseconds. Defaults to 50000.",
+    )
+    args = parser.parse_args()
+
+    repo_root = Path(args.repo_root).resolve()
+    try:
+        assignments: dict[str, dict[str, str]] = {}
+        for raw_assignment in args.assignments:
+            role, cli_id, model = parse_assignment(raw_assignment)
+            if role in assignments:
+                raise RouterConfigError(f"Duplicate role assignment provided for {role}.")
+            assignments[role] = {"cli": cli_id, "model": model}
+
+        payload = configure_verified_routes(repo_root, assignments=assignments, timeout_ms=args.timeout_ms)
+    except RouterConfigError as exc:
+        print(f"[FAIL] {exc}")
+        return 1
+
+    if args.json:
+        print(pretty_json(payload), end="")
+    else:
+        print(f"Saved={'yes' if payload['saved'] else 'no'} Policy={payload['policy_path']}")
+        for role, result in payload["verification_results"].items():
+            print(
+                f"{role}: verified={'yes' if result['verified'] else 'no'} "
+                f"cli={result['cli']} model={result['model']} transport={result['transport']}"
+            )
+            print(f"  reason: {result['reason']}")
+    return 0 if payload["saved"] else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/references/scripts/recursive-router-init.ps1

@@ -0,0 +1,17 @@
+[CmdletBinding()]
+param(
+    [string]$RepoRoot = (Get-Location).Path
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+
+$python = if ($env:PYTHON) { $env:PYTHON } elseif (Get-Command python -ErrorAction SilentlyContinue) { "python" } else { $null }
+if (-not $python) {
+    Write-Host "[FAIL] Python executable not found in PATH."
+    exit 1
+}
+
+$scriptPath = Join-Path $PSScriptRoot "recursive-router-init.py"
+& $python $scriptPath "--repo-root" $RepoRoot
+exit $LASTEXITCODE

package/references/scripts/recursive-router-init.py

@@ -0,0 +1,29 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+
+from pathlib import Path
+
+from recursive_router_lib import RouterConfigError, ensure_router_scaffold, normalize_repo_path
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Initialize recursive-router config files.")
+    parser.add_argument("--repo-root", default=".", help="Repository root path.")
+    args = parser.parse_args()
+
+    repo_root = Path(args.repo_root).resolve()
+    try:
+        policy_path, discovery_path = ensure_router_scaffold(repo_root)
+    except RouterConfigError as exc:
+        print(f"[FAIL] {exc}")
+        return 1
+
+    print(f"[OK] Router policy path: {normalize_repo_path(str(policy_path.relative_to(repo_root)))}")
+    print(f"[OK] Discovery inventory path: {normalize_repo_path(str(discovery_path.relative_to(repo_root)))}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/references/scripts/recursive-router-invoke.ps1

@@ -0,0 +1,47 @@
+[CmdletBinding()]
+param(
+    [string]$RepoRoot = (Get-Location).Path,
+    [string]$Role,
+    [string]$PromptFile,
+    [string]$Prompt,
+    [string]$OutputFile,
+    [string]$MetadataFile,
+    [switch]$Json,
+    [switch]$NoWrite,
+    [int]$TimeoutMs = 0
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+
+$python = if ($env:PYTHON) { $env:PYTHON } elseif (Get-Command python -ErrorAction SilentlyContinue) { "python" } else { $null }
+if (-not $python) {
+    Write-Host "[FAIL] Python executable not found in PATH."
+    exit 1
+}
+
+if (-not $Role) {
+    Write-Host "[FAIL] -Role is required."
+    exit 1
+}
+if ([string]::IsNullOrWhiteSpace($PromptFile) -and [string]::IsNullOrWhiteSpace($Prompt)) {
+    Write-Host "[FAIL] Provide either -PromptFile or -Prompt."
+    exit 1
+}
+if (-not [string]::IsNullOrWhiteSpace($PromptFile) -and -not [string]::IsNullOrWhiteSpace($Prompt)) {
+    Write-Host "[FAIL] Provide only one of -PromptFile or -Prompt."
+    exit 1
+}
+
+$scriptPath = Join-Path $PSScriptRoot "recursive-router-invoke.py"
+$argsList = @($scriptPath, "--repo-root", $RepoRoot, "--role", $Role)
+if ($PromptFile) { $argsList += @("--prompt-file", $PromptFile) }
+if ($Prompt) { $argsList += @("--prompt", $Prompt) }
+if ($OutputFile) { $argsList += @("--output-file", $OutputFile) }
+if ($MetadataFile) { $argsList += @("--metadata-file", $MetadataFile) }
+if ($Json) { $argsList += "--json" }
+if ($NoWrite) { $argsList += "--no-write" }
+if ($TimeoutMs -gt 0) { $argsList += @("--timeout-ms", $TimeoutMs) }
+
+& $python @argsList
+exit $LASTEXITCODE

package/references/scripts/recursive-router-invoke.py

@@ -0,0 +1,103 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from recursive_router_lib import RouterConfigError, invoke_route_binding, normalize_repo_path, pretty_json, write_json
+
+
+def _normalize_prompt_path(repo_root: Path, prompt_path: Path) -> str:
+    try:
+        return normalize_repo_path(str(prompt_path.relative_to(repo_root)))
+    except ValueError:
+        return str(prompt_path)
+
+
+def _is_run_subagents_path(repo_root: Path, path: Path) -> bool:
+    try:
+        relative = path.resolve().relative_to(repo_root)
+    except ValueError:
+        return False
+    parts = relative.parts
+    return len(parts) >= 4 and parts[0] == ".recursive" and parts[1] == "run" and parts[3] == "subagents"
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Invoke a recursive-router role with a real prompt bundle or inline prompt.")
+    parser.add_argument("--repo-root", default=".", help="Repository root path.")
+    parser.add_argument("--role", required=True, help="Stage-aligned routed role to invoke. Legacy aliases are accepted.")
+    prompt_group = parser.add_mutually_exclusive_group(required=True)
+    prompt_group.add_argument("--prompt-file", help="Path to a prompt bundle file to dispatch.")
+    prompt_group.add_argument("--prompt", help="Inline prompt text to dispatch.")
+    parser.add_argument("--output-file", help="Optional file path to write the routed model output text.")
+    parser.add_argument("--metadata-file", help="Optional file path to write the full invocation payload JSON.")
+    parser.add_argument("--json", action="store_true", help="Emit machine-readable JSON.")
+    parser.add_argument("--no-write", action="store_true", help="Do not refresh the discovery inventory file.")
+    parser.add_argument("--timeout-ms", type=int, default=None, help="Override probe and invocation timeout in milliseconds.")
+    args = parser.parse_args()
+
+    repo_root = Path(args.repo_root).resolve()
+    try:
+        if args.output_file and _is_run_subagents_path(repo_root, Path(args.output_file)):
+            raise RouterConfigError(
+                "Raw routed output must be stored under the run evidence tree, "
+                "for example /.recursive/run/<run-id>/evidence/router/, not under subagents/."
+            )
+        if args.metadata_file and _is_run_subagents_path(repo_root, Path(args.metadata_file)):
+            raise RouterConfigError(
+                "Router invocation metadata must be stored under the run evidence tree, "
+                "for example /.recursive/run/<run-id>/evidence/router/, not under subagents/."
+            )
+        prompt_bundle_path = ""
+        if args.prompt_file:
+            prompt_path = Path(args.prompt_file).resolve()
+            prompt_text = prompt_path.read_text(encoding="utf-8")
+            prompt_bundle_path = _normalize_prompt_path(repo_root, prompt_path)
+            prompt_source = "file"
+        else:
+            prompt_text = args.prompt
+            prompt_source = "inline"
+
+        payload = invoke_route_binding(
+            repo_root,
+            role=args.role,
+            prompt=prompt_text,
+            timeout_ms=args.timeout_ms,
+            write_discovery=not args.no_write,
+        )
+        payload["prompt_source"] = prompt_source
+        payload["prompt_bundle_path"] = prompt_bundle_path
+    except (OSError, RouterConfigError) as exc:
+        print(f"[FAIL] {exc}")
+        return 1
+
+    if args.output_file and payload["output_text"]:
+        output_path = Path(args.output_file).resolve()
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        output_path.write_text(str(payload["output_text"]).rstrip() + "\n", encoding="utf-8", newline="\n")
+    if args.metadata_file:
+        metadata_path = Path(args.metadata_file).resolve()
+        write_json(metadata_path, payload)
+
+    if args.json:
+        print(pretty_json(payload), end="")
+    else:
+        print(
+            f"Role={payload['role']} Decision={payload['decision']['decision']} "
+            f"CLI={payload['cli'] or 'none'} Model={payload['model'] or 'none'} "
+            f"Success={'yes' if payload['success'] else 'no'}"
+        )
+        print(f"Reason: {payload['reason']}")
+        if payload["output_text"]:
+            print("")
+            print(payload["output_text"])
+        elif payload["decision"].get("prompt"):
+            print("")
+            print(payload["decision"]["prompt"])
+
+    return 0 if payload["success"] else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/references/scripts/recursive-router-probe.ps1

@@ -0,0 +1,25 @@
+[CmdletBinding()]
+param(
+    [string]$RepoRoot = (Get-Location).Path,
+    [switch]$Json,
+    [switch]$NoWrite,
+    [int]$TimeoutMs = 0
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+
+$python = if ($env:PYTHON) { $env:PYTHON } elseif (Get-Command python -ErrorAction SilentlyContinue) { "python" } else { $null }
+if (-not $python) {
+    Write-Host "[FAIL] Python executable not found in PATH."
+    exit 1
+}
+
+$scriptPath = Join-Path $PSScriptRoot "recursive-router-probe.py"
+$argsList = @($scriptPath, "--repo-root", $RepoRoot)
+if ($Json) { $argsList += "--json" }
+if ($NoWrite) { $argsList += "--no-write" }
+if ($TimeoutMs -gt 0) { $argsList += @("--timeout-ms", $TimeoutMs) }
+
+& $python @argsList
+exit $LASTEXITCODE

package/references/scripts/recursive-router-probe.py

@@ -0,0 +1,44 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+from recursive_router_lib import RouterConfigError, ensure_router_scaffold, pretty_json, probe_inventory
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Probe available routers for recursive-router.")
+    parser.add_argument("--repo-root", default=".", help="Repository root path.")
+    parser.add_argument("--json", action="store_true", help="Emit machine-readable JSON.")
+    parser.add_argument("--no-write", action="store_true", help="Do not refresh the discovery inventory file.")
+    parser.add_argument("--timeout-ms", type=int, default=None, help="Override probe timeout in milliseconds.")
+    args = parser.parse_args()
+
+    repo_root = Path(args.repo_root).resolve()
+    try:
+        ensure_router_scaffold(repo_root)
+        inventory = probe_inventory(
+            repo_root,
+            timeout_ms=args.timeout_ms,
+            probe_tool="recursive-router-probe",
+            write_discovery=not args.no_write,
+        )
+    except RouterConfigError as exc:
+        print(f"[FAIL] {exc}")
+        return 1
+
+    if args.json:
+        print(pretty_json(inventory), end="")
+    else:
+        for entry in inventory["clis"]:
+            status = "available" if entry["available"] else "unavailable"
+            version = entry["version"] or "unknown version"
+            models = ", ".join(entry["models"]) if entry["models"] else "(no models listed)"
+            print(f"- {entry['id']}: {status}; version={version}; models={models}; source={entry['model_source']}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/references/scripts/recursive-router-resolve.ps1

@@ -0,0 +1,26 @@
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory = $true)][string]$Role,
+    [string]$RepoRoot = (Get-Location).Path,
+    [switch]$Json,
+    [switch]$NoWrite,
+    [int]$TimeoutMs = 0
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+
+$python = if ($env:PYTHON) { $env:PYTHON } elseif (Get-Command python -ErrorAction SilentlyContinue) { "python" } else { $null }
+if (-not $python) {
+    Write-Host "[FAIL] Python executable not found in PATH."
+    exit 1
+}
+
+$scriptPath = Join-Path $PSScriptRoot "recursive-router-resolve.py"
+$argsList = @($scriptPath, "--repo-root", $RepoRoot, "--role", $Role)
+if ($Json) { $argsList += "--json" }
+if ($NoWrite) { $argsList += "--no-write" }
+if ($TimeoutMs -gt 0) { $argsList += @("--timeout-ms", $TimeoutMs) }
+
+& $python @argsList
+exit $LASTEXITCODE

package/references/scripts/recursive-router-resolve.py

@@ -0,0 +1,46 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from recursive_router_lib import RouterConfigError, pretty_json, resolve_route
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Resolve recursive-router routing for a subagent role.")
+    parser.add_argument("--repo-root", default=".", help="Repository root path.")
+    parser.add_argument("--role", required=True, help="Stage-aligned routed role to resolve. Legacy aliases are accepted.")
+    parser.add_argument("--json", action="store_true", help="Emit machine-readable JSON.")
+    parser.add_argument("--no-write", action="store_true", help="Do not refresh the discovery inventory file.")
+    parser.add_argument("--timeout-ms", type=int, default=None, help="Override probe timeout in milliseconds.")
+    args = parser.parse_args()
+
+    repo_root = Path(args.repo_root).resolve()
+    try:
+        decision = resolve_route(
+            repo_root,
+            role=args.role,
+            timeout_ms=args.timeout_ms,
+            write_discovery=not args.no_write,
+        )
+    except RouterConfigError as exc:
+        print(f"[FAIL] {exc}")
+        return 1
+
+    if args.json:
+        print(pretty_json(decision), end="")
+    else:
+        print(
+            f"Role={decision['role']} Decision={decision['decision']} "
+            f"CLI={decision['cli'] or 'none'} Model={decision['model'] or 'none'}"
+        )
+        print(f"Reason: {decision['reason']}")
+        if decision.get("prompt"):
+            print("")
+            print(decision["prompt"])
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/references/scripts/recursive-router-validate.ps1

@@ -0,0 +1,17 @@
+[CmdletBinding()]
+param(
+    [string]$RepoRoot = (Get-Location).Path
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+
+$python = if ($env:PYTHON) { $env:PYTHON } elseif (Get-Command python -ErrorAction SilentlyContinue) { "python" } else { $null }
+if (-not $python) {
+    Write-Host "[FAIL] Python executable not found in PATH."
+    exit 1
+}
+
+$scriptPath = Join-Path $PSScriptRoot "recursive-router-validate.py"
+& $python $scriptPath "--repo-root" $RepoRoot
+exit $LASTEXITCODE

package/references/scripts/recursive-router-validate.py

@@ -0,0 +1,27 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from recursive_router_lib import RouterConfigError, load_policy, normalize_repo_path, router_policy_path
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Validate recursive-router routing policy.")
+    parser.add_argument("--repo-root", default=".", help="Repository root path.")
+    args = parser.parse_args()
+
+    repo_root = Path(args.repo_root).resolve()
+    try:
+        load_policy(repo_root)
+    except RouterConfigError as exc:
+        print(f"[FAIL] {exc}")
+        return 1
+
+    print(f"[OK] Routing policy is valid: {normalize_repo_path(str(router_policy_path(repo_root).relative_to(repo_root)))}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/references/scripts/recursive-status.ps1

@@ -0,0 +1,23 @@
+[CmdletBinding()]
+param(
+    [string]$RunId = "",
+    [string]$RepoRoot = (Get-Location).Path,
+    [switch]$ShowHashes
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+
+$python = if ($env:PYTHON) { $env:PYTHON } elseif (Get-Command python -ErrorAction SilentlyContinue) { "python" } else { $null }
+if (-not $python) {
+    Write-Host "[FAIL] Python executable not found in PATH."
+    exit 1
+}
+
+$scriptPath = Join-Path $PSScriptRoot "recursive-status.py"
+$argsList = @($scriptPath, "--repo-root", $RepoRoot)
+if ($RunId) { $argsList += @("--run-id", $RunId) }
+if ($ShowHashes.IsPresent) { $argsList += "--show-hashes" }
+
+& $python @argsList
+exit $LASTEXITCODE