@kodax-ai/kodax 0.7.92 → 0.7.94

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (81) hide show
  1. package/CHANGELOG.md +125 -0
  2. package/README.md +63 -18
  3. package/README_CN.md +31 -0
  4. package/dist/builtin/skill-creator/SKILL.md +5 -0
  5. package/dist/builtin/skill-creator/scripts/init-skill.js +5 -4
  6. package/dist/chunks/{agent-YHHFIH7N.js → agent-Q3FB3GNZ.js} +1 -1
  7. package/dist/chunks/argument-completer-SS2Q2ZKT.js +2 -0
  8. package/dist/chunks/chunk-56CIZI5I.js +418 -0
  9. package/dist/chunks/{chunk-QPBN3J4E.js → chunk-6BATYA47.js} +2 -2
  10. package/dist/chunks/chunk-77PNP27P.js +92 -0
  11. package/dist/chunks/chunk-7CKGNNTU.js +383 -0
  12. package/dist/chunks/{chunk-X75UGXP3.js → chunk-7QBWHCIZ.js} +1 -1
  13. package/dist/chunks/{chunk-FBL7IVMK.js → chunk-BHE66SP3.js} +14 -14
  14. package/dist/chunks/{chunk-YVG6OKN7.js → chunk-BVV3IA5W.js} +1 -1
  15. package/dist/chunks/chunk-EASGM7W7.js +687 -0
  16. package/dist/chunks/{chunk-GRWUC6H7.js → chunk-IIIAUDGW.js} +1 -1
  17. package/dist/chunks/{chunk-GH3KBC2H.js → chunk-N7HIJNJH.js} +1 -1
  18. package/dist/chunks/{chunk-THZVJ6R7.js → chunk-NGOPE4KK.js} +10 -10
  19. package/dist/chunks/chunk-NK5AWGNW.js +319 -0
  20. package/dist/chunks/{chunk-7XSZVOG7.js → chunk-UNRHTOT5.js} +134 -133
  21. package/dist/chunks/{chunk-5CIKWSCA.js → chunk-YMNFQ7SQ.js} +2 -2
  22. package/dist/chunks/{chunk-AGZNXFHZ.js → chunk-ZGZLSKN6.js} +214 -213
  23. package/dist/chunks/{chunk-PKPBII4F.js → chunk-ZKEXHAXA.js} +238 -239
  24. package/dist/chunks/{chunk-OSQIYUGD.js → chunk-ZMGATMXN.js} +121 -122
  25. package/dist/chunks/{client-OVYKC3ND.js → client-4IOUU4U3.js} +1 -1
  26. package/dist/chunks/compaction-config-2DTN3OHT.js +2 -0
  27. package/dist/chunks/{construction-bootstrap-QVLJPFTL.js → construction-bootstrap-BL56XTNW.js} +1 -1
  28. package/dist/chunks/dist-B4CB7KHY.js +2 -0
  29. package/dist/chunks/{dist-WNMK42WE.js → dist-ITTXQHRJ.js} +1 -1
  30. package/dist/chunks/host-7747QS3X.js +2 -0
  31. package/dist/chunks/run-manager-NLNMI3P2.js +2 -0
  32. package/dist/chunks/{utils-HPVZCR2J.js → utils-CGGQLMJS.js} +1 -1
  33. package/dist/index.d.ts +10 -10
  34. package/dist/index.js +2 -2
  35. package/dist/kodax_bootstrap.js +1 -1
  36. package/dist/kodax_cli.js +1554 -1384
  37. package/dist/runtime-worker.js +1562 -1392
  38. package/dist/sandbox-workspace-session.js +429 -260
  39. package/dist/sdk-a2a.d.ts +6 -6
  40. package/dist/sdk-a2a.js +1 -1
  41. package/dist/sdk-agent.d.ts +17 -6
  42. package/dist/sdk-agent.js +1 -1
  43. package/dist/sdk-coding.d.ts +32 -15
  44. package/dist/sdk-coding.js +1 -1
  45. package/dist/sdk-experimental-memory.js +1 -1
  46. package/dist/sdk-llm.js +1 -1
  47. package/dist/sdk-mcp.js +1 -1
  48. package/dist/sdk-media.js +1 -1
  49. package/dist/sdk-repl.d.ts +32 -14
  50. package/dist/sdk-repl.js +2 -2
  51. package/dist/sdk-runtime.d.ts +31 -8
  52. package/dist/sdk-runtime.js +1 -1
  53. package/dist/sdk-sandbox.d.ts +7 -0
  54. package/dist/sdk-sandbox.js +1 -1
  55. package/dist/sdk-session.d.ts +4 -4
  56. package/dist/sdk-session.js +1 -1
  57. package/dist/sdk-skills.d.ts +2 -333
  58. package/dist/sdk-skills.js +1 -1
  59. package/dist/semantic-worker.js +61 -60
  60. package/dist/types-chunks/{bash-prefix-extractor.d-BMi_TJIY.d.ts → bash-prefix-extractor.d-AOJdvO4r.d.ts} +53 -3
  61. package/dist/types-chunks/{guardrail.d-CKkoea7y.d.ts → guardrail.d-D8RyuTrv.d.ts} +1 -1
  62. package/dist/types-chunks/{public-api.d-BsZWOq3P.d.ts → public-api.d-BNmLxGnR.d.ts} +1 -1
  63. package/dist/types-chunks/{repl.d-DxD0Olm0.d.ts → repl.d-Q6Z3lV2-.d.ts} +4 -4
  64. package/dist/types-chunks/{sdk-session-BTzblJTQ.d.ts → sdk-session-BwC_i6JB.d.ts} +1 -1
  65. package/dist/types-chunks/sdk-skills-Bg1yL4i4.d.ts +335 -0
  66. package/dist/types-chunks/{shell-command-sets.d-C2cc9Hwi.d.ts → shell-command-sets.d-hkYPr4Dy.d.ts} +1 -1
  67. package/dist/types-chunks/{types.d-Dc3kwcjC.d.ts → types.d-Bdv2JoiC.d.ts} +12 -1
  68. package/dist/types-chunks/{types.d-DrtP1ceI.d.ts → types.d-CzrUifXB.d.ts} +1 -1
  69. package/dist/types-chunks/{types.d-BEMcUOng.d.ts → types.d-ssh6zRaf.d.ts} +5 -4
  70. package/dist/types-chunks/{utils.d-50Q24Few.d.ts → utils.d-Buv_Gxhi.d.ts} +3 -3
  71. package/package.json +1 -1
  72. package/dist/chunks/argument-completer-6ZTRBNZM.js +0 -2
  73. package/dist/chunks/chunk-A6GNPNGB.js +0 -383
  74. package/dist/chunks/chunk-BV3SVH36.js +0 -519
  75. package/dist/chunks/chunk-QFV6YCIH.js +0 -92
  76. package/dist/chunks/chunk-QKLS4BYA.js +0 -320
  77. package/dist/chunks/chunk-RJIYXB62.js +0 -415
  78. package/dist/chunks/compaction-config-2TVSYSB4.js +0 -2
  79. package/dist/chunks/dist-XC5M7UYX.js +0 -2
  80. package/dist/chunks/host-B3TK2U43.js +0 -2
  81. package/dist/chunks/run-manager-5AV3MR4W.js +0 -2
