okstra 0.228.2 → 0.230.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (124) hide show
  1. package/README.md +1 -5
  2. package/dist/cli-registry.mjs +0 -18
  3. package/dist/cli-registry.mjs.map +1 -1
  4. package/dist/commands/lifecycle/doctor.mjs +0 -15
  5. package/dist/commands/lifecycle/doctor.mjs.map +1 -1
  6. package/dist/lib/skill-catalog.mjs +4 -4
  7. package/dist/lib/skill-catalog.mjs.map +1 -1
  8. package/docs/architecture/storage-model.md +179 -13
  9. package/docs/architecture.md +13 -14
  10. package/docs/contributor-change-matrix.md +5 -5
  11. package/docs/project-structure-overview.md +16 -21
  12. package/package.json +1 -2
  13. package/runtime/BUILD.json +2 -2
  14. package/runtime/bin/lib/okstra/interactive.sh +2 -1
  15. package/runtime/bin/okstra-provider-exec.py +53 -4
  16. package/runtime/prompts/duties/code-reviewer.json +5 -2
  17. package/runtime/prompts/launch.template.md +5 -5
  18. package/runtime/prompts/lead/convergence.md +4 -4
  19. package/runtime/prompts/lead/okstra-lead-contract.md +14 -13
  20. package/runtime/prompts/lead/phase-routing.md +1 -1
  21. package/runtime/prompts/lead/report-writer.md +3 -3
  22. package/runtime/prompts/lead/team-contract.md +3 -3
  23. package/runtime/python/okstra_ctl/agent/invocation.py +142 -5
  24. package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +31 -1
  25. package/runtime/python/okstra_ctl/cmux.py +4 -2
  26. package/runtime/python/okstra_ctl/code_review_census.py +194 -0
  27. package/runtime/python/okstra_ctl/code_review_coverage.py +18 -5
  28. package/runtime/python/okstra_ctl/code_review_scope.py +11 -7
  29. package/runtime/python/okstra_ctl/code_review_target.py +79 -25
  30. package/runtime/python/okstra_ctl/conformance.py +61 -0
  31. package/runtime/python/okstra_ctl/conformance_evidence.py +235 -0
  32. package/runtime/python/okstra_ctl/correction_round.py +19 -13
  33. package/runtime/python/okstra_ctl/dispatch_core.py +1 -1
  34. package/runtime/python/okstra_ctl/dispatch_state.py +1 -0
  35. package/runtime/python/okstra_ctl/execution_mutation_audit.py +100 -2
  36. package/runtime/python/okstra_ctl/generated_input.py +21 -0
  37. package/runtime/python/okstra_ctl/ids.py +1 -41
  38. package/runtime/python/okstra_ctl/initial_prompt_materialization.py +30 -0
  39. package/runtime/python/okstra_ctl/interactive_cli.py +5 -0
  40. package/runtime/python/okstra_ctl/locks.py +28 -1
  41. package/runtime/python/okstra_ctl/model_io/renderers.py +17 -1
  42. package/runtime/python/okstra_ctl/paths.py +84 -31
  43. package/runtime/python/okstra_ctl/phases/catalog.py +3 -0
  44. package/runtime/python/okstra_ctl/phases/change_impact_analysis/spec.md +2 -2
  45. package/runtime/python/okstra_ctl/phases/discussion/spec.md +63 -63
  46. package/runtime/python/okstra_ctl/phases/discussion/wizard.py +2 -11
  47. package/runtime/python/okstra_ctl/phases/error_analysis/report_assets/error-analysis-input.template.md +1 -1
  48. package/runtime/python/okstra_ctl/phases/error_analysis/spec.md +2 -2
  49. package/runtime/python/okstra_ctl/phases/feature_analysis/spec.md +1 -1
  50. package/runtime/python/okstra_ctl/phases/final_verification/profile.md +4 -4
  51. package/runtime/python/okstra_ctl/phases/final_verification/report_assets/final-verification-input.template.md +1 -1
  52. package/runtime/python/okstra_ctl/phases/final_verification/spec.md +4 -4
  53. package/runtime/python/okstra_ctl/phases/implementation/host-rules.md +1 -1
  54. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md +2 -2
  55. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-executor.md +1 -1
  56. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +4 -4
  57. package/runtime/python/okstra_ctl/phases/implementation/report_assets/implementation-input.template.md +1 -1
  58. package/runtime/python/okstra_ctl/phases/implementation/spec.md +4 -4
  59. package/runtime/python/okstra_ctl/phases/implementation_option_selection/spec.md +2 -2
  60. package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +11 -11
  61. package/runtime/python/okstra_ctl/phases/implementation_planning/plan_body.py +14 -0
  62. package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +4 -4
  63. package/runtime/python/okstra_ctl/phases/implementation_planning/report_assets/implementation-planning-input.template.md +1 -1
  64. package/runtime/python/okstra_ctl/phases/implementation_planning/spec.md +1 -1
  65. package/runtime/python/okstra_ctl/phases/project_analysis/spec.md +2 -2
  66. package/runtime/python/okstra_ctl/phases/release_handoff/entry.py +7 -3
  67. package/runtime/python/okstra_ctl/phases/release_handoff/report_assets/release-handoff-input.template.md +1 -1
  68. package/runtime/python/okstra_ctl/phases/release_handoff/spec.md +4 -4
  69. package/runtime/python/okstra_ctl/phases/technical_verification/spec.md +1 -1
  70. package/runtime/python/okstra_ctl/process_group.py +26 -3
  71. package/runtime/python/okstra_ctl/qa_commands.py +7 -2
  72. package/runtime/python/okstra_ctl/qa_procedures.py +60 -17
  73. package/runtime/python/okstra_ctl/recap.py +1 -2
  74. package/runtime/python/okstra_ctl/render.py +10 -2
  75. package/runtime/python/okstra_ctl/report_finalize.py +3 -3
  76. package/runtime/python/okstra_ctl/report_synthesis_packet.py +5 -0
  77. package/runtime/python/okstra_ctl/run.py +24 -20
  78. package/runtime/python/okstra_ctl/stage_command_commits.py +143 -0
  79. package/runtime/python/okstra_ctl/verification_capture.py +291 -0
  80. package/runtime/python/okstra_ctl/verification_conformance.py +182 -0
  81. package/runtime/python/okstra_ctl/verification_dispatch.py +130 -0
  82. package/runtime/python/okstra_ctl/verification_evidence.py +652 -0
  83. package/runtime/python/okstra_ctl/verification_generation.py +248 -0
  84. package/runtime/python/okstra_ctl/verification_input_ref.py +9 -0
  85. package/runtime/python/okstra_ctl/verification_input_types.py +23 -2
  86. package/runtime/python/okstra_ctl/verification_inputs.py +161 -23
  87. package/runtime/python/okstra_ctl/verification_invocation.py +139 -0
  88. package/runtime/python/okstra_ctl/verification_target.py +20 -5
  89. package/runtime/python/okstra_ctl/wizard/registry.py +2 -1
  90. package/runtime/python/okstra_ctl/wizard/render.py +2 -1
  91. package/runtime/python/okstra_ctl/wizard/sources.py +14 -3
  92. package/runtime/python/okstra_ctl/wizard/steps_identity.py +2 -1
  93. package/runtime/python/okstra_ctl/worker_runner.py +1 -1
  94. package/runtime/python/okstra_ctl/worktree_lock_cli.py +70 -17
  95. package/runtime/python/okstra_ctl/worktree_registry.py +4 -0
  96. package/runtime/skills/okstra-code-review/SKILL.md +84 -48
  97. package/runtime/skills/okstra-code-review/references/census-rules.md +10 -4
  98. package/runtime/skills/okstra-code-review/references/review-calibration.md +7 -4
  99. package/runtime/skills/okstra-explain-flow/SKILL.md +1 -1
  100. package/runtime/skills/okstra-run/SKILL.md +6 -6
  101. package/runtime/skills/okstra-schedule-gen/SKILL.md +3 -3
  102. package/runtime/skills/okstra-setup/SKILL.md +2 -3
  103. package/runtime/validators/validate-run.py +118 -52
  104. package/docs/cli.md +0 -1060
  105. package/docs/container.md +0 -100
  106. package/docs/follow-ups/2026-07-10-final-report-option-3.md +0 -51
  107. package/docs/performance-improvement-plan-v2.md +0 -369
  108. package/runtime/python/okstra_ctl/container.py +0 -702
  109. package/runtime/python/okstra_ctl/rollup.py +0 -241
  110. package/runtime/python/okstra_ctl/usage_report.py +0 -362
  111. package/runtime/skills/okstra-container-build/SKILL.md +0 -139
  112. package/runtime/skills/okstra-inspect/SKILL.md +0 -100
  113. package/runtime/skills/okstra-inspect/facets/cost.md +0 -84
  114. package/runtime/skills/okstra-inspect/facets/error-zip.md +0 -41
  115. package/runtime/skills/okstra-inspect/facets/errors.md +0 -69
  116. package/runtime/skills/okstra-inspect/facets/history.md +0 -86
  117. package/runtime/skills/okstra-inspect/facets/logs.md +0 -89
  118. package/runtime/skills/okstra-inspect/facets/recap.md +0 -167
  119. package/runtime/skills/okstra-inspect/facets/report.md +0 -57
  120. package/runtime/skills/okstra-inspect/facets/run-audit.md +0 -34
  121. package/runtime/skills/okstra-inspect/facets/status.md +0 -163
  122. package/runtime/skills/okstra-inspect/facets/time.md +0 -57
  123. package/runtime/skills/okstra-rollup/SKILL.md +0 -75
  124. package/runtime/skills/okstra-usage/SKILL.md +0 -71
