orizu 0.3.7 → 0.4.0

package/vendor/orizu-gepa-python/src/orizu_gepa/reflection.py

@@ -2,14 +2,31 @@ from __future__ import annotations
 
 import json
 import os
+import random
+import socket
 import ssl
 import subprocess
 import tempfile
+import time
 import urllib.error
 import urllib.request
+from collections.abc import Callable
 from typing import Any
 
-from .optimizer import ReflectionResult, RowEvaluation, TextGepaConfig, build_reflection_prompt, extract_candidate_text
+from .optimizer import (
+    ReflectionResult,
+    RetryableReflectionError,
+    RowEvaluation,
+    TextGepaConfig,
+    build_reflection_prompt,
+    extract_candidate_text,
+)
+
+
+RETRYABLE_HTTP_STATUS_CODES = {429, 500, 502, 503, 504, 529}
+RETRY_BACKOFF_BASE_SECONDS = 5.0
+RETRY_BACKOFF_JITTER_SECONDS = 5.0
+RETRYABLE_DIRECT_ERRORS = (TimeoutError, socket.timeout, ConnectionResetError, ConnectionAbortedError)
 
 
 def _read_anthropic_response_with_curl(api_key: str, payload: dict[str, Any]) -> dict[str, Any]:
@@ -40,6 +57,73 @@ def _read_anthropic_response_with_curl(api_key: str, payload: dict[str, Any]) ->
     return json.loads(result.stdout)
 
 
+def _validate_positive_http_config(value: int, name: str) -> int:
+    if value <= 0:
+        raise RuntimeError(f"{name} must be positive")
+    return value
+
+
+def _retry_backoff_seconds(attempt: int) -> float:
+    return (RETRY_BACKOFF_BASE_SECONDS * (2 ** attempt)) + random.uniform(0, RETRY_BACKOFF_JITTER_SECONDS)
+
+
+def _is_retryable_http_status(status_code: int) -> bool:
+    return status_code in RETRYABLE_HTTP_STATUS_CODES
+
+
+def _is_retryable_url_error(error: urllib.error.URLError) -> bool:
+    return isinstance(error.reason, RETRYABLE_DIRECT_ERRORS)
+
+
+def _read_json_response_with_retries(
+    request: urllib.request.Request,
+    *,
+    timeout_seconds: int,
+    retry_attempts: int,
+    failure_prefix: str,
+    ssl_fallback: Callable[[], dict[str, Any]] | None = None,
+) -> dict[str, Any]:
+    timeout_seconds = _validate_positive_http_config(timeout_seconds, "reflection_http_timeout_seconds")
+    retry_attempts = _validate_positive_http_config(retry_attempts, "reflection_retry_attempts")
+
+    for attempt in range(retry_attempts):
+        try:
+            with urllib.request.urlopen(request, timeout=timeout_seconds) as response:
+                return json.loads(response.read().decode("utf-8"))
+        except urllib.error.HTTPError as error:
+            if _is_retryable_http_status(error.code) and attempt < retry_attempts - 1:
+                time.sleep(_retry_backoff_seconds(attempt))
+                continue
+            detail = error.read().decode("utf-8", errors="replace")
+            if _is_retryable_http_status(error.code):
+                raise RetryableReflectionError(
+                    f"{failure_prefix} retryable HTTP failure after {retry_attempts} attempts: "
+                    f"{error.code} {detail}"
+                ) from error
+            raise RuntimeError(f"{failure_prefix}: {error.code} {detail}") from error
+        except urllib.error.URLError as error:
+            if isinstance(error.reason, ssl.SSLCertVerificationError) and ssl_fallback is not None:
+                return ssl_fallback()
+            if _is_retryable_url_error(error):
+                if attempt < retry_attempts - 1:
+                    time.sleep(_retry_backoff_seconds(attempt))
+                    continue
+                raise RetryableReflectionError(
+                    f"{failure_prefix} retryable connection failure after {retry_attempts} attempts: "
+                    f"{error.reason}"
+                ) from error
+            raise
+        except RETRYABLE_DIRECT_ERRORS as error:
+            if attempt < retry_attempts - 1:
+                time.sleep(_retry_backoff_seconds(attempt))
+                continue
+            raise RetryableReflectionError(
+                f"{failure_prefix} timed out after {retry_attempts} attempts: {error}"
+            ) from error
+
+    raise RetryableReflectionError(f"{failure_prefix} failed after {retry_attempts} attempts")
+
+
 def _merge_provider_settings(
     payload: dict[str, Any],
     settings: dict[str, Any],
@@ -143,16 +227,13 @@ def reflect_with_anthropic(parent_text: str, parent_results: list[RowEvaluation]
             "content-type": "application/json",
         },
     )