package/CHANGELOG.md CHANGED
@@ -8,6 +8,131 @@ All notable changes to this project will be documented in this file.
8
8
 
9
9
  ---
10
10
 
11
+ ## [0.7.94] - 2026-08-21
12
+
13
+ ### Changed
14
+
15
+ - Runtime capability negotiation and pre-start SDK facts now advertise
16
+ `conversationHistory:2` only when
17
+ ordinary history is topology-transparent across managed context and direct
18
+ clone provenance is preserved. Embedders can require v2 to reject stale daemon
19
+ processes that still expose the legacy projection contract. Auto-start replaces
20
+ an idle v1 daemon and fails closed while an incompatible daemon is busy.
21
+ - Skill invocation now has an explicit source contract across CLI, REPL, SDK,
22
+ Runtime, Workflow, and child-Agent paths. Every enabled Skill remains
23
+ explicitly invocable; `disable-model-invocation: true` only removes it from
24
+ model discovery and blocks the model `skill` tool. The legacy
25
+ `user-invocable` field remains parse-compatible but is no longer an execution
26
+ permission.
27
+ - The public README files, package SDK guides, Embedder Guide, public sandbox
28
+ guide, HLD/DD, `kodax_manual` commands/skills topics, skill-creator
29
+ authoring contract, and Runtime SDK type comments now document the same Skill
30
+ catalog, slash-argument, provenance, child-delegation, Run-settlement,
31
+ typed-disconnect, safe-failure, and exact-`runId` recovery contracts.
32
+
33
+ ### Fixed
34
+
35
+ - Sandboxed text-mutation helper stdin failures are now observed by the
36
+ operation Promise instead of escaping as process-level stream errors.
37
+ Linked-worktree and submodule relationship files are read through strict
38
+ byte bounds before external Git metadata earns sandbox trust.
39
+ - Explicit Skill runtime policy now diagnoses invalid `allowed-tools` entries
40
+ and malformed hook JSON. `PostToolUse` still runs when an embedder's base
41
+ result observer throws, while preserving that observer failure for its
42
+ caller.
43
+
44
+ - Scheduled Runtime daemon shutdown now rejects the public host lifecycle when
45
+ cleanup fails, while retaining an internal rejection observer so embedded
46
+ hosts do not emit an unhandled rejection. CLI stop persists and reports the
47
+ matching failed shutdown outcome instead of claiming a safe stop.
48
+ - Worktree Git process-tree drain now returns a bounded error when completion
49
+ remains unprovable, while leaving the namespace lease fail-closed. Successful
50
+ `insert_after_anchor` mutations also refresh the content-hash cache so the
51
+ next edit is not falsely rejected as stale.
52
+ - Windows sandbox Git trust now removes ASRT wildcard `safe.directory` entries
53
+ even when no authorized root survives, rejects malformed `GIT_CONFIG_*`
54
+ shapes, and generates broker and bundled rewriting from one implementation.
55
+ Linked-worktree metadata must prove its backlink before the main `.git` earns
56
+ read trust; repository-bearing metadata read roots join the exact trust set
57
+ (Issue 300).
58
+ - Long-running and background Bash processes no longer block Runtime `write`,
59
+ `edit`, `multi_edit`, `insert_after_anchor`, or `undo` solely because a shell
60
+ lease is alive. Those tools now perform both snapshot and identity-aware
61
+ optimistic compare-and-write through the same ASRT workspace policy, while
62
+ preserving same-path FIFO ordering. Sandbox failure for a covered workspace
63
+ target fails closed; non-workspace targets, standalone/other host filesystem
64
+ sinks, incompatible Windows ACL policies, and worktree namespace changes
65
+ retain their existing safety fences. Runtime non-workspace host writes also
66
+ reject symlink/junction-routed and hard-linked targets inside that fence.
67
+ - Sandboxed text backup authority is minted from the helper's opened file
68
+ identity, preserving stable alias undo without trusting concurrent host
69
+ `realpath`. A permanently rejected Windows Job drain proof now reports the
70
+ error and keeps the worktree namespace fence fail-closed instead of polling
71
+ a settled promise forever or trusting a root-only process check.
72
+ - Sandboxed text mutations now reject hard-linked targets at snapshot and
73
+ commit, reject canonical backup identities outside the workspace capability,
74
+ and preserve the winning undo record when two lexical aliases race. POSIX
75
+ workspace-session startup no longer conflicts with unrelated live shell
76
+ policies because its sandbox policy is process-local; Windows retains its
77
+ shared-account ACL transition fence.
78
+ - Runtime start omits the concurrent text-mutation sandbox when the workspace
79
+ directory does not exist yet, instead of aborting option construction.
80
+ - Run terminal convergence now observes every finalization rejection. A durable
81
+ terminal status remains authoritative if only event publication fails; when
82
+ neither terminal record can be persisted, the public Run resolves as
83
+ `unknown` with `run_settlement_not_persisted` and the Session execution fence
84
+ remains closed instead of escalating the rejection to the daemon process.
85
+ - Workspace-sandbox and managed-child emergency termination promises are now
86
+ observed and retain fail-closed diagnostics when process-tree drain cannot be
87
+ confirmed. Daemon transport disconnects expose typed connection facts, reject
88
+ oversized outbound frames before socket write, and credential-safe terminals
89
+ preserve a bounded `failureKind` without persisting provider error text.
90
+ - Explicit `/<name>` and `/skill:<name>` tokens now resolve at the query head or
91
+ middle, preserve suffix arguments, and use the same host-owned expansion,
92
+ hooks, and permission pipeline in Classic, Ink, non-interactive CLI, queued
93
+ follow-ups, isolated Runtime, and terminal SDK helpers. Low-level
94
+ `SkillRegistry.invoke()` remains an explicit load/resolve primitive; SDK hosts
95
+ that need lifecycle hooks and permission admission use
96
+ `prepareInvocationExecution`. Expanded Skill content enters the provider
97
+ request exactly once.
98
+ - A structured host `skillInvocation` now propagates an active explicit Skill to
99
+ Workflow children, while model-authored child objectives must use the
100
+ governed model tool and cannot bypass `disable-model-invocation` by writing a
101
+ slash token or forged Skill block.
102
+ - The publish-tarball regression test now honors the standard `npm_execpath`
103
+ supplied by npm-compatible test launchers. The Windows optional-ASRT test
104
+ verifies the additional unrepresentable-path fallback without assuming that
105
+ local ASRT containment is always available.
106
+
107
+ ---
108
+
109
+ ## [0.7.93] - 2026-08-19
110
+
111
+ ### Fixed
112
+
113
+ - Runtime exit settlement no longer spends the 170-second orderly Windows
114
+ daemon-exit window after the exact owner has already persisted a terminal
115
+ `failed` shutdown outcome. Settlement observes that durable evidence while
116
+ waiting for process exit and enters the existing exact PID/start-identity,
117
+ Job-containment, and ACL-recovery path immediately. Slow cleanup without a
118
+ terminal failure still keeps the full budget; POSIX behavior is unchanged.
119
+ - Runtime exit settlement now recovers Windows sandbox ACL markers from multiple
120
+ owners only after a changed boot identity and a machine-lock recheck prove
121
+ that every marker has a canonical non-current boot identity. Recovery is
122
+ durably recorded with the recovery boot before marker removal. A further
123
+ reboot repeats native recovery before clear; same-boot, mixed, unreadable, or
124
+ identity-free markers remain fail-closed, and the path never enters sandbox
125
+ provisioning or elevation.
126
+ - Anthropic and OpenAI SDK abort wrappers whose runtime `name` remains `Error`
127
+ are now recognized by their lazily loaded `APIUserAbortError` class identity
128
+ when the request signal is already aborted. Each SDK load is isolated, so a
129
+ missing or broken sibling package cannot replace the original error.
130
+ Managed Runtime Stop therefore retains its trusted interrupted terminal
131
+ cause before run-scoped credential redaction, without reclassifying
132
+ independent same-message Provider failures.
133
+
134
+ ---
135
+
11
136
  ## [0.7.92] - 2026-08-18
