@kodax-ai/kodax 0.7.62 → 0.7.63

package/CHANGELOG.md

@@ -6,6 +6,65 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.7.63] - 2026-07-07
+
+> Scope note: a patch/stability release for SDK session boundaries and release
+> hygiene. No planned feature slot is consumed: `FEATURE_244` remains targeted
+> at `v0.7.65`. This release hardens the public `/session` subpath, keeps
+> rewind audit markers out of model context, makes `startKodaX()` wrapper
+> session IDs safe around auto-resume, improves `/reload` extension rediscovery,
+> and prunes superseded feature-design parking notes from the private feature-doc
+> index.
+
+### Added
+
+- **`@kodax-ai/kodax/session` now exports imperative compaction.**
+  `compactSession` and its public option/result types are re-exported from the
+  root session SDK subpath, with a package-level regression test proving the
+  bundled subpath exposes the same session facade hosts use in Space-style
+  integrations.
+- **Typed rewind transcript entries.** Session lineage now has a dedicated
+  `rewind_marker` entry type. `loadFullTranscript()` surfaces it as a structured
+  system transcript entry for host scrollback, while `loadSession()` and the
+  returned transcript `messages` keep rewind audit markers out of model context.
+  Downstream consumers that exhaustively switch on `KodaXSessionEntry` or
+  `SessionTranscriptEntryType` should handle `rewind_marker`.
+- **`/reload` rediscovers extensions.** The REPL reload command now re-scans
+  default and configured extension entrypoints from disk, creates the extension
+  runtime on demand, hot-reloads already loaded modules, loads newly discovered
+  modules, and reports separate "Extensions reloaded" / "Extensions loaded"
+  counts.
+
+### Changed
+
+- **SDK session boundary hardening.** `startKodaX()` now threads wrapper-generated
+  session IDs into forwarded run options only when the caller did not provide an
+  explicit ID and did not request auto-resume/resume discovery. Generated handle
+  IDs are marked internally so the "session.id without storage" warning remains
+  useful for caller-provided IDs without warning on the wrapper's own handle ID.
+- **Feature-design index cleanup.** Superseded/parked planning-only docs for old
+  `v0.7.67`, `v0.7.68`, `v0.7.71`, `v0.7.73`, and `v0.7.74` slots were pruned.
+  Active targets remain in the indexed docs: `FEATURE_228` is in `v0.7.62`,
+  `FEATURE_231` in `v0.7.70`, `FEATURE_235` in `v0.7.75`, `FEATURE_108` in
+  `v0.7.95`, and `FEATURE_225` in `v0.7.100`.
+
+### Fixed
+
+- **Rewind selection skips synthetic/tool-result user entries.** `/rewind`
+  previous-turn selection now walks the active lineage path and ignores
+  tool-result-only user messages plus synthetic user notices, avoiding accidental
+  rewinds to tool protocol plumbing instead of the previous real user prompt.
+- **Rewind helpers reject sidecar targets.** Direct lineage rewinds now reject
+  label/client/goal/archive/rewind-marker side-state entries and legacy rewind
+  compactions remain context-silent even if a damaged old session points
+  `activeEntryId` at one.
+- **`/reload` reports successful extension reloads.** Failed hot-reload attempts
+  are reported only in the failure count instead of also inflating the
+  "Extensions reloaded" success count.
+- **Transcript layout fixtures are deterministic.** Duration-sensitive transcript
+  layout tests now use fixed timestamps instead of `Date.now()`, removing a
+  release-gate flake without changing runtime behavior.
+
 ## [0.7.62] - 2026-07-06
 
 > Scope note: a memory-governance release plus interaction polish. **FEATURE_228**

package/README.md

@@ -396,7 +396,7 @@ KodaX has two layers that consumers should understand separately:
 | `packages/agent`  | `@kodax-ai/kodax/mcp`     | **Narrow subset** | MCP only — `McpCapabilityProvider` / `createMcpTransport` / `searchMcpCatalog` / ... (11 exports = pre-v0.7.43 `@kodax-ai/mcp` complete API) | MCP server hosts |
 | `packages/coding` | `@kodax-ai/kodax/coding`  | Full package | Coding agent + 50+ tools + repo-intelligence (342 exports) | Build a Claude Code-shape product |
 | `packages/repl`   | `@kodax-ai/kodax/repl`    | Full package | Ink TUI + permission modes + commands (193 exports) | Terminal-UI consumers |