-    try:
-        with urllib.request.urlopen(request, timeout=180) as response:
-            data = json.loads(response.read().decode("utf-8"))
-    except urllib.error.HTTPError as error:
-        detail = error.read().decode("utf-8", errors="replace")
-        raise RuntimeError(f"Reflection LM failed: {error.code} {detail}") from error
-    except urllib.error.URLError as error:
-        if not isinstance(error.reason, ssl.SSLCertVerificationError):
-            raise
-        data = _read_anthropic_response_with_curl(api_key, payload)
+    data = _read_json_response_with_retries(
+        request,
+        timeout_seconds=config.reflection_http_timeout_seconds,
+        retry_attempts=config.reflection_retry_attempts,
+        failure_prefix="Reflection LM failed",
+        ssl_fallback=lambda: _read_anthropic_response_with_curl(api_key, payload),
+    )
     parts = data.get("content") or []
     text = "".join(part.get("text", "") for part in parts if isinstance(part, dict))
     return ReflectionResult(
@@ -180,12 +261,12 @@ def reflect_with_openai(parent_text: str, parent_results: list[RowEvaluation], c
             "Content-Type": "application/json",
         },
     )
-    try:
-        with urllib.request.urlopen(request, timeout=180) as response:
-            data = json.loads(response.read().decode("utf-8"))
-    except urllib.error.HTTPError as error:
-        detail = error.read().decode("utf-8", errors="replace")
-        raise RuntimeError(f"OpenAI reflection LM failed: {error.code} {detail}") from error
+    data = _read_json_response_with_retries(
+        request,
+        timeout_seconds=config.reflection_http_timeout_seconds,
+        retry_attempts=config.reflection_retry_attempts,
+        failure_prefix="OpenAI reflection LM failed",
+    )
     text = _extract_openai_output_text(data)
     if not text:
         raise RuntimeError("OpenAI reflection LM returned no output text")

package/vendor/skills/orizu-cli/SKILL.md

@@ -22,15 +22,18 @@ Skip this skill when:
 
 - Node.js 20+ installed.
 - Install the CLI: `npm i -g orizu`.
-- Install this skill from the CLI package: `orizu install-skill --target agent-user --yes`.
+- Install this skill from the CLI package: `orizu install-skill --agent codex --yes` (or `--agent claude`; advanced target IDs remain available via `--target`).
+- Or read the bundled skill in place without installing: `orizu skills path --json` returns `root`, `skillMd`, `source`, `cliVersion`, and `skillHash`.
+- After CLI upgrades, check installed copies with `orizu skills status` and refresh them with `orizu skills update`.
 - Rediscover the command surface any time with `orizu --help`, `orizu <group> --help`, or `orizu capabilities --json`.
+- Every command supports `--json` (prefix `orizu --json <cmd>` or trailing flag) and emits a single JSON document; prefer it over parsing human-formatted text. Long-running commands emit the JSON summary as the final stdout line.
 - Login callback requires `127.0.0.1:43123`.
 - Credentials are stored at `~/.config/orizu/credentials.json`.
 - Current `orizu login` creates a user-owned personal access token for the CLI and stores it as a v3 API-key credential. The raw token is not recoverable after creation.
 
 ## Login
 
