ktx/docs-site
Andrey Avtomonov 21744fc520
feat(cli): profile ingest runs and split model vs tool time (#249)
* feat(cli): profile ingest runs to find where wall-clock time goes

Add opt-in profiling for `ktx ingest`. Each timed phase, work unit, and
agent loop now records durationMs / step count / token usage in the
trace, and a post-run aggregator rolls them up into a "where did the
time go" report printed to stderr.

Enable per run with KTX_PROFILE_INGEST (1/true -> human table, json ->
raw structured profile) or persistently via `ingest.profile` in
ktx.yaml. The json form emits raw milliseconds, token counts, and a
summary.headline one-line diagnosis so coding agents can parse it
directly; json wins when both env and config request profiling.

- runtime-port: RunLoopMetrics (totalMs, usage, stepCount,
  stepBoundariesMs) plus onMetrics callbacks on text/object generation
- ai-sdk + claude-code runtimes: capture per-loop timing and token usage
- work-unit-executor and stages 3/4: thread metrics into trace events
- ingest-bundle.runner: time worktree / triage / clustering / index /
  reconcile / squash phases and emit the profile in a finally block
  (best-effort; never affects the run outcome)
- ingest-profile: new trace+transcript aggregator with table/json formatters
- config: ingest.profile flag; docs: profiling section in ktx-ingest.mdx

* fix(cli): flush tool-call logs before reading ingest profile

Tool transcripts are appended fire-and-forget so the agent hot path never
blocks on logging. The ingest profiler read them before the writes settled,
so per-work-unit toolMs (and the model-vs-tool split derived from it) could
be incomplete. Track in-flight appends and expose flushToolCallLogs() —
bounded by a timeout so it can never hang — and flush before the profiler
reads the transcript.
2026-06-01 15:49:17 +02:00
..
app feat: README architecture diagrams + React Flow diagram studio (#245) 2026-06-01 12:06:27 +02:00
components feat: README architecture diagrams + React Flow diagram studio (#245) 2026-06-01 12:06:27 +02:00
content/docs feat(cli): profile ingest runs and split model vs tool time (#249) 2026-06-01 15:49:17 +02:00
lib docs: add ktx skills.sh setup skill (#227) 2026-05-28 12:28:10 +02:00
public feat: README architecture diagrams + React Flow diagram studio (#245) 2026-06-01 12:06:27 +02:00
tests docs: standardize ktx naming (#187) 2026-05-20 17:33:38 +02:00
.gitignore chore: configure docs site deployment 2026-05-11 17:57:55 +02:00
next-env.d.ts docs(quickstart): redesign demo-warehouse callout with sticker icons (#202) 2026-05-21 16:04:58 +02:00
next.config.mjs Route ktx stars dashboard 2026-05-28 13:00:49 +02:00
package.json feat: README architecture diagrams + React Flow diagram studio (#245) 2026-06-01 12:06:27 +02:00
postcss.config.mjs chore: move docs site workspace 2026-05-11 16:53:42 +02:00
proxy.ts docs: rewrite Semantic Querying concept with imperative-vs-declarative diagram (#156) 2026-05-19 23:41:29 +02:00
source.config.ts docs: revamp quickstart and tighten code-block styling (#135) 2026-05-18 19:22:19 +02:00
tsconfig.json feat: merge ingest and scan 2026-05-14 01:43:06 +02:00