-| `packages/repl`   | `@kodax-ai/kodax/session` | **Narrow subset** | Session management only — `listSessions` / `loadFullTranscript` / `appendClientNotice` / `forkSession` / `watchSessions` / ... | IDE plugins and desktop hosts reading session history |
+| `packages/repl`   | `@kodax-ai/kodax/session` | **Narrow subset** | Session management only — `listSessions` / `loadFullTranscript` / `appendClientNotice` / `forkSession` / `compactSession` / `watchSessions` / ... | IDE plugins and desktop hosts reading session history |
 
 **Rule of thumb**: if you need Runner / Agent / fan-out, import from `/agent`. If you only need skills or mcp APIs, import from `/skills` or `/mcp` to get a smaller bundle. The narrow subsets are subsets of the full packages — they do **not** expose extra symbols.
 
@@ -404,7 +404,7 @@ KodaX has two layers that consumers should understand separately:
 
 **Workflow Process Surface (FEATURE_229, v0.7.50)**: workflow progress is now a reusable Agent-layer process contract rather than private REPL text. SDK hosts can subscribe to `WorkflowProcessEvent`/poll `WorkflowProcessSnapshot`, use `createWorkflowRunManager` and `createWorkflowLifecycleController` for stop/pause/resume/result/artifact/delete/prune/identity/preflight controls, and receive ANSI-free provenance fields (`source`, `sourceRunId`, `sourceWorkflowName`, `savedWorkflowName`, `revisionOf`) plus `resultSummary`. `/coding` owns the coding workflow backend and run graph, `/repl` renders the same snapshots, and the terminal UI is not the hidden source of truth. `KodaXEvents` callbacks also take an optional metadata arg (`KodaXToolEventMeta` / `KodaXActivityEventMeta` / `KodaXWorkflowEventMeta`) so a host can attribute every child-agent tool/thinking/progress event to its workflow run and child id without a second event protocol, and generated/saved workflow scripts pass `validateRestrictedWorkflowSource` (compile + source-policy check) plus a generator repair/smoke loop before they run. See [docs/ADR.md ADR-040](docs/ADR.md) for the layering rationale.
 