-- Verify auth: `orizu whoami`.
+- Verify auth: `orizu whoami --json` (returns `{user, server}`; non-zero exit means sign in is needed).
 - Start the login flow: `orizu login` (opens a browser tab).
 - Approving login in the browser creates a personal access token for that Orizu user. The token inherits the user's current team/project access and loses access if the user's role or membership changes.
 - Clear local credentials and revoke the current CLI token: `orizu logout`.
@@ -143,12 +146,14 @@ Local execution workflow:
 7. Diff before/after on a held-out set; ship if it holds.
 
 Bundled `run-gepa` reflection behavior:
+- Budget controls are mutually exclusive. Use at most one of `--budget auto|light|medium|heavy`, `--max-metric-calls <n>`, `--max-full-evals <n>`, or `--max-iterations <n>`. If none is provided, `run-gepa` uses `--budget auto`, the balanced medium preset.
 - The reflective LM's final text is used verbatim as the next candidate prompt. It should return only the complete updated prompt body, not analysis, labels, XML tags, or markdown fences.
 - Keep provider-native reasoning controls separate from the prompt text with `--reflection-provider-settings <json|@file>`.
 - Reflection max-token limits are explicit config, not implicit defaults. Use `--reflection-max-tokens <n>` when a provider requires an output cap; this maps to Anthropic `max_tokens` and OpenAI `max_output_tokens`.
 - Anthropic native Messages reflection requires `max_tokens`, so `run-gepa` with an `anthropic/...` reflection model must receive `--reflection-max-tokens <n>` and should fail fast if it is omitted. OpenAI reflection may omit `max_output_tokens` unless the user explicitly wants a cap.
+- Reflection HTTP calls retry transient provider failures by default (`--reflection-retry-attempts 3`, `--reflection-http-timeout-seconds 180`). Retryable failures include timeouts, connection reset/abort, HTTP 429, and common server/capacity statuses. If reflection still fails after retries, `run-gepa` logs `reflection_failed`, counts the proposal against budget, and continues to the next iteration.
 - By default, `run-gepa` skips reflection and child creation when every row in the selected parent mini-batch is already perfect (`1.0` for higher-is-better scorers, `0.0` for lower-is-better scorers). This saves reflection tokens because the child cannot beat a saturated mini-batch. Use `--no-skip-perfect-parent-reflection` to force reflection anyway, or `--skip-perfect-parent-reflection` to make the default explicit in scripted runs.
-- By default, `run-gepa` sets `--num-threads auto` for row evaluations. Auto uses mini-batch size, validation-set size, CPU count, memory estimate, file-descriptor limit, and an 8-thread hard cap to avoid launching too many runner subprocesses at once. Use `--num-threads <n>` only when the runner/provider capacity is known.
+- By default, `run-gepa` sets `--num-threads auto` for row evaluations. Auto uses mini-batch size, validation-set size, 2x CPU count, memory estimate, file-descriptor limit, and a 64-thread default ceiling to avoid launching too many runner subprocesses at once while still scaling large runs. Set `ORIZU_GEPA_AUTO_THREADS_MAX` or use `--num-threads <n>` only when the runner/provider capacity is known.
 - `run-gepa` writes complete local logs by default under `logs/<optimization_run_id>`; override with `--log-dir <dir>` or disable with `--no-local-log`.
 - Server optimization events redact row snapshots and reflection prompts by default; the local log keeps full row inputs, outputs, scores, feedback, reflection prompts, and reflection responses for later agent analysis.
 - OpenAI example: `--reflection-model openai/gpt-5 --reflection-provider-settings '{"reasoning":{"effort":"medium","summary":"auto"}}'`.

package/vendor/skills/orizu-cli/references/cli-reference.md

@@ -12,8 +12,9 @@
 1. Verify auth first: `orizu whoami`.
 2. Prefer explicit flags over prompts.
 3. Use interactive fallback only in TTY sessions.
