okstra 0.1.0

package/runtime/bin/okstra-central.sh

@@ -0,0 +1,152 @@
+#!/usr/bin/env bash
+# okstra 중앙 컨트롤 센터의 write-side 헬퍼 모음.
+# okstra.sh 와 okstra-ctl.sh 양쪽에서 source 하여 사용한다.
+
+# 중앙 디렉터리 위치를 해석한다. OKSTRA_HOME 이 설정돼 있으면 그 값을, 아니면 $HOME/.okstra 를 사용한다.
+okstra_central_home() {
+  if [[ -n "${OKSTRA_HOME:-}" ]]; then
+    printf '%s\n' "$OKSTRA_HOME"
+  else
+    printf '%s\n' "$HOME/.okstra"
+  fi
+}
+
+# 중앙 디렉터리와 필수 파일을 생성한다. 멱등성이 보장된다.
+okstra_central_bootstrap() {
+  local home
+  home="$(okstra_central_home)"
+  python3 - "$home" <<'PY'
+import json
+import os
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+home = Path(sys.argv[1])
+# OKSTRA_HOME 은 사용자 지정 override 가 가능하며 ($XDG_STATE_HOME/okstra
+# 처럼) 부모 디렉터리가 없는 nested 경로일 수 있다. parents=False 로
+# mkdir 하면 모든 okstra-ctl 진입점과 record_start hook 이 bootstrap 단계
+# 에서 FileNotFoundError 로 abort 하므로, 부모까지 함께 생성한다.
+home.mkdir(mode=0o700, parents=True, exist_ok=True)
+os.chmod(home, 0o700)
+for sub in ("archive", ".locks", "batches", "projects"):
+    (home / sub).mkdir(exist_ok=True)
+for f in ("active.jsonl", "recent.jsonl"):
+    (home / f).touch(exist_ok=True)
+state_file = home / "state.json"
+if not state_file.exists():
+    payload = {
+        "schemaVersion": "1",
+        "createdAt": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+        "backfilledAt": None,
+    }
+    state_file.write_text(json.dumps(payload, indent=2) + "\n")
+    os.chmod(state_file, 0o600)
+PY
+}
+
+# 인자로 받은 명령을 ~/.okstra/.lock 위에 fcntl LOCK_EX 로 직렬화해 실행한다.
+# 사용법: okstra_central_with_lock "<bash command string>"
+# 주: macOS 는 util-linux 의 `flock` 바이너리를 제공하지 않아 python fcntl 을 사용한다.
+okstra_central_with_lock() {
+  local home cmd lockfile
+  home="$(okstra_central_home)"
+  cmd="$1"
+  lockfile="$home/.lock"
+  : >> "$lockfile"
+  python3 - "$lockfile" "$cmd" <<'PY'
+import fcntl, subprocess, sys
+lockpath, cmd = sys.argv[1], sys.argv[2]
+with open(lockpath, "r+") as lock:
+    fcntl.flock(lock.fileno(), fcntl.LOCK_EX)
+    rc = subprocess.run(["bash", "-c", cmd]).returncode
+sys.exit(rc)
+PY
+}
+
+# okstra.sh 에서 호출되는 메인 hook. 환경변수에서 메타를 읽어
+# active.jsonl, projects/<id>/index.jsonl, invocation, meta.json 을
+# 단일 락 트랜잭션으로 갱신한다.
+#
+# 이전 구현은 OKSTRA_HOME / OKSTRA_CTL_LIB_DIR 값을 OKSTRA_HOME='$home'
+# 형태로 bash -c 문자열에 박아 okstra_central_with_lock 에 넘겼는데,
+# OKSTRA_HOME 이나 체크아웃 경로에 single quote 가 포함되면 syntax error
+# 로 hook 이 silently 실패해 해당 run 이 중앙 인덱스에 남지 않았다.
+# 이를 피하기 위해 값은 환경변수로 전달하고, 락은 python 안에서 직접
+# fcntl.flock 으로 잡는다(okstra_central_with_lock 와 동일 lockfile).
+okstra_central_record_start() {
+  local home script_dir payload_json
+  home="$(okstra_central_home)"
+  script_dir="$(cd -P "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  # 빈 default 일 때 JSON 호환 문자열로 미리 정규화한다.
+  local _argv_json="${OKSTRA_INVOCATION_ARGV_JSON-}"
+  [[ -z "$_argv_json" ]] && _argv_json='[]'
+  local _env_json="${OKSTRA_INVOCATION_ENV_JSON-}"
+  [[ -z "$_env_json" ]] && _env_json='{}'
+  local _initial_status="${OKSTRA_INITIAL_STATUS-}"
+  [[ -z "$_initial_status" ]] && _initial_status='running'
+  local _run_seq="${OKSTRA_RUN_SEQ-}"
+  [[ -z "$_run_seq" ]] && _run_seq='0'
+  # Build the entire payload as a JSON string in bash (no env-var passthrough),
+  # then hand it to python via argv so this hook is callable inside any
+  # claude-session subprocess without leaking shell-globals into the parent
+  # process environment.
+  payload_json="$(python3 -c '
+import json, sys
+it = iter(sys.argv[1:])
+print(json.dumps({k: v for k, v in zip(it, it)}, ensure_ascii=False))
+' \
+    OKSTRA_CTL_LIB_DIR "$script_dir" \
+    OKSTRA_HOME "$home" \
+    PROJECT_ID "${PROJECT_ID-}" \
+    PROJECT_ROOT "${PROJECT_ROOT-}" \
+    TASK_GROUP "${TASK_GROUP-}" \
+    TASK_ID "${TASK_ID-}" \
+    ANALYSIS_TYPE "${ANALYSIS_TYPE-}" \
+    OKSTRA_RUN_SEQ "$_run_seq" \
+    RUN_TIMESTAMP_ISO "${RUN_TIMESTAMP_ISO-}" \
+    SELECTED_REVIEWERS "${SELECTED_REVIEWERS-}" \
+    LEAD_MODEL_DISPLAY "${LEAD_MODEL_DISPLAY-}" \
+    RUN_DIR_RELATIVE_PATH "${RUN_DIR_RELATIVE_PATH-}" \
+    FINAL_REPORT_RELATIVE_PATH "${FINAL_REPORT_RELATIVE_PATH-}" \
+    FINAL_STATUS_RELATIVE_PATH "${FINAL_STATUS_RELATIVE_PATH-}" \
+    OKSTRA_INVOCATION_ARGV_JSON "$_argv_json" \
+    OKSTRA_INVOCATION_CWD "${OKSTRA_INVOCATION_CWD-}" \
+    OKSTRA_INVOCATION_ENV_JSON "$_env_json" \
+    OKSTRA_INITIAL_STATUS "$_initial_status" \
+    OKSTRA_INVOCATION_BRIEF_SHA256 "${OKSTRA_INVOCATION_BRIEF_SHA256-}")"
+  python3 - "$payload_json" <<'PY'
+import fcntl, json, sys
+payload = json.loads(sys.argv[1])
+sys.path.insert(0, payload["OKSTRA_CTL_LIB_DIR"])
+from pathlib import Path
+from okstra_ctl import record_start
+
+home = Path(payload["OKSTRA_HOME"])
+lockfile = home / ".lock"
+home.mkdir(parents=True, exist_ok=True)
+lockfile.touch()
+with lockfile.open("r+") as lock:
+    fcntl.flock(lock.fileno(), fcntl.LOCK_EX)
+    record_start(
+        home,
+        project_id=payload["PROJECT_ID"],
+        project_root=payload["PROJECT_ROOT"],
+        task_group=payload["TASK_GROUP"],
+        task_id=payload["TASK_ID"],
+        task_type=payload.get("ANALYSIS_TYPE", ""),
+        run_seq=int(payload["OKSTRA_RUN_SEQ"]),
+        when=payload["RUN_TIMESTAMP_ISO"],
+        workers=[w for w in payload.get("SELECTED_REVIEWERS", "").split(",") if w],
+        lead_model=payload.get("LEAD_MODEL_DISPLAY", ""),
+        run_dir_rel=payload.get("RUN_DIR_RELATIVE_PATH", ""),
+        final_report_rel=payload.get("FINAL_REPORT_RELATIVE_PATH", ""),
+        final_status_rel=payload.get("FINAL_STATUS_RELATIVE_PATH", ""),
+        argv=json.loads(payload.get("OKSTRA_INVOCATION_ARGV_JSON", "[]")),
+        cwd=payload.get("OKSTRA_INVOCATION_CWD", ""),
+        env_overrides=json.loads(payload.get("OKSTRA_INVOCATION_ENV_JSON", "{}") or "{}"),
+        initial_status=payload.get("OKSTRA_INITIAL_STATUS", "running"),
+        brief_sha256=payload.get("OKSTRA_INVOCATION_BRIEF_SHA256", ""),
+    )
+PY
+}