-**Host Reads Persisted History (FEATURE_230 + FEATURE_234, v0.7.51)**: additive closures for hosts that read persisted state. **Durable tool transcript replay** — a resumed session now replays the tool cards the assistant used instead of degrading to text-only. `messages` / `lineage` stay canonical; `SessionData.uiHistory` becomes a bounded, sanitized, terminal-only replay cache. The SDK transcript contract is explicit: `loadSession()` = active model context, `loadFullTranscript()` = append-order host scrollback with typed entries (`message` / `compaction` / `branch_summary` / `client_notice` / `task_result`) plus clone provenance (`logicalId` / `sourceEntryId`), `uiHistory` = optional replay cache, and tool cards can always be reconstructed from canonical messages. Hosts can persist local slash output with `appendClientNotice()` without entering model context, and workflow/child completions expose structured `taskResults[]` instead of requiring `<task-completed>` parsing. **Workflow run host attribution** — `WorkflowProcessTrackerOptions` / `WorkflowProcessSnapshot` gain a host-owned opaque `hostMetadata?: Record<string, string>` that the SDK stores, persists to `run.json`, and echoes back (including after a restart) without interpreting it, so a host can map a run to the session/surface that launched it with zero side table. Unstamped/legacy runs honestly echo `hostMetadata === undefined`. See [docs/features/v0.7.51.md](docs/features/v0.7.51.md).
+**Host Reads Persisted History (FEATURE_230 + FEATURE_234, v0.7.51; v0.7.63 hardening)**: additive closures for hosts that read persisted state. **Durable tool transcript replay** — a resumed session now replays the tool cards the assistant used instead of degrading to text-only. `messages` / `lineage` stay canonical; `SessionData.uiHistory` becomes a bounded, sanitized, terminal-only replay cache. The SDK transcript contract is explicit: `loadSession()` = active model context, `loadFullTranscript()` = append-order host scrollback with typed entries (`message` / `compaction` / `branch_summary` / `rewind_marker` / `client_notice` / `task_result`) plus clone provenance (`logicalId` / `sourceEntryId`), `uiHistory` = optional replay cache, and tool cards can always be reconstructed from canonical messages. Hosts can persist local slash output with `appendClientNotice()` without entering model context, and workflow/child completions expose structured `taskResults[]` instead of requiring `<task-completed>` parsing. `rewind_marker` is an audit entry for host scrollback only and is excluded from model-context messages. **Workflow run host attribution** — `WorkflowProcessTrackerOptions` / `WorkflowProcessSnapshot` gain a host-owned opaque `hostMetadata?: Record<string, string>` that the SDK stores, persists to `run.json`, and echoes back (including after a restart) without interpreting it, so a host can map a run to the session/surface that launched it with zero side table. Unstamped/legacy runs honestly echo `hostMetadata === undefined`. See [docs/features/v0.7.51.md](docs/features/v0.7.51.md).
 
 **Inline Workflow Authoring (FEATURE_246, v0.7.58)**: in AMA/AMAW the Worker can now author and run a workflow inline via a model-callable `run_workflow` tool — it scouts the codebase with its own tools first, then bakes concrete findings into each child prompt, and runs the script through the **unchanged** sandbox + static-validation + postcondition-verification pipeline. This replaces the context-blind `sideQuery` generator as the primary interactive path (the generator survives only as a fallback for the explicit `/workflow create` command and non-interactive / CI hosts that have no investigating Worker). It adds structured child output (`outputSchema`), the no-barrier `wf.pipeline` staged primitive, same-session resume (`resumeFromRunId`), nested `wf.workflow(...)`, and a `/workflow create` redirect to Worker-authored scouting; `run_workflow` is async / idle-yield so the turn is not blocked. The neutral run-lifecycle manager (`createWorkflowRunManager` / `getDefaultWorkflowRunManager`) now lives in `@kodax-ai/kodax/agent` for non-coding SDK hosts. See [docs/features/v0.7.58.md](docs/features/v0.7.58.md) and [docs/ADR.md](docs/ADR.md) ADR-044/046/047/048/049.
 

package/README_CN.md

@@ -500,13 +500,13 @@ KodaX 有两层结构，SDK 用户需要分开理解：
 | `packages/agent`  | `@kodax-ai/kodax/mcp`     | **窄子集** | 仅 MCP —— `McpCapabilityProvider` / `createMcpTransport` / `searchMcpCatalog` 等 (11 exports = v0.7.43 之前 `@kodax-ai/mcp` 完整 API) | MCP server 宿主 |
 | `packages/coding` | `@kodax-ai/kodax/coding`  | 完整包 | Coding agent + 50+ 工具 + repo-intelligence (342 exports) | 构建 Claude Code 形态产品 |
 | `packages/repl`   | `@kodax-ai/kodax/repl`    | 完整包 | Ink TUI + 权限模式 + 命令系统 (193 exports) | 终端 UI 消费者 |
-| `packages/repl`   | `@kodax-ai/kodax/session` | **窄子集** | 仅会话管理 —— `listSessions` / `loadFullTranscript` / `appendClientNotice` / `forkSession` / `watchSessions` 等 | 读取 session 历史的 IDE 插件和桌面宿主 |
+| `packages/repl`   | `@kodax-ai/kodax/session` | **窄子集** | 仅会话管理 —— `listSessions` / `loadFullTranscript` / `appendClientNotice` / `forkSession` / `compactSession` / `watchSessions` 等 | 读取 session 历史的 IDE 插件和桌面宿主 |
 
 **经验法则**：需要 Runner / Agent / fan-out 时从 `/agent` 引入；只需要 skills 或 mcp API 时从 `/skills` 或 `/mcp` 引入，bundle 更小。窄子集是完整包的真子集 —— **不会**有额外符号。
 
 **Workflow process surface（FEATURE_229，v0.7.50）**：动态工作流不再只是 REPL 私有文本，而是 Agent 层可复用的 process/event/snapshot 契约。SDK 宿主可以订阅 `WorkflowProcessEvent`、轮询 `WorkflowProcessSnapshot`，并通过 `createWorkflowRunManager` / `createWorkflowLifecycleController` 做 stop/pause/resume、读取 final result/artifact、删除/清理 terminal runs、管理 workflow identity/preflight。`/coding` 负责 coding workflow backend 与 run graph，`/repl` 只是消费同一份 snapshot 渲染 UI；SDK 不需要解析 slash-command 输出或 Ink view-model。`KodaXEvents` 回调新增可选 meta 尾参（`KodaXToolEventMeta` / `KodaXActivityEventMeta` / `KodaXWorkflowEventMeta`），宿主据此把每个子 Agent 的 tool/thinking/progress 事件归因到对应 workflow run 与 child id，无需第二套事件协议；生成/保存的工作流脚本在运行前过 `validateRestrictedWorkflowSource`（编译 + 源策略检查）与 generator 的 repair/smoke 循环。分层取舍见 [docs/ADR.md ADR-040](docs/ADR.md)。
 
