@kodax-ai/kodax 0.7.93 → 0.7.94

package/CHANGELOG.md

@@ -8,6 +8,104 @@ All notable changes to this project will be documented in this file.
 
 ---
 
+## [0.7.94] - 2026-08-21
+
+### Changed
+
+- Runtime capability negotiation and pre-start SDK facts now advertise
+  `conversationHistory:2` only when
+  ordinary history is topology-transparent across managed context and direct
+  clone provenance is preserved. Embedders can require v2 to reject stale daemon
+  processes that still expose the legacy projection contract. Auto-start replaces
+  an idle v1 daemon and fails closed while an incompatible daemon is busy.
+- Skill invocation now has an explicit source contract across CLI, REPL, SDK,
+  Runtime, Workflow, and child-Agent paths. Every enabled Skill remains
+  explicitly invocable; `disable-model-invocation: true` only removes it from
+  model discovery and blocks the model `skill` tool. The legacy
+  `user-invocable` field remains parse-compatible but is no longer an execution
+  permission.
+- The public README files, package SDK guides, Embedder Guide, public sandbox
+  guide, HLD/DD, `kodax_manual` commands/skills topics, skill-creator
+  authoring contract, and Runtime SDK type comments now document the same Skill
+  catalog, slash-argument, provenance, child-delegation, Run-settlement,
+  typed-disconnect, safe-failure, and exact-`runId` recovery contracts.
+
+### Fixed
+
+- Sandboxed text-mutation helper stdin failures are now observed by the
+  operation Promise instead of escaping as process-level stream errors.
+  Linked-worktree and submodule relationship files are read through strict
+  byte bounds before external Git metadata earns sandbox trust.
+- Explicit Skill runtime policy now diagnoses invalid `allowed-tools` entries
+  and malformed hook JSON. `PostToolUse` still runs when an embedder's base
+  result observer throws, while preserving that observer failure for its
+  caller.
+
+- Scheduled Runtime daemon shutdown now rejects the public host lifecycle when
+  cleanup fails, while retaining an internal rejection observer so embedded
+  hosts do not emit an unhandled rejection. CLI stop persists and reports the
+  matching failed shutdown outcome instead of claiming a safe stop.
+- Worktree Git process-tree drain now returns a bounded error when completion
+  remains unprovable, while leaving the namespace lease fail-closed. Successful
+  `insert_after_anchor` mutations also refresh the content-hash cache so the
+  next edit is not falsely rejected as stale.
+- Windows sandbox Git trust now removes ASRT wildcard `safe.directory` entries
+  even when no authorized root survives, rejects malformed `GIT_CONFIG_*`
+  shapes, and generates broker and bundled rewriting from one implementation.
+  Linked-worktree metadata must prove its backlink before the main `.git` earns
+  read trust; repository-bearing metadata read roots join the exact trust set
+  (Issue 300).
+- Long-running and background Bash processes no longer block Runtime `write`,
+  `edit`, `multi_edit`, `insert_after_anchor`, or `undo` solely because a shell
+  lease is alive. Those tools now perform both snapshot and identity-aware
+  optimistic compare-and-write through the same ASRT workspace policy, while
+  preserving same-path FIFO ordering. Sandbox failure for a covered workspace
+  target fails closed; non-workspace targets, standalone/other host filesystem
+  sinks, incompatible Windows ACL policies, and worktree namespace changes
+  retain their existing safety fences. Runtime non-workspace host writes also
+  reject symlink/junction-routed and hard-linked targets inside that fence.
+- Sandboxed text backup authority is minted from the helper's opened file
+  identity, preserving stable alias undo without trusting concurrent host
+  `realpath`. A permanently rejected Windows Job drain proof now reports the
+  error and keeps the worktree namespace fence fail-closed instead of polling
+  a settled promise forever or trusting a root-only process check.
+- Sandboxed text mutations now reject hard-linked targets at snapshot and
+  commit, reject canonical backup identities outside the workspace capability,
+  and preserve the winning undo record when two lexical aliases race. POSIX
+  workspace-session startup no longer conflicts with unrelated live shell
+  policies because its sandbox policy is process-local; Windows retains its
+  shared-account ACL transition fence.
+- Runtime start omits the concurrent text-mutation sandbox when the workspace
+  directory does not exist yet, instead of aborting option construction.
+- Run terminal convergence now observes every finalization rejection. A durable
+  terminal status remains authoritative if only event publication fails; when
+  neither terminal record can be persisted, the public Run resolves as
+  `unknown` with `run_settlement_not_persisted` and the Session execution fence
+  remains closed instead of escalating the rejection to the daemon process.
+- Workspace-sandbox and managed-child emergency termination promises are now
+  observed and retain fail-closed diagnostics when process-tree drain cannot be
+  confirmed. Daemon transport disconnects expose typed connection facts, reject
+  oversized outbound frames before socket write, and credential-safe terminals
+  preserve a bounded `failureKind` without persisting provider error text.
+- Explicit `/<name>` and `/skill:<name>` tokens now resolve at the query head or
+  middle, preserve suffix arguments, and use the same host-owned expansion,
+  hooks, and permission pipeline in Classic, Ink, non-interactive CLI, queued
+  follow-ups, isolated Runtime, and terminal SDK helpers. Low-level
+  `SkillRegistry.invoke()` remains an explicit load/resolve primitive; SDK hosts
+  that need lifecycle hooks and permission admission use
+  `prepareInvocationExecution`. Expanded Skill content enters the provider
+  request exactly once.
+- A structured host `skillInvocation` now propagates an active explicit Skill to
+  Workflow children, while model-authored child objectives must use the
+  governed model tool and cannot bypass `disable-model-invocation` by writing a
+  slash token or forged Skill block.
+- The publish-tarball regression test now honors the standard `npm_execpath`
+  supplied by npm-compatible test launchers. The Windows optional-ASRT test
+  verifies the additional unrepresentable-path fallback without assuming that
+  local ASRT containment is always available.
+
+---
+
 ## [0.7.93] - 2026-08-19
 
 ### Fixed