-4. Validate command output before proceeding.
-5. On failure, fix flags/identifiers and rerun.
+4. Prefer `--json` for machine-readable output — every command supports it (prefix `orizu --json <cmd>` or trailing flag). Long-running commands emit the JSON summary as the final stdout line.
+5. Validate command output before proceeding.
+6. On failure, fix flags/identifiers and rerun.
 
 ## Command Matrix
 
@@ -33,6 +34,25 @@ Behavior:
 - PATs can also be revoked from the Personal Tokens page in Orizu.
 - PAT authorization follows the owning user's current team/project roles, so demotion or removal takes effect without rotating the token.
 
+### Agent Setup
+
+```bash
+orizu capabilities --json
+orizu skills path [--skill-md] [--json]
+orizu skills status [--json]
+orizu skills update [--dry-run] [--json]
+orizu install-skill [--agent <claude|codex>]... [--scope global|project] [--mode auto|link|copy] [--yes] [--dry-run] [--json]
+orizu setup [--agent <claude|codex>]... [--skip-login] [--no-install] [--workspace|--no-workspace] [--no-handoff] [--yes] [--dry-run] [--no-input] [--json]
+orizu setup prompt [--json]
+```
+
+Behavior:
+- `capabilities --json` returns the full machine-readable command manifest, including `globalOptions`.
+- `skills path --json` returns where this skill's source lives (`root`, `skillMd`, `source`, `cliVersion`, `skillHash`) so you can read it without installing, and verify an installed copy matches the CLI.
+- `skills status` reports each install target as missing/current/stale/broken-link; `skills update` refreshes stale copies and repairs broken symlinks.
+- `install-skill` selects targets by agent name; `--scope global` (default) installs user-level, `--scope project` into the repo. Project-scope installs always copy; global installs symlink when the CLI path is stable. Advanced target IDs remain available via `--target`.
+- `orizu setup` is the guided onboarding flow (login → agent integration → `.orizu/` workspace → handoff prompt). `orizu setup prompt` prints the repo-adoption prompt for handing to a coding agent.
+
 ### Teams
 
 ```bash
@@ -232,13 +252,14 @@ For prompts, judges, runners, run submission, optimizer artifacts, live event lo
 Optimization trace commands:
 
 ```bash