-**宿主读持久化历史（FEATURE_230 + FEATURE_234，v0.7.51）**：面向「宿主读持久化状态」的 additive 闭环。**持久化工具记录回放**——resume 的会话现在会回放助手用过的工具卡片，而不是退化成纯文本。`messages` / `lineage` 仍是 canonical；`SessionData.uiHistory` 成为有界、脱敏、仅 terminal 状态的回放缓存。SDK transcript 契约明确化：`loadSession()` = 活动 model context，`loadFullTranscript()` = 带结构化条目的追加序 host scrollback（`message` / `compaction` / `branch_summary` / `client_notice` / `task_result`）并带 clone provenance（`logicalId` / `sourceEntryId`），`uiHistory` = 可选回放缓存，工具卡片始终可从 canonical messages 重建。宿主可用 `appendClientNotice()` 持久化本地 slash 输出且不进入模型上下文；workflow/child 完成结果通过结构化 `taskResults[]` 暴露，不再要求解析 `<task-completed>` 文本。**Workflow run 宿主归属**——`WorkflowProcessTrackerOptions` / `WorkflowProcessSnapshot` 新增 host-owned 不透明 `hostMetadata?: Record<string, string>`，SDK 存储、持久化进 `run.json`、回读回显（含进程重启后）但不解释其含义，让宿主零侧表把 run 归回发起它的 session/surface。未 stamp 的旧 run 诚实回显 `hostMetadata === undefined`。详见 [docs/features/v0.7.51.md](docs/features/v0.7.51.md)。
+**宿主读持久化历史（FEATURE_230 + FEATURE_234，v0.7.51；v0.7.63 hardening）**：面向「宿主读持久化状态」的 additive 闭环。**持久化工具记录回放**——resume 的会话现在会回放助手用过的工具卡片，而不是退化成纯文本。`messages` / `lineage` 仍是 canonical；`SessionData.uiHistory` 成为有界、脱敏、仅 terminal 状态的回放缓存。SDK transcript 契约明确化：`loadSession()` = 活动 model context，`loadFullTranscript()` = 带结构化条目的追加序 host scrollback（`message` / `compaction` / `branch_summary` / `rewind_marker` / `client_notice` / `task_result`）并带 clone provenance（`logicalId` / `sourceEntryId`），`uiHistory` = 可选回放缓存，工具卡片始终可从 canonical messages 重建。宿主可用 `appendClientNotice()` 持久化本地 slash 输出且不进入模型上下文；workflow/child 完成结果通过结构化 `taskResults[]` 暴露，不再要求解析 `<task-completed>` 文本。`rewind_marker` 只用于 host scrollback 审计，不进入 model-context messages。**Workflow run 宿主归属**——`WorkflowProcessTrackerOptions` / `WorkflowProcessSnapshot` 新增 host-owned 不透明 `hostMetadata?: Record<string, string>`，SDK 存储、持久化进 `run.json`、回读回显（含进程重启后）但不解释其含义，让宿主零侧表把 run 归回发起它的 session/surface。未 stamp 的旧 run 诚实回显 `hostMetadata === undefined`。详见 [docs/features/v0.7.51.md](docs/features/v0.7.51.md)。
 
 **Inline workflow authoring（FEATURE_246，v0.7.58）**：AMA/AMAW 下 Worker 现在可通过 model-callable 的 `run_workflow` 工具在会话内直接编写并运行工作流——先用自己的工具 scout 代码库，再把具体发现烤进每个 child prompt，然后走**不变的** sandbox + 静态校验 + postcondition 验证流水线。它取代 context-blind 的 `sideQuery` generator 成为主交互路径（generator 仅作为显式 `/workflow create` 命令与无 investigating Worker 的 non-interactive/CI 主机的 fallback 保留）；新增结构化 child 输出（`outputSchema`）、无 barrier 的 `wf.pipeline` 分阶段原语、同会话 resume（`resumeFromRunId`）、嵌套 `wf.workflow(...)`，`/workflow create` 重定向到 Worker 的 scout-then-author；`run_workflow` 为 async / idle-yield，不阻塞当前轮。中立的 run-lifecycle manager（`createWorkflowRunManager`）已移入 `@kodax-ai/kodax/agent` 供非 coding SDK 宿主使用。详见 [docs/features/v0.7.58.md](docs/features/v0.7.58.md) 与 [docs/ADR.md](docs/ADR.md) ADR-044/046/047/048/049。
 

