mirror of
https://github.com/Kaelio/ktx.git
synced 2026-06-07 07:55:13 +02:00
494618ab14
* feat: add codex sdk runner foundation * feat: parse codex runtime events * feat: expose codex runtime mcp tools * feat: add codex llm runtime * feat: wire codex llm backend * test: avoid Array.fromAsync in codex runner test * docs: document codex llm backend * fix: tighten codex runtime config ownership * fix: use codex sdk env and thread options * fix: parse codex sdk event shapes * test: add codex backend live smoke * docs: clarify codex backend isolation * fix: drive codex loop metrics from mcp events * fix: enforce codex local step budget * docs: disclose codex isolation limits * fix: count all codex agent steps and stream step callbacks live The agent-loop step budget only counted completed mcp_tool_call items, so built-in command_execution steps (which the public Codex SDK/CLI surface can still expose) never decremented the budget, letting ingest/reconciliation run past stepBudget until Codex stopped on its own. onStepFinish was also replayed only after the whole stream drained, so live work_unit_step / reconciliation progress appeared stuck until the Codex process exited. collectEvents is now the single live step accumulator: it counts every completed agent-action item via a shared isCompletedAgentStep predicate (command_execution, mcp_tool_call, file_change, web_search), fires onStepFinish as each step completes, and enforces the budget on that broader count. A no-tool turn still counts as one step. toolFailures stays MCP-specific, since a non-zero command exit is normal agent exploration, not a loop failure. * test: align ingest llm-guard assertions with codex backend The skip-llm ingest guard message now lists codex as a valid backend and mentions a Claude Code/Codex session plus a codex setup hint, but this slow suite test still asserted the pre-codex wording. Update it to match the production message (already covered by the local-bundle-runtime unit test) and add the codex setup-line assertion. * fix: treat codex error:null tool calls as success The Codex SDK serializes error: null on successful mcp_tool_call items, so the failure check (item.error !== undefined) flagged every successful tool call as failed with the empty-payload default "Codex turn failed". This killed every ingest work unit under the codex backend before it could produce a patch. Key on status === 'failed' (authoritative, always set) and only treat a populated error object as a failure. Add a regression test built from a verbatim real-SDK event capture. * fix: default codex backend to gpt-5.5 and report real probe errors The previous default gpt-5.3-codex is an API-key-only model that the OpenAI API rejects under ChatGPT-account (subscription) auth, so codex status/setup failed with a misleading "authentication is not usable" message even though auth was fine. - Default codex model is now gpt-5.5 (works on both subscription and API-key auth); the curated setup picker offers gpt-5.5 / gpt-5.4 / gpt-5.4-mini and keeps free-form entry for account-specific ids (e.g. gpt-5.3-codex-spark). - runCodexAuthProbe now distinguishes "model not available" from an auth failure and surfaces the real API error: collectEvents retains stream events when the SDK throws on a non-zero exit, and the API error JSON envelope is unwrapped to its human-readable message. - The Codex isolation warning now renders inside the clack setup frame. - Docs updated to gpt-5.5 with a note that *-codex ids require API-key auth. * fix: require llm.models.default in status and match codex probe remediation Status reported a project ready when a non-none LLM backend was configured without llm.models.default, but the runtime (resolveModelSlots) hard-requires it, so ingest/scan/memory threw after `ktx status` said the project was usable. buildLlmStatus now fails for any non-none backend missing models.default and no longer invents a fallback model for claude-code/codex. Codex probe failures now carry a category-matched fix: a model-access failure steers the user at llm.models.default instead of the auth/install remediation. runCodexAuthProbe returns the fix and status consumes it; the message stays self-sufficient so setup output is unchanged. Docs: README now lists the codex backend and local Codex auth; ktx-setup.mdx states --llm-model only accepts codex/default or gpt-*/codex-* ids. Repaired four doctor fixtures that configured a backend without models.default (the now-correctly-blocked config) and added coverage for the new behavior.
99 lines
3.9 KiB
Text
99 lines
3.9 KiB
Text
---
|
|
title: "ktx status"
|
|
description: "Check ktx setup and project readiness."
|
|
---
|
|
|
|
Run the **ktx** readiness doctor. Inside a **ktx** project, this checks setup,
|
|
project configuration, semantic search, query history, connections, and related
|
|
diagnostics. Outside a project, it checks local CLI setup readiness so you know
|
|
whether `ktx setup` can run.
|
|
|
|
## Command signature
|
|
|
|
```bash
|
|
ktx status [options]
|
|
```
|
|
|
|
## Options
|
|
|
|
| Flag | Description | Default |
|
|
|------|-------------|---------|
|
|
| `--json` | Print JSON output | `false` |
|
|
| `-v`, `--verbose` | Show every check, including passing ones | `false` |
|
|
| `--validate` | Only validate the `ktx.yaml` schema; skip readiness checks | `false` |
|
|
| `--fast` | Skip checks that require external communication (query-history readiness probes, Claude Code auth probe, and Codex auth probe) | `false` |
|
|
| `--no-input` | Disable interactive terminal input | - |
|
|
|
|
## Examples
|
|
|
|
```bash
|
|
# Show project status
|
|
ktx status
|
|
|
|
# Get status as JSON without interactive input
|
|
ktx status --json --no-input
|
|
|
|
# Show all checks, not only warnings and failures
|
|
ktx status --verbose
|
|
|
|
# Validate ktx.yaml without running readiness checks
|
|
ktx status --validate
|
|
|
|
# Skip slow probes (query-history readiness, Claude Code auth, Codex auth)
|
|
ktx status --fast
|
|
|
|
# Check a project from another directory
|
|
ktx status --project-dir ./analytics
|
|
```
|
|
|
|
## Output
|
|
|
|
`ktx status` prints grouped doctor checks. Agents should use
|
|
`ktx status --json --no-input` when they need to branch on readiness state.
|
|
|
|
For `llm.provider.backend: claude-code`, `ktx status` checks that the local
|
|
Claude Code session is usable. If auth fails, run the Claude Code CLI login
|
|
flow, then rerun `ktx status`. Use `--fast` to skip this probe (useful in CI
|
|
or offline contexts); skipped checks render as `-` and carry
|
|
`"status": "skipped"` in JSON output.
|
|
|
|
For `llm.provider.backend: codex`, `ktx status` runs a minimal non-interactive
|
|
Codex request. If the probe fails, authenticate Codex locally with the Codex CLI
|
|
and verify the Codex CLI installation.
|
|
|
|
When `llm.provider.backend: codex` is configured, `ktx status` also prints a
|
|
warning when the installed public Codex SDK and CLI surface cannot prove full
|
|
Claude-Code-style isolation. The warning does not block authenticated Codex
|
|
usage, but it marks the project status as partial so you can make an explicit
|
|
runtime-isolation decision.
|
|
|
|
A `Local data` section summarises what the project has accumulated locally:
|
|
ingest run counts, last completed timestamp per connection, knowledge page
|
|
counts by scope, semantic-layer source and dictionary value counts, and the
|
|
on-disk size of `.ktx/db.sqlite`, `.ktx/cache/`, `raw-sources/`, `wiki/global/`,
|
|
and `semantic-layer/`. These are read from `.ktx/db.sqlite` and local file
|
|
stats, and are always shown (they do not require external communication).
|
|
|
|
```json
|
|
{
|
|
"title": "ktx project doctor",
|
|
"checks": [
|
|
{
|
|
"id": "project-config",
|
|
"label": "Project config",
|
|
"status": "pass",
|
|
"detail": "warehouse"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
## Common errors
|
|
|
|
| Error | Cause | Recovery |
|
|
|-------|-------|----------|
|
|
| No **ktx** project found | Current directory has no `ktx.yaml` and `KTX_PROJECT_DIR` is unset | `ktx status` runs setup checks; run from a **ktx** project or set `KTX_PROJECT_DIR` for project checks |
|
|
| Project config check fails | The project directory is missing or has an invalid `ktx.yaml` | Run `ktx setup` to resume setup |
|
|
| Schema validation fails | `ktx.yaml` does not match the current config schema | Run `ktx status --validate --json` for structured issue details, then edit `ktx.yaml` or rerun `ktx setup` |
|
|
| Semantic search check warns | Embeddings are not configured or the provider probe failed | Run `ktx setup` or inspect the check's `fix` field in JSON output |
|
|
| Query history check warns | A database has query history enabled but the warehouse prerequisites are missing | Fix the warehouse extension, grants, or history access, then rerun `ktx status` |
|