-orizu optimizations run-gepa ... [--num-threads auto|N] [--log-dir logs] [--no-local-log]
+orizu optimizations run-gepa ... [--num-threads auto|N] [--reflection-retry-attempts 3] [--reflection-http-timeout-seconds 180] [--log-dir logs] [--no-local-log]
 orizu optimizations export <optimization-run-id> --out ./optimization.json
 orizu optimizations export <optimization-run-id> --json
 ```
 
 Behavior:
-- `run-gepa` defaults `--num-threads` to `auto`, resolving a conservative row-evaluation parallelism cap from mini-batch size, validation-set size, CPU count, memory estimate, file-descriptor limit, and an 8-thread hard cap.
+- `run-gepa` defaults `--num-threads` to `auto`, resolving a row-evaluation parallelism cap from mini-batch size, validation-set size, 2x CPU count, memory estimate, file-descriptor limit, and a 64-thread default ceiling. Set `ORIZU_GEPA_AUTO_THREADS_MAX` or use `--num-threads <n>` only when the runner/provider capacity is known.
+- `run-gepa` retries transient reflection-provider failures by default. If retries are exhausted, it logs `reflection_failed`, counts that reflection proposal against budget, and continues with the next iteration.
 - `run-gepa` writes a complete local trace under `logs/<optimization_run_id>` by default.
 - The local trace is the best artifact for coding-agent analysis because it includes full rows, outputs, scores, feedback, scorer responses, reflection prompts, reflection responses, candidate text, and `result.json`.
 - `optimizations export` writes a portable JSON artifact from server data when the local log is unavailable or the run happened elsewhere.

package/vendor/skills/orizu-cli/references/optimization-reports.md

@@ -130,9 +130,9 @@ Set an explicit expectation before the run: for example, "if best kappa does not
 
 ### Budget Versus Iteration Cap
 
-Default budget presets are DSPy-style metric-call budgets. `light`, `medium`, and `heavy` map to DSPy's `auto="light"`, `auto="medium"`, and `auto="heavy"` scales; `auto` is treated as the balanced `medium` preset. The final metric-call limit scales with validation-set size, rather than using fixed tiny constants. `--max-metric-calls` overrides this directly, while `--max-full-evals` is converted to a metric-call budget over `train + validation` rows.
+Default budget presets are DSPy-style metric-call budgets. `light`, `medium`, and `heavy` map to DSPy's `auto="light"`, `auto="medium"`, and `auto="heavy"` scales; `auto` is treated as the balanced `medium` preset and is the default when no budget control is provided. The final metric-call limit scales with validation-set size, rather than using fixed tiny constants. `--budget`, `--max-metric-calls`, `--max-full-evals`, and `--max-iterations` are mutually exclusive CLI budget controls; choose only one.
 
-Budget is checked only between iterations. Once an iteration starts, `run-gepa` completes the parent minibatch, child minibatch, and full validation eval for an accepted child even if that overshoots the nominal budget. If a run ends as `budget_exhausted`, it pauses and does not auto-promote. If auto-promotion matters, either increase budget to fit the iteration target or lower `--max-iterations` to fit the budget.
+Metric-call and full-eval budgets are checked only between iterations. Once an iteration starts, `run-gepa` completes the parent minibatch, child minibatch, and full validation eval for an accepted child even if that overshoots the nominal budget. If a run ends as `budget_exhausted`, it pauses and does not auto-promote. If auto-promotion matters, choose a single budget control large enough to cover the intended search.
 
 ### Reflection Signal Quality
 

package/vendor/skills/orizu-cli/references/optimization-with-gepa.md

@@ -62,6 +62,7 @@ Reflection output contract:
 - The default reflection prompt asks for only the complete updated prompt body. Do not ask the model to wrap the candidate in markdown fences or tags; real prompts often contain those characters.
 - Put provider-native reasoning controls in `--reflection-provider-settings <json|@file>`, not in the prompt body. For OpenAI reasoning models, use a shape such as `{"reasoning":{"effort":"medium","summary":"auto"}}`. For Anthropic Claude models with thinking controls, use a shape such as `{"thinking":{"type":"adaptive","display":"omitted"},"output_config":{"effort":"medium"}}`.
 - Reflection max-token limits are explicit. `--reflection-max-tokens <n>` maps to Anthropic `max_tokens` and OpenAI `max_output_tokens`; Anthropic native Messages reflection requires it, while OpenAI may omit it when no cap is desired.
+- Reflection HTTP calls retry transient failures by default (`--reflection-retry-attempts 3`, `--reflection-http-timeout-seconds 180`). Exhausted retryable failures emit `reflection_failed`, consume one candidate-proposal budget slot, and move to the next iteration instead of killing the run.
 
 Full command syntax and event contracts: `prompt-control-plane.md`.
 

package/vendor/skills/orizu-cli/references/prompt-control-plane.md

@@ -332,9 +332,21 @@ List:
 
 ```bash
 orizu --local prompts list --project <team>/<project>
+orizu --local prompts list --project <team>/<project> --status archived
+orizu --local prompts list --project <team>/<project> --status all
 orizu --local judges list --project <team>/<project>
 ```
 
+Prompt and judge lists show active artifacts by default. Use `--status archived`
+or `--status all` when you need archived artifacts.
+
+Archive or restore a prompt:
+
+```bash
+orizu --local prompts archive <prompt-id-or-name> --project <team>/<project>
+orizu --local prompts restore <prompt-id-or-name> --project <team>/<project>
+```
+
 List prompt comment threads for the latest version, or a specific label/version:
 
 ```bash
@@ -607,20 +619,19 @@ orizu --local optimizations run-gepa \
   --train-split train \
   --val-split validation \
   --log-dir ./logs \