@@ -1,241 +0,0 @@
1
- """Read-side cross-task roll-up for a task-group (or the whole project).
2
-
3
- 단일 task 집계기(time-report / error-report / recap)는 task-root 하나만 받는다.
4
- 이 모듈은 그 위에서 catalog 를 task-group 단위로 fan-out 해 task 별 run 수·소요
5
- 시간·에러 수·report 경로를 모으고, group 차원의 합계/분포를 deterministic 하게
6
- roll-up 한다. report 본문 종합(자연어 요약)은 LLM(skill)에 남긴다 — 여기서는
7
- report 경로만 노출한다. time-report 와 동일하게 raw ms 를 출력하고 HH:MM:SS
8
- 포맷·Markdown 표 렌더는 호출자(skill)에 위임한다.
9
- """
10
- from __future__ import annotations
11
-
12
- import argparse
13
- import json
14
- import sys
15
- from pathlib import Path
16
-
17
- from okstra_ctl import next_phase
18
- from okstra_ctl.error_log_core import glob_error_logs, parse_records
19
- from okstra_ctl.time_report import aggregate_time, load_runs
20
- from okstra_ctl.json_boundary import JsonBoundaryError, load_owned_object
21
- from okstra_ctl.fixed_text import line
22
- from okstra_project import (
23
- ResolverError,
24
- list_project_tasks,
25
- resolve_project_root,
26
- )
27
-
28
-
29
- _CRITIC_COUNTERS = (
30
- "gapsProposed",
31
- "gapsMerged",
32
- "gapsRejected",
33
- "gapsUnverified",
34
- )
35
-
36
-
37
- def _collect_critic(task_root: Path) -> dict:
38
- """task 의 모든 run 에서 커버리지 크리틱 결과를 합산.
39
-
40
- 크리틱은 opt-in 이라 대부분의 run 에 `config.critic` 이 없다. 그런 run 은
41
- `runsWithCritic` 에 세지 않는다 — "쓰지 않았다" 와 "썼는데 0건" 은 정책 판단이
42
- 갈리는 서로 다른 사실이다. 읽기 전용이므로 깨진 state 파일은 건너뛴다.
43
- """
44
- totals = {"runsWithCritic": 0} | {name: 0 for name in _CRITIC_COUNTERS}
45
- for state_path in sorted(task_root.glob("runs/*/state/convergence-*.json")):
46
- try:
47
- payload = load_owned_object(state_path, artifact="convergence state")
48
- except JsonBoundaryError:
49
- continue
50
- critic = (payload.get("config") or {}).get("critic")
51
- if not isinstance(critic, dict):
52
- continue
53
- totals["runsWithCritic"] += 1
54
- for name in _CRITIC_COUNTERS:
55
- value = critic.get(name)
56
- if isinstance(value, int) and not isinstance(value, bool):
57
- totals[name] += value
58
- return totals
59
-
60
-
61
- def _collect_task(entry: dict, project_root: Path) -> dict:
62
- """list_project_tasks entry → roll-up 한 줄. catalog 상태 필드 + time/error 측정.
63
-
64
- runCount 는 timeline 의 전체 run 수(usable durationMs 없는 run 도 포함)이고
65
- cpuSumMs/wallClockMs 는 durationMs 가 있는 run 만 반영하므로 0 일 수 있다.
66
- """
67
- task_root = Path(entry["_resolvedTaskRoot"])
68
- runs, _ = load_runs(task_root)
69
- time_agg = aggregate_time(runs, project_root)
70
- records, _ = parse_records(glob_error_logs(task_root))
71
- critic = _collect_critic(task_root)
72
- return {
73
- "criticRuns": critic["runsWithCritic"],
74
- "criticGapsProposed": critic["gapsProposed"],
75
- "criticGapsMerged": critic["gapsMerged"],
76
- "criticGapsRejected": critic["gapsRejected"],
77
- "criticGapsUnverified": critic["gapsUnverified"],
78
- "taskKey": entry.get("taskKey", ""),
79
- "taskGroup": entry.get("taskGroup", ""),
80
- "taskId": entry.get("taskId", ""),
81
- "taskType": entry.get("taskType", ""),
82
- "workCategory": entry.get("workCategory", "") or "unknown",
83
- "workStatus": entry.get("workStatus", "") or "unknown",
84
- "currentPhase": entry.get("currentPhase", ""),
85
- "currentPhaseState": entry.get("currentPhaseState", ""),
86
- "nextRecommendedPhase": next_phase.promote(
87
- entry.get("nextRecommendedPhase")
88
- ),
89
- "latestRunStatus": entry.get("latestRunStatus", ""),
90
- "updatedAt": entry.get("updatedAt", ""),
91
- "reportPath": entry.get("latestReportRecordPath", ""),
92
- "runCount": len(runs),
93
- "cpuSumMs": time_agg["grandTotal"]["cpuSumMs"],
94
- "wallClockMs": sum(r["wallClockMs"] for r in time_agg["perRunWallClock"]),
95
- "errorCount": len(records),
96
- }
97
-
98
-
99
- def _tally(tasks: list[dict], key: str) -> dict:
100
- """task 들의 한 필드를 값별 개수로. 빈 값은 'unknown' 으로 접는다."""
101
- counts: dict[str, int] = {}
102
- for task in tasks:
103
- bucket = task.get(key) or "unknown"
104
- counts[bucket] = counts.get(bucket, 0) + 1
105
- return dict(sorted(counts.items()))
106
-
107
-
108
- def _critic_totals(tasks: list[dict]) -> dict:
109
- return {
110
- "runsWithCritic": sum(t["criticRuns"] for t in tasks),
111
- "gapsProposed": sum(t["criticGapsProposed"] for t in tasks),
112
- "gapsMerged": sum(t["criticGapsMerged"] for t in tasks),
113
- "gapsRejected": sum(t["criticGapsRejected"] for t in tasks),
114
- "gapsUnverified": sum(t["criticGapsUnverified"] for t in tasks),
115
- }
116
-
117
-
118
- def build_rollup(project_root: Path, task_group: str | None) -> dict:
119
- entries = list_project_tasks(project_root, task_group=task_group or None)
120
- tasks = [_collect_task(e, project_root) for e in entries]
121
- totals = {
122
- "critic": _critic_totals(tasks),
123
- "runs": sum(t["runCount"] for t in tasks),
124
- "cpuSumMs": sum(t["cpuSumMs"] for t in tasks),
125
- "wallClockMs": sum(t["wallClockMs"] for t in tasks),
126
- "errors": sum(t["errorCount"] for t in tasks),
127
- "byWorkStatus": _tally(tasks, "workStatus"),
128
- "byWorkCategory": _tally(tasks, "workCategory"),
129
- "byCurrentPhase": _tally(tasks, "currentPhase"),
130
- "byTaskType": _tally(tasks, "taskType"),
131
- }
132
- return {
133
- "ok": True,
134
- "projectRoot": str(project_root),
135
- "taskGroup": task_group or None,
136
- "taskCount": len(tasks),
137
- "tasks": tasks,
138
- "totals": totals,
139
- }
140
-
141
-
142
- _CLI_EPILOG = r"""Usage:
143
- okstra rollup [--task-group <group>] [--project-root <dir>] [--cwd <dir>]
144
-
145
- Prints a JSON roll-up of every catalog task (optionally scoped to one
146
- task-group): per-task run count, elapsed time (raw ms), error count, and the
147
- latest report path, plus group-level totals and status/category/phase tallies.
148
- Resolving a task may record a finished implementation outcome in its task
149
- manifest, the task catalog, and consumers.jsonl; nothing else is written.
150
- With no --task-group it covers the whole project catalog. Time is raw ms; the
151
- caller formats HH:MM:SS and synthesizes the prose digest from the report files.
152
- """
153
-
154
-
155
- def main(argv: list[str] | None = None) -> int:
156
- parser = argparse.ArgumentParser(
157
- epilog=_CLI_EPILOG,
158
- formatter_class=argparse.RawDescriptionHelpFormatter,
159
- prog="okstra rollup",
160
- description="Roll up run results across a task-group's tasks (raw ms).")
161
- parser.add_argument("--task-group", default="",
162
- help="scope to this task-group (default: whole project catalog)")
163
- parser.add_argument("--project-root", default="")
164
- parser.add_argument("--cwd", default=".")
165
- parser.add_argument("--json", action="store_true", help="emit JSON (always on)")
166
- parser.add_argument("--text", action="store_true", help="emit fixed text fields")
167
- args = parser.parse_args(argv)
168
-
169
- try:
170
- project_root = Path(
171
- resolve_project_root(explicit_root=args.project_root, cwd=args.cwd)
172
- ).resolve()
173
- except ResolverError as exc:
174
- payload = {"ok": False, "stage": "resolve", "reason": str(exc)}
175
- print(render_rollup_text(payload) if args.text else json.dumps(payload))
176
- return 2
177
-
178
- result = build_rollup(project_root, args.task_group)
179
- print(
180
- render_rollup_text(result)
181
- if args.text
182
- else json.dumps(result, ensure_ascii=False, indent=2)
183
- )
184
- return 0
185
-
186
-
187
- def render_rollup_text(payload: dict) -> str:
188
- """rollup 모델 표면에 승인된 필드만 고정 순서로 투영한다."""
189
- rows = ["Okstra rollup\n"]
190
- rows.append(line("Status", "ready" if payload.get("ok") else "error"))
191
- rows.append(line("Task group", payload.get("taskGroup") or "all"))
192
- rows.append(line("Task count", payload.get("taskCount")))
193
- totals = payload.get("totals") if isinstance(payload.get("totals"), dict) else {}
194
- rows.append(line("Total runs", totals.get("runs")))
195
- rows.append(line("Total errors", totals.get("errors")))
196
- rows.append(line("CPU sum ms", totals.get("cpuSumMs")))
197
- rows.append(line("Wall clock ms", totals.get("wallClockMs")))
198
- rows.extend(_distribution_lines("Work status", totals.get("byWorkStatus")))
199
- rows.extend(_distribution_lines("Work category", totals.get("byWorkCategory")))
200
- rows.extend(_distribution_lines("Current phase", totals.get("byCurrentPhase")))
201
- rows.extend(_distribution_lines("Task type", totals.get("byTaskType")))
202
- tasks = payload.get("tasks") if isinstance(payload.get("tasks"), list) else []
203
- for index, task in enumerate(tasks, 1):
204
- if not isinstance(task, dict):
205
- continue
206
- rows.extend(_task_lines(index, task))
207
- if not payload.get("ok"):
208
- rows.append(line("Failure stage", payload.get("stage")))
209
- rows.append(line("Failure reason", payload.get("reason")))
210
- return "".join(rows)
211
-
212
-
213
- def _distribution_lines(title: str, raw_values: object) -> list[str]:
214
- values = raw_values if isinstance(raw_values, dict) else {}
215
- rows: list[str] = []
216
- for index, (name, count) in enumerate(sorted(values.items()), 1):
217
- rows.append(line(f"{title} {index} name", name))
218
- rows.append(line(f"{title} {index} count", count))
219
- return rows
220
-
221
-
222
- def _task_lines(index: int, task: dict) -> list[str]:
223
- fields = (
224
- ("key", "taskKey"), ("type", "taskType"), ("category", "workCategory"),
225
- ("status", "workStatus"), ("phase", "currentPhase"),
226
- ("phase state", "currentPhaseState"), ("latest run status", "latestRunStatus"),
227
- ("updated at", "updatedAt"), ("runs", "runCount"),
228
- ("CPU sum ms", "cpuSumMs"), ("wall clock ms", "wallClockMs"),
229
- ("errors", "errorCount"), ("report path", "reportPath"),
230
- )
231
- rows = [line(f"Task {index} {label}", task.get(key)) for label, key in fields]
232
- next_phase = task.get("nextRecommendedPhase")
233
- values = next_phase if isinstance(next_phase, dict) else {}
234
- for label, key in (("next phase", "phase"), ("next phase status", "status"),
235
- ("next phase rationale", "rationale")):
236
- rows.append(line(f"Task {index} {label}", values.get(key)))
237
- return rows
238
-
239
-
240
- if __name__ == "__main__":
241
- raise SystemExit(main(sys.argv[1:]))
@@ -1,362 +0,0 @@
1
- from __future__ import annotations
2
-
3
- import argparse
4
- import datetime as dt
5
- import json
6
- import math
7
- import sys
8
- from pathlib import Path
9
- from typing import Any
10
-
11
- from okstra_ctl.time_report import (
12
- _duration_ms,
13
- _read_state,
14
- wall_clock_ms,
15
- load_runs,
16
- )
17
- from okstra_ctl.json_boundary import load_owned_object
18
- from okstra_ctl.fixed_text import line
19
- from okstra_project import ResolverError, list_project_tasks, resolve_project_root
20
- from okstra_token_usage.blocks import accounting_workers, normalize_usage_block, usage_blocks
21
-
22
- UTC = dt.timezone.utc
23
- UNAVAILABLE_KEYS = (
24
- "invalidRunTimestamp",
25
- "teamStateMissing",
26
- "usageSummaryMissing",
27
- "durationMissing",
28
- )
29
-
30
-
31
- def _iso_z(value: dt.datetime) -> str:
32
- return value.astimezone(UTC).isoformat().replace("+00:00", "Z")
33
-
34
-
35
- def _parse_timestamp(value: Any) -> dt.datetime | None:
36
- if not isinstance(value, str) or not value:
37
- return None
38
- try:
39
- parsed = dt.datetime.fromisoformat(value.replace("Z", "+00:00"))
40
- if parsed.tzinfo is None:
41
- parsed = parsed.replace(tzinfo=UTC)
42
- return parsed.astimezone(UTC)
43
- except (OverflowError, ValueError):
44
- return None
45
-
46
-
47
- def _project_id(project_root: Path) -> str:
48
- try:
49
- data = load_owned_object(
50
- project_root / ".okstra" / "project.json", artifact="project config"
51
- )
52
- except (OSError, ValueError):
53
- return ""
54
- return str(data.get("projectId") or "") if isinstance(data, dict) else ""
55
-
56
-
57
- def _int_value(value: Any) -> int:
58
- try:
59
- return int(value or 0)
60
- except (OverflowError, TypeError, ValueError):
61
- return 0
62
-
63
-
64
- def _float_value(value: Any) -> float:
65
- try:
66
- result = float(value or 0)
67
- except (OverflowError, TypeError, ValueError):
68
- return 0.0
69
- return result if math.isfinite(result) else 0.0
70
-
71
-
72
- def _usage_block(value: Any) -> dict:
73
- if not isinstance(value, dict):
74
- return {}
75
- block = {"source": value["source"]} if "source" in value else {}
76
- if "durationMs" in value:
77
- block["durationMs"] = _int_value(value["durationMs"])
78
- for key in ("startedAt", "endedAt"):
79
- if isinstance(value.get(key), str):
80
- block[key] = value[key]
81
- return block
82
-
83
-
84
- def _usage_blocks(state: dict) -> tuple[dict, list[dict]]:
85
- worker_entries = accounting_workers(state)
86
- return _usage_block(state.get("leadUsage")), [
87
- _usage_block(worker.get("usage"))
88
- for worker in worker_entries
89
- if isinstance(worker, dict)
90
- ]
91
-
92
-
93
- def _wall_clock_from_blocks(lead: dict, workers: list[dict]) -> int:
94
- state = {
95
- "leadUsage": lead,
96
- "workers": [{"usage": usage} for usage in workers],
97
- }
98
- try:
99
- return wall_clock_ms(state)
100
- except TypeError:
101
- return 0
102
-
103
-
104
- def _run_metrics(run: dict, project_root: Path) -> tuple[dict | None, str | None]:
105
- state = _read_state(project_root, str(run.get("teamStatePath") or ""))
106
- if state is None:
107
- return None, "teamStateMissing"
108
- summary = state.get("usageSummary")
109
- if not isinstance(summary, dict) or _int_value(summary.get("grandTotalTokens")) <= 0:
110
- return None, "usageSummaryMissing"
111
- lead, workers = _usage_blocks(state)
112
- durations = [_duration_ms(lead), *(_duration_ms(worker) for worker in workers)]
113
- positive_durations = [duration for duration in durations if duration > 0]
114
- if not positive_durations:
115
- return None, "durationMissing"
116
- costs = summary.get("estimatedCostUsd")
117
- cost = costs.get("grandTotal", 0) if isinstance(costs, dict) else 0
118
- unmatched = summary.get("unmatchedModels")
119
- unmatched_models = unmatched if isinstance(unmatched, list) else []
120
- original_blocks = usage_blocks(state)
121
- normalized = [normalize_usage_block(block) for block in original_blocks]
122
- cache_adjustment = sum(_int_value(block.get("totalTokens")) for block in original_blocks)
123
- cache_adjustment -= sum(_int_value(block.get("totalTokens")) for block in normalized)
124
- return {
125
- "rawTokens": _int_value(summary.get("grandTotalTokens")) - cache_adjustment,
126
- "reportedRawTokens": _int_value(summary.get("grandTotalTokens")),
127
- "legacyCacheReadAdjustmentTokens": cache_adjustment,
128
- "cacheReadTokens": sum(_int_value(block.get("cacheReadTokens")) for block in normalized),
129
- "billableTokens": _int_value(summary.get("grandBillableEquivalentTokens")),
130
- "costUsd": _float_value(cost),
131
- "cpuSumMs": sum(positive_durations),
132
- "wallClockMs": _wall_clock_from_blocks(lead, workers),
133
- "unmatchedModels": [
134
- model for model in unmatched_models if isinstance(model, str) and model
135
- ],
136
- }, None
137
-
138
-
139
- def _new_bucket(task_type: str, first_run_at: dt.datetime) -> dict:
140
- return {
141
- "taskType": task_type,
142
- "firstRunAt": _iso_z(first_run_at),
143
- "runs": 0,
144
- "collectedRuns": 0,
145
- "rawTokens": 0,
146
- "reportedRawTokens": 0,
147
- "legacyCacheReadAdjustmentTokens": 0,
148
- "cacheReadTokens": 0,
149
- "billableTokens": 0,
150
- "costUsd": 0.0,
151
- "cpuSumMs": 0,
152
- "wallClockMs": 0,
153
- }
154
-
155
-
156
- def _collect_usage(
157
- project_root: Path,
158
- start_at: dt.datetime,
159
- end_at: dt.datetime,
160
- unavailable: dict[str, int],
161
- warnings: dict[str, int],
162
- ) -> tuple[dict[str, dict], set[str], int, int, list[dict]]:
163
- from okstra_ctl.usage_identity import identity_rows_from_state
164
-
165
- buckets: dict[str, dict] = {}
166
- unmatched_models: set[str] = set()
167
- identity_rows: list[dict] = []
168
- seen_identity: set[str] = set()
169
- total_runs = 0
170
- collected_runs = 0
171
- for entry in list_project_tasks(project_root):
172
- runs, timeline_warning = load_runs(Path(entry["_resolvedTaskRoot"]))
173
- warnings["missingOrInvalidTimelines"] += int(timeline_warning)
174
- for run in runs:
175
- run_at = _parse_timestamp(run.get("runTimestamp") if isinstance(run, dict) else None)
176
- if run_at is None:
177
- unavailable["invalidRunTimestamp"] += 1
178
- continue
179
- if run_at < start_at or run_at > end_at:
180
- continue
181
- task_type = str(run.get("taskType") or "unknown")
182
- bucket = buckets.setdefault(task_type, _new_bucket(task_type, run_at))
183
- run_at_text = _iso_z(run_at)
184
- if run_at_text < bucket["firstRunAt"]:
185
- bucket["firstRunAt"] = run_at_text
186
- total_runs += 1
187
- bucket["runs"] += 1
188
- metrics, reason = _run_metrics(run, project_root)
189
- state = _read_state(project_root, str(run.get("teamStatePath") or ""))
190
- for row in identity_rows_from_state(state):
191
- key = str(row.get("roleExecutionRef") or row.get("executionLabel"))
192
- if key in seen_identity:
193
- continue
194
- seen_identity.add(key)
195
- identity_rows.append(row)
196
- if reason is not None:
197
- unavailable[reason] += 1
198
- continue
199
- collected_runs += 1
200
- bucket["collectedRuns"] += 1
201
- for key in ("rawTokens", "reportedRawTokens", "legacyCacheReadAdjustmentTokens",
202
- "cacheReadTokens", "billableTokens", "cpuSumMs", "wallClockMs"):
203
- bucket[key] += metrics[key]
204
- bucket["costUsd"] += metrics["costUsd"]
205
- unmatched_models.update(metrics["unmatchedModels"])
206
- return buckets, unmatched_models, total_runs, collected_runs, identity_rows
207
-
208
-
209
- def build_usage_report(project_root: Path, days: int, now: dt.datetime) -> dict:
210
- if days <= 0:
211
- raise ValueError("days must be a positive integer")
212
- project_root = Path(project_root).resolve()
213
- end_at = now.astimezone(UTC)
214
- try:
215
- start_at = end_at - dt.timedelta(days=days)
216
- except OverflowError:
217
- start_at = dt.datetime.min.replace(tzinfo=UTC)
218
- unavailable = {key: 0 for key in UNAVAILABLE_KEYS}
219
- warnings = {"missingOrInvalidTimelines": 0}
220
- buckets, unmatched_models, total_runs, collected_runs, identity_rows = _collect_usage(
221
- project_root, start_at, end_at, unavailable, warnings
222
- )
223
-
224
- rows = sorted(buckets.values(), key=lambda row: row["firstRunAt"])
225
- for row in rows:
226
- row["costUsd"] = round(_float_value(row["costUsd"]), 4)
227
- row["collectionRate"] = (
228
- row["collectedRuns"] / row["runs"] if row["runs"] else 0.0
229
- )
230
- totals = {
231
- "runs": total_runs,
232
- "collectedRuns": collected_runs,
233
- "rawTokens": sum(row["rawTokens"] for row in rows),
234
- "reportedRawTokens": sum(row["reportedRawTokens"] for row in rows),
235
- "legacyCacheReadAdjustmentTokens": sum(row["legacyCacheReadAdjustmentTokens"] for row in rows),
236
- "cacheReadTokens": sum(row["cacheReadTokens"] for row in rows),
237
- "billableTokens": sum(row["billableTokens"] for row in rows),
238
- "costUsd": round(_float_value(sum(row["costUsd"] for row in rows)), 4),
239
- "cpuSumMs": sum(row["cpuSumMs"] for row in rows),
240
- "wallClockMs": sum(row["wallClockMs"] for row in rows),
241
- }
242
- return {
243
- "ok": True,
244
- "projectId": _project_id(project_root),
245
- "range": {"days": days, "startAt": _iso_z(start_at), "endAt": _iso_z(end_at)},
246
- "runs": {
247
- "total": total_runs,
248
- "collected": collected_runs,
249
- "collectionRate": collected_runs / total_runs if total_runs else 0.0,
250
- },
251
- "byTaskType": rows,
252
- "totals": totals,
253
- "unavailable": unavailable,
254
- "warnings": warnings,
255
- "unmatchedModels": sorted(unmatched_models),
256
- "identityRows": identity_rows,
257
- }
258
-
259
-
260
- def utc_now() -> dt.datetime:
261
- return dt.datetime.now(UTC)
262
-
263
-
264
- def _positive_days(value: str) -> int:
265
- try:
266
- days = int(value)
267
- except ValueError as exc:
268
- raise argparse.ArgumentTypeError("--days must be a positive integer") from exc
269
- if days <= 0:
270
- raise argparse.ArgumentTypeError("--days must be a positive integer")
271
- return days
272
-
273
-
274
- _CLI_EPILOG = r"""Usage:
275
- okstra usage-report [--days <positive-int>] [--project-root <dir>] [--cwd <dir>] [--json]
276
-
277
- Prints JSON containing run coverage, raw and billable-equivalent
278
- tokens, known USD cost, CPU-sum time, and wall-clock time grouped by task type.
279
- Resolving a task may record a finished implementation outcome in its task
280
- manifest, the task catalog, and consumers.jsonl; nothing else is written.
281
- The default window is the current project's last 30 days.
282
- """
283
-
284
-
285
- def main(argv: list[str] | None = None) -> int:
286
- parser = argparse.ArgumentParser(
287
- epilog=_CLI_EPILOG,
288
- formatter_class=argparse.RawDescriptionHelpFormatter,
289
- prog="okstra usage-report",
290
- description="Aggregate recent project usage by task type.",
291
- )
292
- parser.add_argument("--days", type=_positive_days, default=30)
293
- parser.add_argument("--project-root", default="")
294
- parser.add_argument("--cwd", default=".")
295
- parser.add_argument("--json", action="store_true", help="emit JSON (always on)")
296
- parser.add_argument("--text", action="store_true", help="emit fixed text fields")
297
- args = parser.parse_args(argv)
298
- try:
299
- project_root = Path(
300
- resolve_project_root(explicit_root=args.project_root, cwd=args.cwd)
301
- ).resolve()
302
- except ResolverError as exc:
303
- payload = {"ok": False, "stage": "resolve", "reason": str(exc)}
304
- print(render_usage_text(payload) if args.text else json.dumps(payload))
305
- return 2
306
- result = build_usage_report(project_root, args.days, utc_now())
307
- print(
308
- render_usage_text(result)
309
- if args.text
310
- else json.dumps(result, ensure_ascii=False, indent=2)
311
- )
312
- return 0
313
-
314
-
315
- def render_usage_text(payload: dict) -> str:
316
- """usage 모델 표면에 승인된 집계만 고정 순서로 투영한다."""
317
- rows = ["Okstra usage\n"]
318
- rows.append(line("Status", "ready" if payload.get("ok") else "error"))
319
- rows.append(line("Project ID", payload.get("projectId")))
320
- period = payload.get("range") if isinstance(payload.get("range"), dict) else {}
321
- rows.append(line("Range days", period.get("days")))
322
- runs = payload.get("runs") if isinstance(payload.get("runs"), dict) else {}
323
- rows.append(line("Runs total", runs.get("total")))
324
- rows.append(line("Runs collected", runs.get("collected")))
325
- rows.append(line("Runs collection rate", runs.get("collectionRate")))
326
- task_types = payload.get("byTaskType") if isinstance(payload.get("byTaskType"), list) else []
327
- for index, item in enumerate(task_types, 1):
328
- if not isinstance(item, dict):
329
- continue
330
- rows.append(line(f"Task type {index} name", item.get("taskType")))
331
- rows.append(line(f"Task type {index} runs", item.get("runs")))
332
- rows.append(line(f"Task type {index} collected runs", item.get("collectedRuns")))
333
- rows.append(line(f"Task type {index} collection rate", item.get("collectionRate")))
334
- rows.append(line(f"Task type {index} raw tokens", item.get("rawTokens")))
335
- rows.append(line(f"Task type {index} billable tokens", item.get("billableTokens")))
336
- rows.append(line(f"Task type {index} cost USD", item.get("costUsd")))
337
- rows.append(line(f"Task type {index} CPU sum ms", item.get("cpuSumMs")))
338
- rows.append(line(f"Task type {index} wall clock ms", item.get("wallClockMs")))
339
- totals = payload.get("totals") if isinstance(payload.get("totals"), dict) else {}
340
- for label, key in (("Raw tokens", "rawTokens"), ("Billable tokens", "billableTokens"),
341
- ("Reported raw tokens", "reportedRawTokens"),
342
- ("Legacy cache read adjustment tokens", "legacyCacheReadAdjustmentTokens"),
343
- ("Cache read tokens", "cacheReadTokens"),
344
- ("Cost USD", "costUsd"), ("CPU sum ms", "cpuSumMs"),
345
- ("Wall clock ms", "wallClockMs")):
346
- rows.append(line(label, totals.get(key)))
347
- for prefix, key in (("Unavailable", "unavailable"), ("Warning", "warnings")):
348
- values = payload.get(key) if isinstance(payload.get(key), dict) else {}
349
- for index, (name, count) in enumerate(sorted(values.items()), 1):
350
- rows.append(line(f"{prefix} {index} reason", name))
351
- rows.append(line(f"{prefix} {index} count", count))
352
- models = payload.get("unmatchedModels") if isinstance(payload.get("unmatchedModels"), list) else []
353
- for index, model in enumerate(models, 1):
354
- rows.append(line(f"Unmatched model {index} name", model))
355
- if not payload.get("ok"):
356
- rows.append(line("Failure stage", payload.get("stage")))
357
- rows.append(line("Failure reason", payload.get("reason")))
358
- return "".join(rows)
359
-
360
-
361
- if __name__ == "__main__":
362
- raise SystemExit(main(sys.argv[1:]))