package/README.md

@@ -113,7 +113,7 @@ you.
     </td>
     <td align="center" valign="top">
       <h3>🧩 Skills + self-construction</h3>
-      <sub>Markdown skills, NL triggers</sub>
+      <sub>Markdown Skills, model-visible NL discovery, explicit slash invocation</sub>
       <br><br>
       5-stage self-modification staircase (scaffold → validate → stage → test → activate) gated by an 8-invariant admission contract.
     </td>
@@ -726,6 +726,32 @@ permission UI, and recovers stale prepared Session tails through an
 authoritative merge. Background persistence failures are surfaced as
 diagnostics rather than hidden.
 
+**v0.7.94 release:** Runtime text tools may overlap a compatible live Bash
+lease because snapshot and commit run through the same ASRT workspace policy.
+Hard-linked workspace targets are rejected. Windows sandboxed git trusts
+authorized repo roots only and never emits `safe.directory=*` (Issue 300).
+Linked-worktree and submodule relationship files are read through strict byte
+bounds before that git trust is granted. Sandboxed text-helper stdin failures
+stay on the operation Promise. Scheduled daemon shutdown reports failed
+cleanup instead of a safe stop.
+A missing workspace directory omits the concurrent text sandbox at Run start.
+Runtime advertises `conversationHistory:2`. Explicit Skill invocation
+(`/<name>`, `/skill:<name>`) remains available for every enabled Skill;
+`disable-model-invocation` only blocks the model tool path. Invalid
+`allowed-tools` entries and malformed hook JSON are diagnosed; `PostToolUse`
+still runs if an embedder result observer throws. Every Run
+finalization and sandbox/managed-child termination rejection is observed. If
+neither terminal record can be persisted, the Run resolves `unknown` with
+`run_settlement_not_persisted` and keeps the Session fenced. Daemon connection
+loss exposes a typed code, `connectionId`, and `reconnectable` fact. Once a
+host receives a `runId`, it must retain it and, after reconnecting, call
+`runs.get(runId)` then `runs.await(runId)` on the replacement Runtime. It must
+never replay `runs.start()` for that admitted Run. Capability versions
+`sandboxRuntime:4` and `crashOutcomeModel:2` are unchanged. Issue 256 remains
+open. See the
+[v0.7.94 release checklist](docs/release.md#v0794-release-preparation)
+and [SDK Embedder Guide](public_docs/sdk/embedder-guide.md#query-authoritative-session-and-run-lifecycle).
+
 **v0.7.93 release:** Runtime exit settlement no longer spends the 170-second
 Windows orderly-exit window after a durable `failed` shutdown outcome, can
 recover previous-boot shared ACL markers after a verified boot change, and
@@ -1622,28 +1648,33 @@ described under FEATURE_272 above.
 
 ### `@kodax-ai/kodax/skills` — Skills System
 
-Zero external dependencies. Markdown-based skill files with natural-language triggers and variable resolution.
+Markdown-based skill files with natural-language triggers, explicit slash invocation, and variable resolution.
 
 ```typescript
 import {
   SkillRegistry,
-  discoverSkills,
-  executeSkill,
   type SkillContext,
 } from '@kodax-ai/kodax/skills';
 
-const skills = await discoverSkills(['/path/to/skills']);
-const registry = new SkillRegistry();
-await registry.registerSkills(skills);
-
-const result = await executeSkill({
-  skillId: 'code-review',
-  arguments: { target: 'src/' },
-  workingDirectory: process.cwd(),
+const registry = new SkillRegistry(process.cwd(), {
+  projectPaths: ['/path/to/skills'],
 });
+await registry.discover();
+
+const context: SkillContext = { workingDirectory: process.cwd() };
+const modelCatalog = registry.getSystemPromptSnippet(); // Excludes model-disabled Skills.
+const result = await registry.invoke('code-review', 'src/', context);
 ```
 
-**Key Features**: zero deps · markdown-based skill files · natural-language triggering · variable resolution · built-in skills included.
+Every enabled Skill is explicitly user-invocable with `/<name>` or `/skill:<name>`, including when the token appears in the middle of a query; the remaining text is passed as Skill arguments. `disable-model-invocation: true` only removes the Skill from the model-visible catalog and blocks the model's `skill` tool path. It does not block explicit user or SDK `SkillRegistry.invoke()` calls. The legacy `user-invocable` field is retained for parsing compatibility but is not an execution permission.
+
+Explicit invocation is expanded by the host and injected once as structured
+`skillInvocation` context. Workflow and child Agents inherit that active Skill.
+A slash reference authored only inside a model-generated child objective is a
+new model invocation, so it must pass through the governed `skill` tool and
+cannot elevate a `disable-model-invocation` Skill.
+
+**Key Features**: markdown-based skill files · natural-language triggering for model-visible Skills · explicit slash invocation for every enabled Skill · variable resolution · built-in skills included.
 
 ### `@kodax-ai/kodax/coding` — Coding Agent
 
@@ -1830,18 +1861,23 @@ KodaX ships 50+ built-in tools, grouped below. They are registered as a single f
 
 ## Skills System
 
-KodaX includes a built-in Skills system that can be triggered by natural language:
+KodaX includes a built-in Skills system. Model-visible Skills can be triggered
+by natural language; every enabled Skill can be invoked explicitly:
 
 ```bash
 # Natural language triggering (no explicit /skill needed)
 kodax "帮我审查代码"           # Triggers code-review skill
-kodax "写测试用例"             # Triggers tdd skill
-kodax "提交代码"               # Triggers git-workflow skill
+kodax "创建一个新的 KodaX Skill" # Triggers skill-creator
 
-# Explicit skill command
-kodax /skill:code-review
+# Explicit skill commands (arguments may follow the token)
+kodax /code-review src/
+kodax /tdd packages/repl/src/
+kodax /git-workflow commit
+kodax "please use /skill:code-review src/"
 ```
 
+Set `disable-model-invocation: true` for a Skill that must only be loaded after an explicit slash invocation. This keeps it out of natural-language model discovery without disabling `/<name>` or `/skill:<name>`.
+
 Built-in skills include:
 - **code-review** - Code review and quality analysis
 - **tdd** - Test-driven development workflow

package/README_CN.md

@@ -266,6 +266,26 @@ SDK 系统代码契约更新，但没有放宽 shell/sandbox 的 fail-closed 边
 `handleRuntimePermissionRequest()` 管理 SDK 权限 UI，并在 prepared Session 尾部遇到
 `data_changed` 时通过权威 delta 合并恢复；后台持久化失败会显示为诊断，不再静默丢失。
 
+**v0.7.94 发布**：Runtime 文本工具可以与兼容的长驻/后台 Bash 并发，因为
+snapshot 与 commit 走同一套 ASRT workspace 策略。硬链接工作区目标会被拒绝。
+Windows 沙箱 git 只信任已授权的仓库根，不再发出 `safe.directory=*`（Issue 300）。
+linked-worktree / submodule 关系文件在授予 git trust 前按严格字节上限读取。
+沙箱文本 helper 的 stdin 失败留在该操作 Promise 上。
+计划中的 daemon shutdown 在 cleanup 失败时报告失败，而不是声称安全停止。
+工作区目录尚不存在时，Run 启动会省略并发文本沙箱，而不是中止 option 构造。
+Runtime 广告 `conversationHistory:2`。显式 Skill 调用（`/<name>`、
+`/skill:<name>`）对每个已启用 Skill 始终可用；`disable-model-invocation`
+只关闭模型工具路径。无效 `allowed-tools` 与畸形 hook JSON 会被诊断；
+embedder 的 result observer 抛错时 `PostToolUse` 仍会运行。所有 Run 终态收敛以及 sandbox / managed-child
+终止 Promise 都会显式观察 rejection。若两种终态记录都无法持久化，Run 以
+`unknown` + `run_settlement_not_persisted` 收敛，并继续关闭 Session 执行门禁。
+daemon 断线公开 typed code、`connectionId` 和 `reconnectable` 事实。宿主一旦取得
+`runId`，重连后必须在 replacement Runtime 上调用 `runs.get(runId)` 与
+`runs.await(runId)`，绝不能为同一已接纳 Run 再次调用 `runs.start()`。
+`sandboxRuntime:4` 与 `crashOutcomeModel:2` 不变。Issue 256 仍保持 Open。
+详见 [v0.7.94 发布清单](docs/release.md#v0794-release-preparation) 与
+[SDK Embedder Guide](public_docs/sdk/embedder-guide.md#query-authoritative-session-and-run-lifecycle)。
+
 **v0.7.93 发布**：Windows 退出结算在精确 owner 已写入 durable `failed`
 shutdown outcome 后不再空等 170 秒有序窗口，改为立即进入既有精确恢复路径。
 验证 boot 变化后，可在 machine lock 下回收上一启动留下的共享 ACL marker，
@@ -946,6 +966,8 @@ KodaX 有两层结构，SDK 用户需要分开理解：
 
 **经验法则**：需要 Runner / Agent / fan-out 时从 `/agent` 引入；只需要 skills 或 mcp API 时从 `/skills` 或 `/mcp` 引入，bundle 更小。窄子集是完整包的真子集 —— **不会**有额外符号。
 
+Skill 的两条触发路径彼此独立：未设置 `disable-model-invocation: true` 的 Skill 会把名称和描述注入模型上下文，因而可被自然语言自动发现；所有已启用 Skill 都始终支持用户显式输入 `/<name>` 或 `/skill:<name>`（可位于 query 头部或中间，后续文本作为参数）。`disable-model-invocation: true` 只关闭模型发现与模型 `skill` 工具调用，不会禁止显式 `/skill` 或 SDK `SkillRegistry.invoke()`。旧的 `user-invocable` 字段仅保留解析兼容性，不再充当执行权限。宿主会把显式调用展开一次并以结构化 `skillInvocation` 传入 SA/AMA、Workflow 与子 Agent；模型自己在 child objective 中写出的 slash token 仍是新的模型调用，必须经过受限 `skill` 工具，不能借委派绕过该标记。
+
 **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；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)。

package/dist/builtin/skill-creator/SKILL.md

@@ -47,6 +47,11 @@ compatibility: "Optimized for KodaX and Agent Skills style directories. Bundled
 - 大块参考资料放到 `references/`。
 - 模板或静态文件放到 `assets/`。
 - 如果某个专家流程只服务这个 skill，可以放进 `agents/`，但先把它当私有 contract，不要自动上升成全局产品概念。
+- `description` 同时决定模型发现。自然语言只会看到未设置 `disable-model-invocation: true` 的 name/description。
+- 需要只在显式 slash 后加载时，写 `disable-model-invocation: true`。这只关闭模型 catalog 与模型 `skill` 工具。
+- 每个已启用 Skill 都接受 `/<name>` 和 `/skill:<name>`。
+- token 可在 query 头部或中间。后续文本是 Skill 参数。
+- `user-invocable` 只保留解析兼容。不要把它当成执行权限：宿主忽略该字段后，作者会误以为 `false` 能禁止 slash/SDK 调用。
 
 ### 4. Bundled scripts 默认用 Node.js
 

package/dist/builtin/skill-creator/scripts/init-skill.js

@@ -19,6 +19,7 @@ export function renderSkillTemplate(name, description) {
 name: ${name}
 description: ${description}
 user-invocable: true
+disable-model-invocation: false
 allowed-tools: "Read, Grep, Glob"
 compatibility: "Optimized for KodaX and Agent Skills style directories."
 ---
@@ -131,8 +132,8 @@ function parseArgs(argv) {
   return args;
 }
 
-export async function main(argv = process.argv) {
-  const args = parseArgs(argv);
+export async function main(argv = process.argv) {
+  const args = parseArgs(argv);
   if (!args.name) {
     console.error('Usage: node scripts/init-skill.js <skill-name> [--path <skills-dir>] [--description <text>] [--force] [--no-evals]');
     process.exit(1);
@@ -142,8 +143,8 @@ export async function main(argv = process.argv) {
   console.log(`Initialized ${result.skillDir}`);
 }
 
-const isDirectRun = process.env.KODAX_MODULE_BUNDLE !== 'true'
-  && process.argv[1]
+const isDirectRun = process.env.KODAX_MODULE_BUNDLE !== 'true'
+  && process.argv[1]
   && fileURLToPath(import.meta.url) === path.resolve(process.argv[1]);
 
 if (isDirectRun) {

package/dist/chunks/{agent-R7HVNARP.js → agent-Q3FB3GNZ.js}

@@ -1,2 +1,2 @@
 // @kodax-ai/kodax — bundled distribution. See docs/ADR.md ADR-022 + ADR-024.
-import{Ka as g,Ma as h,Za as i,_a as j,a as c,sa as d,ta as e,ua as f,yc as k}from"./chunk-JJ2YDBSN.js";import"./chunk-7QBWHCIZ.js";import"./chunk-JTZKC4TV.js";import"./chunk-GH3KBC2H.js";import"./chunk-YVG6OKN7.js";import"./chunk-BHE66SP3.js";import{Jb as a,Kb as b}from"./chunk-7XSZVOG7.js";import"./chunk-QFV6YCIH.js";import"./chunk-ONUPGMER.js";export{e as bucketProviderPayloadSize,g as buildAutoRepoIntelligenceContext,f as checkPromiseSignal,b as cleanupIncompleteToolCalls,h as describeTransientProviderRetry,c as emitResilienceDebug,d as estimateProviderPayloadBytes,k as runKodaX,j as saveRequiredSessionSnapshot,i as saveSessionSnapshot,a as validateAndFixToolHistory};
+import{$a as j,Bc as k,La as g,Na as h,_a as i,a as c,ta as d,ua as e,va as f}from"./chunk-56CIZI5I.js";import"./chunk-7QBWHCIZ.js";import"./chunk-ZGZLSKN6.js";import"./chunk-N7HIJNJH.js";import"./chunk-BVV3IA5W.js";import"./chunk-BHE66SP3.js";import{Jb as a,Kb as b}from"./chunk-UNRHTOT5.js";import"./chunk-77PNP27P.js";import"./chunk-ONUPGMER.js";export{e as bucketProviderPayloadSize,g as buildAutoRepoIntelligenceContext,f as checkPromiseSignal,b as cleanupIncompleteToolCalls,h as describeTransientProviderRetry,c as emitResilienceDebug,d as estimateProviderPayloadBytes,k as runKodaX,j as saveRequiredSessionSnapshot,i as saveSessionSnapshot,a as validateAndFixToolHistory};

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

@@ -0,0 +1,2 @@
+// @kodax-ai/kodax — bundled distribution. See docs/ADR.md ADR-022 + ADR-024.
+import{Ma as a,Na as b}from"./chunk-ZKEXHAXA.js";import"./chunk-YMNFQ7SQ.js";import"./chunk-IIIAUDGW.js";import"./chunk-ZMGATMXN.js";import"./chunk-NGOPE4KK.js";import"./chunk-56CIZI5I.js";import"./chunk-7QBWHCIZ.js";import"./chunk-6BATYA47.js";import"./chunk-ZGZLSKN6.js";import"./chunk-N7HIJNJH.js";import"./chunk-BVV3IA5W.js";import"./chunk-BHE66SP3.js";import"./chunk-UNRHTOT5.js";import"./chunk-77PNP27P.js";import"./chunk-ONUPGMER.js";export{a as ArgumentCompleter,b as createArgumentCompleter};