package/runtime/bin/okstra-codex-exec.sh

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+# okstra-codex-exec.sh — wrapper around `codex exec` for okstra codex-worker
+#
+# Purpose: Claude Code's Bash permission matcher requires explicit approval for
+# commands that contain shell metacharacters (stdin/stderr redirects, pipes).
+# `codex exec ... - < <prompt-path> 2>/dev/null` therefore triggers a permission
+# prompt every dispatch even when `Bash(codex exec:*)` is allowlisted, because
+# the redirect tokens disqualify the simple-prefix match.
+#
+# This wrapper accepts positional arguments and performs the redirect inside
+# the script body, so the caller can allowlist a single non-redirect form:
+#
+#   Bash($HOME/.okstra/bin/okstra-codex-exec.sh:*)
+#
+# Usage:
+#   okstra-codex-exec.sh <project-root> <model-execution-value> <prompt-path>
+#
+# All three arguments are required and must be absolute paths or literal model
+# strings. The wrapper exits non-zero on any preflight failure.
+set -euo pipefail
+
+if [[ $# -ne 3 ]]; then
+  printf 'usage: %s <project-root> <model-execution-value> <prompt-path>\n' "$(basename "$0")" >&2
+  exit 64
+fi
+
+project_root="$1"
+model="$2"
+prompt_path="$3"
+
+if [[ -z "$project_root" || ! -d "$project_root" ]]; then
+  printf 'okstra-codex-exec: project-root is missing or not a directory: %q\n' "$project_root" >&2
+  exit 65
+fi
+
+if [[ -z "$model" ]]; then
+  printf 'okstra-codex-exec: model-execution-value is empty\n' >&2
+  exit 66
+fi
+
+if [[ -z "$prompt_path" || ! -f "$prompt_path" ]]; then
+  printf 'okstra-codex-exec: prompt-path is missing or not a file: %q\n' "$prompt_path" >&2
+  exit 67
+fi
+
+if ! command -v codex >/dev/null 2>&1; then
+  printf 'okstra-codex-exec: codex CLI is not installed on PATH\n' >&2
+  exit 127
+fi
+
+# stdin redirect and stderr suppression are intentionally inside the wrapper —
+# this is the entire reason this script exists.
+exec codex exec -C "$project_root" --model "$model" --full-auto - < "$prompt_path" 2>/dev/null

package/runtime/bin/okstra-error-log.py

@@ -0,0 +1,295 @@
+"""OKSTRA error log helper.
+
+Single writer for runs/<task-type>/logs/errors-<task-type>-<seq>.jsonl.
+"""
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import json
+import os
+from pathlib import Path
+
+STDERR_EXCERPT_MAX_BYTES = 2048
+TRUNCATION_SUFFIX = "...[truncated]"
+PIPE_BUF_BYTES = 4096
+
+ALLOWED_ERROR_TYPES = {"tool-failure", "cli-failure", "contract-violation"}
+ALLOWED_AGENTS = {
+    "claude-lead", "claude-worker", "codex-worker",
+    "gemini-worker", "report-writer",
+}
+ALLOWED_AGENT_ROLES = {"lead", "worker", "report-writer"}
+SUPPORTED_SIDECAR_SCHEMA_VERSIONS = {1}
+
+
+def _now_utc():
+    return dt.datetime.now(dt.timezone.utc)
+
+
+def _iso(t):
+    return t.isoformat()
+
+
+def truncate_stderr(s):
+    """Truncate stderr text to STDERR_EXCERPT_MAX_BYTES, multibyte-safe."""
+    if s is None:
+        return None
+    encoded = s.encode("utf-8")
+    if len(encoded) <= STDERR_EXCERPT_MAX_BYTES:
+        return s
+    cut = encoded[:STDERR_EXCERPT_MAX_BYTES]
+    # 멀티바이트 경계 보호: 디코드 가능해질 때까지 끝 바이트 제거
+    while cut:
+        try:
+            decoded = cut.decode("utf-8")
+            return decoded + TRUNCATION_SUFFIX
+        except UnicodeDecodeError:
+            cut = cut[:-1]
+    return TRUNCATION_SUFFIX
+
+
+def append_jsonl_line(path, record):
+    """Append a single JSON record as one line to ``path``.
+
+    Atomicity guarantee (POSIX only):
+        With ``O_APPEND`` and a single ``write()`` syscall, the kernel
+        appends the entire payload as one indivisible operation as long as
+        the payload size is at most ``PIPE_BUF`` (4096 bytes on Linux and
+        macOS). Larger payloads may be split across syscalls and interleave
+        with concurrent writers, so this helper rejects them with
+        ``ValueError`` rather than silently losing atomicity.
+
+    The atomicity contract holds only on POSIX filesystems with O_APPEND
+    semantics. Concurrent writers using ``O_TRUNC``, ``unlink``, or
+    non-append modes against the same path break the contract and are
+    out of scope for this helper.
+
+    Caller responsibilities:
+    - Keep records small (this module's stderr excerpt cap of
+      ``STDERR_EXCERPT_MAX_BYTES`` exists to keep records well under
+      ``PIPE_BUF_BYTES``).
+    - Handle ``TypeError`` from ``json.dumps`` for non-serializable values.
+
+    Creates parent directories as needed.
+    """
+    p = Path(path)
+    p.parent.mkdir(parents=True, exist_ok=True)
+    # ensure_ascii=False keeps UTF-8 compact (no \uXXXX escapes).
+    # json.dumps escapes literal newlines inside string values, so the
+    # only unescaped newline is the record separator we append below.
+    line = json.dumps(record, ensure_ascii=False, separators=(",", ":")) + "\n"
+    data = line.encode("utf-8")
+    if len(data) > PIPE_BUF_BYTES:
+        raise ValueError(
+            f"record too large for atomic append: {len(data)} bytes > "
+            f"PIPE_BUF ({PIPE_BUF_BYTES})"
+        )
+    # mode 0o644: owner read/write, group/world read-only.
+    fd = os.open(str(p), os.O_WRONLY | os.O_CREAT | os.O_APPEND, 0o644)
+    try:
+        os.write(fd, data)
+    finally:
+        os.close(fd)
+
+
+def append_observed(
+    *,
+    out_path,
+    task_key,
+    phase,
+    agent,
+    agent_role,
+    model,
+    error_type,
+    command,
+    command_kind,
+    exit_code,
+    duration_ms,
+    message,
+    stderr_excerpt,
+    context,
+    now=None,
+):
+    """Append a lead-observed error event to errors.jsonl."""
+    if error_type not in ALLOWED_ERROR_TYPES:
+        raise ValueError(f"invalid errorType: {error_type!r}")
+    if agent not in ALLOWED_AGENTS:
+        raise ValueError(f"invalid agent: {agent!r}")
+    if agent_role not in ALLOWED_AGENT_ROLES:
+        raise ValueError(f"invalid agentRole: {agent_role!r}")
+    ts = _iso(now or _now_utc())
+    rec = {
+        "ts": ts,
+        "recordedAt": ts,
+        "taskKey": task_key,
+        "phase": str(phase),
+        "agent": agent,
+        "agentRole": agent_role,
+        "model": model,
+        "source": "lead-observed",
+        "errorType": error_type,
+        "command": command,
+        "commandKind": command_kind,
+        "exitCode": exit_code,
+        "durationMs": duration_ms,
+        "message": message,
+        "stderrExcerpt": truncate_stderr(stderr_excerpt),
+        "context": context,
+    }
+    append_jsonl_line(out_path, rec)
+    return rec
+
+
+def dump_from_worker_sidecar(
+    *,
+    sidecar_path,
+    out_path,
+    task_key,
+    agent,
+    agent_role,
+    model,
+    now=None,
+):
+    """Read worker sidecar errors[] and append each to errors.jsonl with
+    Lead-side metadata filled in. Returns number of records appended.
+
+    Raises ValueError if:
+      - ``agent`` or ``agent_role`` is not in the allow-lists
+      - sidecar ``schemaVersion`` is not in ``SUPPORTED_SIDECAR_SCHEMA_VERSIONS``
+      - any entry's ``errorType`` is not in ``ALLOWED_ERROR_TYPES``
+
+    Returns 0 (no-op) if the sidecar file does not exist or its
+    ``errors`` list is empty.
+
+    Partial-failure semantics: entries are validated and appended in
+    order. If entry N fails validation, entries 0..N-1 have already
+    been written to ``out_path`` and are NOT rolled back. Callers that
+    require atomicity must validate the sidecar payload before invoking
+    this function.
+    """
+    if agent not in ALLOWED_AGENTS:
+        raise ValueError(f"invalid agent: {agent!r}")
+    if agent_role not in ALLOWED_AGENT_ROLES:
+        raise ValueError(f"invalid agentRole: {agent_role!r}")
+    p = Path(sidecar_path)
+    if not p.exists():
+        return 0
+    payload = json.loads(p.read_text())
+    schema = payload.get("schemaVersion")
+    if schema not in SUPPORTED_SIDECAR_SCHEMA_VERSIONS:
+        raise ValueError(f"unsupported sidecar schemaVersion: {schema!r}")
+    entries = payload.get("errors") or []
+    recorded_at = _iso(now or _now_utc())
+    count = 0
+    for e in entries:
+        et = e.get("errorType")
+        if et not in ALLOWED_ERROR_TYPES:
+            raise ValueError(f"invalid errorType in sidecar: {et!r}")
+        rec = {
+            "ts": e.get("ts"),
+            "recordedAt": recorded_at,
+            "taskKey": task_key,
+            "phase": str(e.get("phase")) if e.get("phase") is not None else None,
+            "agent": agent,
+            "agentRole": agent_role,
+            "model": model,
+            "source": "worker-reported",
+            "errorType": et,
+            "command": e.get("command"),
+            "commandKind": e.get("commandKind"),
+            "exitCode": e.get("exitCode"),
+            "durationMs": e.get("durationMs"),
+            "message": e.get("message"),
+            "stderrExcerpt": truncate_stderr(e.get("stderrExcerpt")),
+            "context": e.get("context"),
+        }
+        append_jsonl_line(out_path, rec)
+        count += 1
+    return count
+
+
+def _build_parser():
+    p = argparse.ArgumentParser(description="OKSTRA error log helper")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    obs = sub.add_parser("append-observed",
+                         help="Append a lead-observed error event")
+    obs.add_argument("--out", required=True)
+    obs.add_argument("--task-key", required=True)
+    obs.add_argument("--phase", required=True)
+    obs.add_argument("--agent", required=True, choices=sorted(ALLOWED_AGENTS))
+    obs.add_argument("--agent-role", required=True, choices=sorted(ALLOWED_AGENT_ROLES))
+    obs.add_argument("--model", required=True)
+    obs.add_argument("--error-type", required=True, choices=sorted(ALLOWED_ERROR_TYPES))
+    obs.add_argument("--command", required=True)
+    obs.add_argument("--command-kind", required=True)
+    obs.add_argument("--exit-code", type=int, default=None)
+    obs.add_argument("--duration-ms", type=int, default=None)
+    obs.add_argument("--message", required=True)
+    grp = obs.add_mutually_exclusive_group()
+    grp.add_argument("--stderr-excerpt", default=None)
+    grp.add_argument("--stderr-excerpt-file", default=None)
+    obs.add_argument("--context-json", default=None,
+                     help="JSON object string for context")
+
+    dump = sub.add_parser("append-from-worker",
+                          help="Dump worker sidecar errors[] into errors.jsonl")
+    dump.add_argument("--sidecar", required=True)
+    dump.add_argument("--out", required=True)
+    dump.add_argument("--task-key", required=True)
+    dump.add_argument("--agent", required=True, choices=sorted(ALLOWED_AGENTS))
+    dump.add_argument("--agent-role", required=True, choices=sorted(ALLOWED_AGENT_ROLES))
+    dump.add_argument("--model", required=True)
+    return p
+
+
+def _read_stderr(args):
+    if args.stderr_excerpt_file:
+        return Path(args.stderr_excerpt_file).read_text()
+    return args.stderr_excerpt
+
+
+def _read_context(args):
+    if args.context_json is None:
+        return None
+    return json.loads(args.context_json)
+
+
+def main(argv=None):
+    args = _build_parser().parse_args(argv)
+    if args.cmd == "append-observed":
+        append_observed(
+            out_path=args.out,
+            task_key=args.task_key,
+            phase=args.phase,
+            agent=args.agent,
+            agent_role=args.agent_role,
+            model=args.model,
+            error_type=args.error_type,
+            command=args.command,
+            command_kind=args.command_kind,
+            exit_code=args.exit_code,
+            duration_ms=args.duration_ms,
+            message=args.message,
+            stderr_excerpt=_read_stderr(args),
+            context=_read_context(args),
+        )
+        return 0
+    if args.cmd == "append-from-worker":
+        n = dump_from_worker_sidecar(
+            sidecar_path=args.sidecar,
+            out_path=args.out,
+            task_key=args.task_key,
+            agent=args.agent,
+            agent_role=args.agent_role,
+            model=args.model,
+        )
+        print(n)
+        return 0
+    # Unreachable: argparse `required=True` on subparsers raises SystemExit
+    # before this function runs if the subcommand is missing or invalid.
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/runtime/bin/okstra-gemini-exec.sh

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+# okstra-gemini-exec.sh — wrapper around `gemini -p -` for okstra gemini-worker
+#
+# Purpose: Claude Code's Bash permission matcher requires explicit approval for
+# commands that contain shell metacharacters (stdin/stderr redirects, pipes).
+# `gemini -p - -m <model> -o text --include-directories <root> < <prompt-path> 2>/dev/null`
+# therefore triggers a permission prompt every dispatch even when `Bash(gemini:*)`
+# is allowlisted, because the redirect tokens disqualify the simple-prefix match.
+#
+# This wrapper accepts positional arguments and performs the redirect inside
+# the script body, so the caller can allowlist a single non-redirect form:
+#
+#   Bash($HOME/.okstra/bin/okstra-gemini-exec.sh:*)
+#
+# Usage:
+#   okstra-gemini-exec.sh <project-root> <model-execution-value> <prompt-path>
+#
+# All three arguments are required and must be absolute paths or literal model
+# strings. The wrapper exits non-zero on any preflight failure.
+set -euo pipefail
+
+if [[ $# -ne 3 ]]; then
+  printf 'usage: %s <project-root> <model-execution-value> <prompt-path>\n' "$(basename "$0")" >&2
+  exit 64
+fi
+
+project_root="$1"
+model="$2"
+prompt_path="$3"
+
+if [[ -z "$project_root" || ! -d "$project_root" ]]; then
+  printf 'okstra-gemini-exec: project-root is missing or not a directory: %q\n' "$project_root" >&2
+  exit 65
+fi
+
+if [[ -z "$model" ]]; then
+  printf 'okstra-gemini-exec: model-execution-value is empty\n' >&2
+  exit 66
+fi
+
+if [[ -z "$prompt_path" || ! -f "$prompt_path" ]]; then
+  printf 'okstra-gemini-exec: prompt-path is missing or not a file: %q\n' "$prompt_path" >&2
+  exit 67
+fi
+
+if ! command -v gemini >/dev/null 2>&1; then
+  printf 'okstra-gemini-exec: gemini CLI is not installed on PATH\n' >&2
+  exit 127
+fi
+
+# stdin redirect and stderr suppression are intentionally inside the wrapper —
+# this is the entire reason this script exists. Gemini CLI has no `--cd` flag,
+# so workspace correctness is anchored via `--include-directories` plus the
+# Project Root referenced in the prompt body itself.
+exec gemini -p - -m "$model" -o text --include-directories "$project_root" < "$prompt_path" 2>/dev/null

package/runtime/bin/okstra-token-usage.py

@@ -0,0 +1,46 @@
+#!/usr/bin/env python3
+"""Collect token usage for an okstra run from agent session transcripts.
+
+The implementation lives in the ``okstra_token_usage`` package alongside
+this entry script. Public symbols are re-exported here so callers that
+load this file dynamically (e.g. tests using
+``importlib.util.spec_from_file_location``) keep working.
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from okstra_token_usage.cli import main  # noqa: E402
+# Re-exports for callers that access attributes off this module directly.
+from okstra_token_usage import (  # noqa: E402,F401
+    CLAUDE_PRICING,
+    CLAUDE_PROJECTS,
+    CODEX_PRICING,
+    CODEX_SESSIONS,
+    GEMINI_PRICING,
+    GEMINI_TMP,
+    claude_billable_equivalent,
+    claude_cost_usd,
+    claude_project_dir,
+    claude_session_totals,
+    codex_cost_usd,
+    codex_session_total,
+    collect,
+    find_claude_team_sessions,
+    find_codex_session,
+    find_gemini_session,
+    gemini_cost_usd,
+    gemini_session_total,
+    iter_jsonl,
+    na_block,
+    substitute_final_report,
+    usage_block,
+    utc_now,
+)
+
+
+if __name__ == "__main__":
+    sys.exit(main())