@kodax-ai/kodax 0.7.59 → 0.7.61

package/CHANGELOG.md

@@ -6,6 +6,64 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.7.61] - 2026-07-06
+
+> Scope note: a token-efficiency + workflow-reliability release. **FEATURE_251** adds command-aware
+> in-tool output compression (an rtk-style Token Killer port) inside KodaX's own `bash` tool layer,
+> so a noisy `git diff` / test run / package-install / docker-build no longer spends thousands of
+> context tokens — the compressed body is what context accounting actually counts, and every lossy
+> summary keeps a raw-recovery path. **FEATURE_252** lands the deterministic half of workflow-quality
+> preflight: a pre-start AST/dataflow lint that hard-fails weak-model authoring contract bugs before
+> a workflow can run. Both are deterministic (no prompt change, no LLM eval). The release also fixes a
+> workflow-start crash: `typescript` is now a runtime dependency of `@kodax-ai/agent` because the
+> quality lint uses the TypeScript compiler API on the workflow hot path. No public runtime type is removed.
+
+### Added
+
+- **Tool-output semantic compression — command-aware in-tool Token Killer (FEATURE_251, ADR-050).** A new `packages/coding/src/tools/output-filters/` module compresses bash `stdout`/`stderr` **body** after decode, before the `Command:` / `Exit:` header is assembled, at the single `bash.ts` close-handler integration point (so both the SA and AMA dispatch paths are covered by one change). It ships a lossless generic layer (ANSI strip), compiled stateful filters (`git-diff`, `git-log`, `git-status`, `test-runner` failure-focus, `lint` diagnostic grouping, `json-output` / NDJSON structural summary), and a built-in declarative long-tail table (package-manager / docker / infra CLI progress). Hard constraints: the `Command:` / `Exit:` header is preserved verbatim (FEATURE_185 hits-ledger depends on it); the generic layer is lossless-by-construction with `never_worse` as a size-only backstop; content-signature detection is preferred over command-name matching (robust to compound commands and pipes); and every lossy filter (`lossiness: tail | whole`) first persists the raw decoded body via `persistToolOutput` and appends a recovery hint, falling back to the raw body + existing tail-truncation if the persist fails. `background` / `timeout` / `abort` paths do not reach the completion assembly and are naturally excluded. Isolated Layer-1 measurements (`context-savings.test.ts`) show ~66–99% body-token reduction on high-noise commands (e.g. a 120-file `git diff` 9,960 → 1,344 tokens; a `terraform apply` progress stream 10,617 → 59). Deterministic code — no prompt change, no FEATURE_104 eval. Human test guide: `docs/test-guides/FEATURE_251_v0.7.61_TEST_GUIDE.md`.
+- **Deterministic workflow-quality preflight lint (FEATURE_252).** A new `packages/agent/src/workflow/quality-lint.ts` (`lintRestrictedWorkflowSource` / `assertRestrictedWorkflowQuality`, exported from the workflow package) runs inside restricted workflow module materialization (`script-runner.ts` `createRestrictedWorkflowModule`) and in the coding workflow host with host-policy `maxAgents`, so structural contract violations fail before a run can start — matching the existing inline-smoke hard-fail feedback loop. It hard-fails three deterministic contract classes only: (1) an unawaited workflow-command variable (`wf.runAgent` / `wf.spawnAgent` / `wf.wait` / `wf.synthesize` / `wf.workflow` / `wf.artifact`) used in a boolean position (`if (x)`, `!x`, ternary test, `x && …`, `x || …`, loop test) — a case a runtime Proxy cannot catch because object truthiness has no Proxy trap; (2) top-level structured-output field access (`result.findings`, `result.summary`, …) when the fields belong under `result.structured`; and (3) a literal `[...]`/`[...].map(...)` agent fanout whose static upper bound exceeds `manifest.maxAgents` or a known host cap. Review/verifier/generic quality heuristics are intentionally **not** emitted as model-visible warnings (a lightweight AST pass cannot distinguish a weak workflow from a valid optimized one, and surfacing them causes needless rewrite churn). Human test guide: `docs/test-guides/FEATURE_252_v0.7.61_TEST_GUIDE.md`.
+
+### Changed
+
+- **Review/audit workflow templates make adversarial verification explicit (FEATURE_252 Layer 2).** The default generator/authoring fixtures for `adversarial-verification` shapes now use explicit verifier stages and `task_id:` evidence refs, so the desired shape — finders → adversarial verifiers → synthesis of confirmed findings — is stated in the template rather than left to a weak authoring model to infer. This reduces reliance on lint and is robust to capability-limited authors.
+
+### Fixed
+
+- **Workflow-start crash: `typescript` promoted to a runtime dependency of `@kodax-ai/agent`.** The FEATURE_252 quality lint imports the TypeScript compiler API (`ts.createSourceFile`, …) and runs on every workflow start via `assertRestrictedWorkflowQuality`. With `typescript` only in `devDependencies`, a bundled/published build resolved no `typescript` module at that call site, throwing an uncaught error that crashed the process before the workflow ran (leaving the terminal in a corrupted mouse/alt-screen state). Moving `typescript` to `dependencies` fixes the workflow-front crash.
+
+## [0.7.60] - 2026-07-05
+
+> Scope note: an F250 refactor + Space SDK rollup. **FEATURE_250** brings the deferred-tool
+> progressive-disclosure mechanism — previously SA-path-only — to the AMA/AMAW **managed** tool
+> path, so cache-cold managed turns carry one-line search hints instead of full descriptions for
+> the repo-intelligence + web/code/goal tools. Tool `input_schema` is unchanged, so every deferred
+> tool stays directly callable; the full description is fetched on demand via `tool_search`.
+> Transparent (no user-facing behavior change) and prompt-additive only (a two-line
+> `code_search`/`semantic_lookup` teaching block). The release also lands **CAP-099 (Space SDK):
+> live turn attribution + structured transcript** — streamed activity events carry session/turn
+> identity, explicit turn-boundary events share one per-session sequence, and client-only
+> transcript notices are persisted without ever entering the model context. All additive and
+> profile/host-gated; the default path stays unchanged when a host does not read the new metadata.
+> No public runtime type is removed.
+
+### Added
+
+- **`code_search` / `semantic_lookup` teaching in the Worker REPO INTELLIGENCE prompt (FEATURE_250).** A two-line, eval-justified teaching block: the floor-tier alias under-adopted the hint-only tools on ambiguous tasks (75%), and the teaching recovered adoption to 100% while being strictly non-negative on every other alias.
+- **CAP-099 live turn attribution — session/turn identity on streamed events (Space SDK).** A shared live-turn scope (`createLiveTurnScope` / `withLiveTurnAttribution`, `event-emitter.ts`) stamps `KodaXActivityEventMeta` (`sessionId` / `seq` / `turnId` / `deliveryId` / `timestamp`) onto every streamed activity callback, and explicit turn-boundary events (`emitTurnStarted` / `emitTurnCompleted` / `emitTurnFailed`) share one monotonic per-session sequence — so an SDK host can route streamed assistant events to the owning turn's UI bubble by turn ownership instead of fragile ordering-by-observation. Threaded through messaging (queue/drain), orchestration (idle-yield), run-substrate, runner-driven, run-workflow, and dispatch-child-tasks; a host that ignores the metadata sees unchanged behavior. New `cap-099-live-turn-attribution` contract test; existing `cap-005/006/007/041/046/054/086` event-contract tests updated for the added meta parameter.
+- **Client-only transcript notices + structured transcript entries (CAP-099, Space SDK).** The persisted transcript gains structured entry types (`message` / `compaction` / `branch_summary` / `client_notice` / `task_result`) with `source` + `turnId`. A `client_notice` is persisted as a lineage entry, NOT a model message: `loadSession()` (active model context) omits it while `loadFullTranscript()` returns it with `type: 'client_notice'`, `source: 'client'`, and `payload.entersModelContext === false` — so a host can render client-side scrollback notices without polluting the model's context. SDK embedder guide updated (`docs/SDK_EMBEDDER_GUIDE.md`).
+- **Transcript clone provenance for SDK hosts (CAP-099, Space SDK).** Lineage entries now carry optional `logicalId` / `sourceEntryId`, and `loadFullTranscript().transcriptEntries[]` always exposes a stable `logicalId` (falling back to `entryId` for old sessions). Forked/cloned entries keep the source `logicalId` and point `sourceEntryId` at the root physical source entry, so hosts can fold cloned history precisely without guessing from role/content/timestamp or `[compacted]` placeholders. `loadFullTranscript()` remains raw append-order scrollback; it does not silently merge branches or hide compaction notices.
+
+### Changed
+
+- **Progressive disclosure on the AMA/AMAW managed tool path (FEATURE_250).** `buildAgentToolsFromRegistry` (`agent-chain.ts`) now hint-swaps the 13 non-mcp deferred tools — repo-intel (`repo_overview`, `changed_scope`, `module_context`, `symbol_context`, `process_context`, `impact_estimate`), web/code (`web_search`, `web_fetch`, `code_search`, `semantic_lookup`), and goal (`get_goal`, `create_goal`, `update_goal`) — to their `DEFERRED_TOOL_HINTS` one-liner. The swap is a one-time build-time change (the managed `Agent.tools` is a static array), so the tools[] prefix is cache-stable turn-to-turn. `mcp_*` (5) stay resident (remote-mutation risk + not covered by the reachability eval; conservative hold gated on a future MCP-runtime eval); `run_workflow` is untouched (host-conditional per FEATURE_246/249). Two eval panels (5-alias coding-plan) confirm no reachability harm: DEFER_SAFE 5/5, 0% read/grep fallback, and V_teach 100% adoption on ambiguous tasks. KodaX's hint-swap keeps the tool in `tools[]` with `input_schema` intact — safer than the reference agents (Claude Code / Codex) which remove deferred tools from the wire and therefore gate deferral off for weak models.
+- **Inline workflow preflight hardening (FEATURE_246).** The inline `run_workflow` restricted-smoke preflight now rejects two more classes of weak-model authoring bug before a workflow starts: (1) an unawaited `wf.runAgent` / `wf.synthesize` result that leaks into a property read, JSON serialization, or assignment — a Proxy trap throws `wf.<method> result must be awaited before …` instead of silently coercing a pending command; and (2) a `manifest.readOnly=true` workflow that spawns a write-capable child (`readOnly:false`) — it now throws at preflight instead of running. This is the deterministic-structural groundwork for the planned FEATURE_252 workflow-quality lints (v0.7.61).
+
+### Fixed
+
+- **`tool_search` result protected from microcompaction pruning (FEATURE_250).** `tool_search` is added to `PRUNE_PROTECTED_TOOLS` (`compaction.ts`). On the managed path a deferred tool's full description lives only in the `tool_search` result message (the static `Agent.tools` array cannot make a description resident mid-session), so the unconditional 20-turn prune would otherwise silently stub the only teaching surface for any non-prompt-taught deferral.
+- **Headless SDK resume recovers `<task-completed>` results + per-message timestamps (Space SDK).** Two resume/persistence fixes for headless SDK embedders; the KodaX TUI is byte-unchanged. (1) `dispatch_child_task` / `run_workflow` `<task-completed>` result banners are spliced into the transcript as synthetic user messages that the reconstruction helper drops, so a headless host with no `uiHistory` lost them on resume — they are now tagged `_source: 'task-completed'` (only when a task-notification actually drained) and restored as a distinct `task_completed` event seed at their transcript position; when `uiHistory` is present the derived seed is discarded, so the CLI does not double-render. (2) `KodaXMessage` carried no time, so `createSessionLineage` stamped a whole managed task's messages with one accounting-millisecond and per-message "N ago" footers collapsed — an additive `KodaXMessage.timestamp?` is now stamped at each message-finalization site and preferred by `createSessionLineage`. The dedup fingerprint ignores timestamp (resume dedup unaffected); old sessions fall back to accounting-time.
+- **Goal-state tool results protected from microcompaction pruning.** `get_goal` / `create_goal` / `update_goal` are added to `PRUNE_PROTECTED_TOOLS` (`compaction.ts`) alongside `tool_search`. The canonical goal state persists as session-lineage entries, but these tool results are the model-visible status snapshots and lifecycle-transition receipts (short, low-frequency, control-plane-like), so microcompaction's 20-turn prune no longer stubs the model's view of `/goal` state. (v0.7.60 review follow-up.)
+
 ## [0.7.59] - 2026-07-03
 
 > Scope note: a rollup release on top of v0.7.58. **FEATURE_248** and **FEATURE_249** extend