12
137
 
13
138
  ### Fixed
package/README.md CHANGED
@@ -113,7 +113,7 @@ you.
113
113
  </td>
114
114
  <td align="center" valign="top">
115
115
  <h3>🧩 Skills + self-construction</h3>
116
- <sub>Markdown skills, NL triggers</sub>
116
+ <sub>Markdown Skills, model-visible NL discovery, explicit slash invocation</sub>
117
117
  <br><br>
118
118
  5-stage self-modification staircase (scaffold → validate → stage → test → activate) gated by an 8-invariant admission contract.
119
119
  </td>
@@ -726,6 +726,41 @@ permission UI, and recovers stale prepared Session tails through an
726
726
  authoritative merge. Background persistence failures are surfaced as
727
727
  diagnostics rather than hidden.
728
728
 
729
+ **v0.7.94 release:** Runtime text tools may overlap a compatible live Bash
730
+ lease because snapshot and commit run through the same ASRT workspace policy.
731
+ Hard-linked workspace targets are rejected. Windows sandboxed git trusts
732
+ authorized repo roots only and never emits `safe.directory=*` (Issue 300).
733
+ Linked-worktree and submodule relationship files are read through strict byte
734
+ bounds before that git trust is granted. Sandboxed text-helper stdin failures
735
+ stay on the operation Promise. Scheduled daemon shutdown reports failed
736
+ cleanup instead of a safe stop.
737
+ A missing workspace directory omits the concurrent text sandbox at Run start.
738
+ Runtime advertises `conversationHistory:2`. Explicit Skill invocation
739
+ (`/<name>`, `/skill:<name>`) remains available for every enabled Skill;
740
+ `disable-model-invocation` only blocks the model tool path. Invalid
741
+ `allowed-tools` entries and malformed hook JSON are diagnosed; `PostToolUse`
742
+ still runs if an embedder result observer throws. Every Run
743
+ finalization and sandbox/managed-child termination rejection is observed. If
744
+ neither terminal record can be persisted, the Run resolves `unknown` with
745
+ `run_settlement_not_persisted` and keeps the Session fenced. Daemon connection
746
+ loss exposes a typed code, `connectionId`, and `reconnectable` fact. Once a
747
+ host receives a `runId`, it must retain it and, after reconnecting, call
748
+ `runs.get(runId)` then `runs.await(runId)` on the replacement Runtime. It must
749
+ never replay `runs.start()` for that admitted Run. Capability versions
750
+ `sandboxRuntime:4` and `crashOutcomeModel:2` are unchanged. Issue 256 remains
751
+ open. See the
752
+ [v0.7.94 release checklist](docs/release.md#v0794-release-preparation)
753
+ and [SDK Embedder Guide](public_docs/sdk/embedder-guide.md#query-authoritative-session-and-run-lifecycle).
754
+
755
+ **v0.7.93 release:** Runtime exit settlement no longer spends the 170-second
756
+ Windows orderly-exit window after a durable `failed` shutdown outcome, can
757
+ recover previous-boot shared ACL markers after a verified boot change, and
758
+ keeps managed Stop interrupted when an Anthropic or OpenAI abort wrapper
759
+ does not carry the `APIUserAbortError` runtime name. Capability versions are
760
+ unchanged. Issue 256 remains open. See the
761
+ [v0.7.93 release checklist](docs/release.md#v0793-release-preparation)
762
+ and [SDK Embedder Guide](public_docs/sdk/embedder-guide.md).
763
+
729
764
  **v0.7.92 release:** the filesystem-effect coordinator now gives each
730
765
  queue attempt an exact token and heartbeat. It can reclaim a stale same-daemon
731
766
  ticket only when that token no longer owns the coordinator lock, and durable
@@ -1613,28 +1648,33 @@ described under FEATURE_272 above.
1613
1648
 
1614
1649
  ### `@kodax-ai/kodax/skills` — Skills System
1615
1650
 
1616
- Zero external dependencies. Markdown-based skill files with natural-language triggers and variable resolution.
1651
+ Markdown-based skill files with natural-language triggers, explicit slash invocation, and variable resolution.
1617
1652
 
1618
1653
  ```typescript
1619
1654
  import {
1620
1655
  SkillRegistry,
1621
- discoverSkills,
1622
- executeSkill,
1623
1656
  type SkillContext,
1624
1657
  } from '@kodax-ai/kodax/skills';
1625
1658
 
1626
- const skills = await discoverSkills(['/path/to/skills']);
1627
- const registry = new SkillRegistry();
1628
- await registry.registerSkills(skills);
1629
-
1630
- const result = await executeSkill({
1631
- skillId: 'code-review',
1632
- arguments: { target: 'src/' },
1633
- workingDirectory: process.cwd(),
1659
+ const registry = new SkillRegistry(process.cwd(), {
1660
+ projectPaths: ['/path/to/skills'],
1634
1661
  });
1662
+ await registry.discover();
1663
+
1664
+ const context: SkillContext = { workingDirectory: process.cwd() };
1665
+ const modelCatalog = registry.getSystemPromptSnippet(); // Excludes model-disabled Skills.
1666
+ const result = await registry.invoke('code-review', 'src/', context);
1635
1667
  ```
1636
1668
 
1637
- **Key Features**: zero deps · markdown-based skill files · natural-language triggering · variable resolution · built-in skills included.
1669
+ 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.
1670
+
1671
+ Explicit invocation is expanded by the host and injected once as structured
1672
+ `skillInvocation` context. Workflow and child Agents inherit that active Skill.
1673
+ A slash reference authored only inside a model-generated child objective is a
1674
+ new model invocation, so it must pass through the governed `skill` tool and
1675
+ cannot elevate a `disable-model-invocation` Skill.
1676
+
1677
+ **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.
1638
1678
 
1639
1679
  ### `@kodax-ai/kodax/coding` — Coding Agent
1640
1680
 
@@ -1821,18 +1861,23 @@ KodaX ships 50+ built-in tools, grouped below. They are registered as a single f
1821
1861
 
1822
1862
  ## Skills System
1823
1863
 
1824
- KodaX includes a built-in Skills system that can be triggered by natural language:
1864
+ KodaX includes a built-in Skills system. Model-visible Skills can be triggered
1865
+ by natural language; every enabled Skill can be invoked explicitly:
1825
1866
 
1826
1867
  ```bash
1827
1868
  # Natural language triggering (no explicit /skill needed)
1828
1869
  kodax "帮我审查代码" # Triggers code-review skill
1829
- kodax "写测试用例" # Triggers tdd skill
1830
- kodax "提交代码" # Triggers git-workflow skill
1870
+ kodax "创建一个新的 KodaX Skill" # Triggers skill-creator
1831
1871
 
1832
- # Explicit skill command
1833
- kodax /skill:code-review
1872
+ # Explicit skill commands (arguments may follow the token)
1873
+ kodax /code-review src/
1874
+ kodax /tdd packages/repl/src/
1875
+ kodax /git-workflow commit
1876
+ kodax "please use /skill:code-review src/"
1834
1877
  ```
1835
1878
 
1879
+ 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>`.
1880
+
1836
1881
  Built-in skills include:
1837
1882
  - **code-review** - Code review and quality analysis
1838
1883
  - **tdd** - Test-driven development workflow
package/README_CN.md CHANGED
@@ -266,6 +266,35 @@ SDK 系统代码契约更新,但没有放宽 shell/sandbox 的 fail-closed 边
266
266
  `handleRuntimePermissionRequest()` 管理 SDK 权限 UI,并在 prepared Session 尾部遇到
267
267
  `data_changed` 时通过权威 delta 合并恢复;后台持久化失败会显示为诊断,不再静默丢失。
268
268
 
269
+ **v0.7.94 发布**:Runtime 文本工具可以与兼容的长驻/后台 Bash 并发,因为
270
+ snapshot 与 commit 走同一套 ASRT workspace 策略。硬链接工作区目标会被拒绝。
271
+ Windows 沙箱 git 只信任已授权的仓库根,不再发出 `safe.directory=*`(Issue 300)。
272
+ linked-worktree / submodule 关系文件在授予 git trust 前按严格字节上限读取。
273
+ 沙箱文本 helper 的 stdin 失败留在该操作 Promise 上。
274
+ 计划中的 daemon shutdown 在 cleanup 失败时报告失败,而不是声称安全停止。
275
+ 工作区目录尚不存在时,Run 启动会省略并发文本沙箱,而不是中止 option 构造。
276
+ Runtime 广告 `conversationHistory:2`。显式 Skill 调用(`/<name>`、
277
+ `/skill:<name>`)对每个已启用 Skill 始终可用;`disable-model-invocation`
278
+ 只关闭模型工具路径。无效 `allowed-tools` 与畸形 hook JSON 会被诊断;
279
+ embedder 的 result observer 抛错时 `PostToolUse` 仍会运行。所有 Run 终态收敛以及 sandbox / managed-child
280
+ 终止 Promise 都会显式观察 rejection。若两种终态记录都无法持久化,Run 以
281
+ `unknown` + `run_settlement_not_persisted` 收敛,并继续关闭 Session 执行门禁。
282
+ daemon 断线公开 typed code、`connectionId` 和 `reconnectable` 事实。宿主一旦取得
283
+ `runId`,重连后必须在 replacement Runtime 上调用 `runs.get(runId)` 与
284
+ `runs.await(runId)`,绝不能为同一已接纳 Run 再次调用 `runs.start()`。
285
+ `sandboxRuntime:4` 与 `crashOutcomeModel:2` 不变。Issue 256 仍保持 Open。
286
+ 详见 [v0.7.94 发布清单](docs/release.md#v0794-release-preparation) 与
287
+ [SDK Embedder Guide](public_docs/sdk/embedder-guide.md#query-authoritative-session-and-run-lifecycle)。
288
+
289
+ **v0.7.93 发布**:Windows 退出结算在精确 owner 已写入 durable `failed`
290
+ shutdown outcome 后不再空等 170 秒有序窗口,改为立即进入既有精确恢复路径。
291
+ 验证 boot 变化后,可在 machine lock 下回收上一启动留下的共享 ACL marker,
292
+ 并在记录 recovery 之后才清除。Anthropic/OpenAI 的 abort 包装在请求 signal
293
+ 已中止时按隔离加载的 SDK class identity 识别,managed Stop 在凭据脱敏前
294
+ 仍保持 interrupted。能力版本不变。Issue 256 仍保持 Open。
295
+ 详见 [v0.7.93 发布清单](docs/release.md#v0793-release-preparation) 与
296
+ [SDK Embedder Guide](public_docs/sdk/embedder-guide.md)。
297
+
269
298
  **v0.7.92 发布**:文件系统效应协调器为每次排队使用精确 token 并 heartbeat。
270
299
  只有当该 token 不再持有 coordinator lock 时,才会回收同一长期 daemon PID 上的过期票;
271
300
  durable release marker 允许后续调用退役已结算的 effect owner。精确仍持有的 lock、
@@ -937,6 +966,8 @@ KodaX 有两层结构,SDK 用户需要分开理解:
937
966
 
938
967
  **经验法则**:需要 Runner / Agent / fan-out 时从 `/agent` 引入;只需要 skills 或 mcp API 时从 `/skills` 或 `/mcp` 引入,bundle 更小。窄子集是完整包的真子集 —— **不会**有额外符号。
939
968
 
969
+ 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` 工具,不能借委派绕过该标记。
970
+
940
971
  **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)。
941
972
 
942
973
  **宿主读持久化历史(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)。
@@ -47,6 +47,11 @@ compatibility: "Optimized for KodaX and Agent Skills style directories. Bundled
47
47
  - 大块参考资料放到 `references/`。
48
48
  - 模板或静态文件放到 `assets/`。
49
49
  - 如果某个专家流程只服务这个 skill,可以放进 `agents/`,但先把它当私有 contract,不要自动上升成全局产品概念。
50
+ - `description` 同时决定模型发现。自然语言只会看到未设置 `disable-model-invocation: true` 的 name/description。
51
+ - 需要只在显式 slash 后加载时,写 `disable-model-invocation: true`。这只关闭模型 catalog 与模型 `skill` 工具。
52
+ - 每个已启用 Skill 都接受 `/<name>` 和 `/skill:<name>`。
53
+ - token 可在 query 头部或中间。后续文本是 Skill 参数。
54
+ - `user-invocable` 只保留解析兼容。不要把它当成执行权限:宿主忽略该字段后,作者会误以为 `false` 能禁止 slash/SDK 调用。
50
55
 
51
56
  ### 4. Bundled scripts 默认用 Node.js
52
57
 
@@ -19,6 +19,7 @@ export function renderSkillTemplate(name, description) {
19
19
  name: ${name}
20
20
  description: ${description}
21
21
  user-invocable: true
22
+ disable-model-invocation: false
22
23
  allowed-tools: "Read, Grep, Glob"
23
24
  compatibility: "Optimized for KodaX and Agent Skills style directories."
24
25
  ---
@@ -131,8 +132,8 @@ function parseArgs(argv) {
131
132
  return args;
132
133
  }
133
134
 
134
- export async function main(argv = process.argv) {
135
- const args = parseArgs(argv);
135
+ export async function main(argv = process.argv) {
136
+ const args = parseArgs(argv);
136
137
  if (!args.name) {
137
138
  console.error('Usage: node scripts/init-skill.js <skill-name> [--path <skills-dir>] [--description <text>] [--force] [--no-evals]');
138
139
  process.exit(1);
@@ -142,8 +143,8 @@ export async function main(argv = process.argv) {
142
143
  console.log(`Initialized ${result.skillDir}`);
143
144
  }
144
145
 
145
- const isDirectRun = process.env.KODAX_MODULE_BUNDLE !== 'true'
146
- && process.argv[1]
146
+ const isDirectRun = process.env.KODAX_MODULE_BUNDLE !== 'true'
147
+ && process.argv[1]
147
148
  && fileURLToPath(import.meta.url) === path.resolve(process.argv[1]);
148
149
 
149
150
  if (isDirectRun) {
@@ -1,2 +1,2 @@
1
1
  // @kodax-ai/kodax — bundled distribution. See docs/ADR.md ADR-022 + ADR-024.
2
- 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-RJIYXB62.js";import"./chunk-X75UGXP3.js";import"./chunk-AGZNXFHZ.js";import"./chunk-GH3KBC2H.js";import"./chunk-YVG6OKN7.js";import"./chunk-FBL7IVMK.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};
2
+ 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};
@@ -0,0 +1,2 @@
1
+ // @kodax-ai/kodax — bundled distribution. See docs/ADR.md ADR-022 + ADR-024.
2
+ 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};