package/dist/chunks/{agent-4ZMCIEGD.js → agent-SL444XLN.js}

@@ -1,2 +1,2 @@
 // @kodax-ai/kodax — bundled distribution. See docs/ADR.md ADR-022 + ADR-024.
-import{I as c,J as d,K as e,L as f,Z as g,_ as h,ia as i,qa as j}from"./chunk-WFE6FBQ2.js";import"./chunk-D6QVXQNI.js";import"./chunk-UA744TZM.js";import"./chunk-S4ISEA6F.js";import"./chunk-S4GVQO3W.js";import{ob as a,pb as b}from"./chunk-E2Q4RIOD.js";import"./chunk-ZL5CEANW.js";import"./chunk-V4WSBIXB.js";export{d as bucketProviderPayloadSize,g as buildAutoRepoIntelligenceContext,e as checkPromiseSignal,b as cleanupIncompleteToolCalls,h as describeTransientProviderRetry,f as emitResilienceDebug,c as estimateProviderPayloadBytes,j as runKodaX,i as saveSessionSnapshot,a as validateAndFixToolHistory};
+import{I as c,J as d,K as e,L as f,Z as g,_ as h,ja as i,ra as j}from"./chunk-LGR7ACBQ.js";import"./chunk-D6QVXQNI.js";import"./chunk-UA744TZM.js";import"./chunk-RR7W7UF6.js";import"./chunk-S4GVQO3W.js";import{ob as a,pb as b}from"./chunk-UGTK2JIJ.js";import"./chunk-ZL5CEANW.js";import"./chunk-V4WSBIXB.js";export{d as bucketProviderPayloadSize,g as buildAutoRepoIntelligenceContext,e as checkPromiseSignal,b as cleanupIncompleteToolCalls,h as describeTransientProviderRetry,f as emitResilienceDebug,c as estimateProviderPayloadBytes,j as runKodaX,i as saveSessionSnapshot,a as validateAndFixToolHistory};

package/dist/chunks/argument-completer-EN63ZVJK.js

@@ -0,0 +1,2 @@
+// @kodax-ai/kodax — bundled distribution. See docs/ADR.md ADR-022 + ADR-024.
+import{Aa as b,za as a}from"./chunk-7MPU7TP6.js";import"./chunk-L3MF5V64.js";import"./chunk-VSWROENP.js";import"./chunk-4MIHVNB7.js";import"./chunk-KCFVGXVK.js";import"./chunk-HP4FXMEM.js";import"./chunk-LGR7ACBQ.js";import"./chunk-D6QVXQNI.js";import"./chunk-UA744TZM.js";import"./chunk-RR7W7UF6.js";import"./chunk-S4GVQO3W.js";import"./chunk-UGTK2JIJ.js";import"./chunk-ZL5CEANW.js";import"./chunk-V4WSBIXB.js";export{a as ArgumentCompleter,b as createArgumentCompleter};