-  --budget light \
-  --max-iterations 3 \
   --minibatch-size 3 \
   --num-threads auto
 ```
 
 Useful GEPA flags:
 
-- `--budget auto|light|medium|heavy`, `--max-metric-calls <n>`, `--max-full-evals <n>`.
+- Budget controls are mutually exclusive: choose at most one of `--budget auto|light|medium|heavy`, `--max-metric-calls <n>`, `--max-full-evals <n>`, or `--max-iterations <n>`. With none provided, `run-gepa` defaults to `--budget auto`, the balanced medium preset.
 - `--minibatch-size <n>` defaults to 3.
-- `--num-threads auto|N` defaults to `auto`; auto caps row-evaluation concurrency from mini-batch size, validation-set size, CPU count, memory estimate, file-descriptor limit, and an 8-thread hard cap.
+- `--num-threads auto|N` defaults to `auto`; auto caps row-evaluation concurrency from mini-batch size, validation-set size, 2x CPU count, memory estimate, file-descriptor limit, and a 64-thread default ceiling. Set `ORIZU_GEPA_AUTO_THREADS_MAX` or use `--num-threads <n>` only when the runner/provider capacity is known.
 - `--candidate-selection-strategy pareto|current_best|epsilon_greedy`; default is `pareto`.
 - `--reflection-model <provider/model>`, `--reflection-temperature <n>`, `--reflection-prompt-template <text|@file>`.
 - `--reflection-max-tokens <n>` is explicit provider config, not a global default. It maps to Anthropic `max_tokens` and OpenAI `max_output_tokens`; Anthropic native Messages reflection requires it, while OpenAI can omit it unless the user wants a cap.
+- `--reflection-retry-attempts` and `--reflection-http-timeout-seconds` tune transient reflection-provider retries. Exhausted retryable failures log `reflection_failed`, count against candidate-proposal budget, and continue with the next iteration.
 - `--reflection-provider-settings <json|@file>` passes provider-native reflection settings separately from the prompt text. Anthropic example: `{"thinking":{"type":"adaptive","display":"omitted"},"output_config":{"effort":"medium"}}`. OpenAI example: `{"reasoning":{"effort":"medium","summary":"auto"}}`.
 - `--disable-evaluation-cache` turns off candidate/row/scorer cache reuse.
 - `--auto-promote --promotion-label <label>` promotes the best candidate at the end.
@@ -718,7 +729,8 @@ Rules:
 - `eventId` must be stable and unique within one optimization run.
 - `eventLayer` is `core`, `extension`, or `system`.
 - Generic core events: `run_started`, `iteration_started`, `candidate_proposed`, `candidate_scored`, `candidate_recommended`, `iteration_completed`, `run_completed`, `run_failed`.
-- GEPA extension events: `seed_val_set_started`, `seed_val_set_completed`, `parent_minibatch_started`, `parent_minibatch_completed`, `reflection_started`, `reflection_completed`, `child_candidate_created`, `child_minibatch_started`, `child_minibatch_completed`, `acceptance_decision_made`, `merge_started`, `merge_completed`.
+- GEPA extension events: `seed_val_set_started`, `seed_val_set_completed`, `parent_minibatch_started`, `parent_minibatch_completed`, `reflection_started`, `reflection_completed`, `child_candidate_created`, `child_minibatch_started`, `child_minibatch_completed`, `acceptance_decision_made`, `optimization_progress`, `merge_started`, `merge_completed`.
+- Emit `optimization_progress` after each completed iteration with `percent`, `metric_calls_used`, `metric_call_budget`, and `metric_calls_remaining`. Cap displayed `percent` at `100` and floor `metric_calls_remaining` at `0`; a started iteration may spend past the nominal metric-call budget before the optimizer pauses.
 - Do not send per-LM-call telemetry to this endpoint in Phase 0. Put aggregate call/token/cost stats in iteration or run payloads.
 
 Shell fallback: