@linnlabs/linnkit 0.8.0 → 0.10.0

package/CHANGELOG.md

@@ -14,6 +14,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.10.0] - 2026-06-15
+
+### Changed
+
+- `GraphExecutor` / `Checkpointer` now name engine-state snapshot keys as `checkpointKey`, and graph telemetry reads the runtime `conversationId` from graph local state instead of treating the checkpoint key as a host conversation.
+- Synchronous child runs can now receive an explicit host `conversationId` while still using an internal checkpoint key for GraphExecutor state isolation. This keeps RuntimeEvent / Audit / Telemetry scope aligned with the child run registered by the host and prevents EventStore-backed audit writes from mixing a child `runId` with an internal conversation key.
+- `copyToolContextRuntimeCapability` is now exported from `@linnlabs/linnkit/runtime-kernel` so child-run tool contexts can preserve the parent tool runtime binding without manually copying reserved fields.
+- Detached runs now execute against the `AgentSpec`, request, and metadata snapshots captured during `spawnDetached()` registration, so later caller-side object mutations cannot change the background run context.
+
+### Compatibility
+
+- Minor bump because `Checkpointer` / `CheckpointMeta` host adapter contracts now use `checkpointKey` for graph persistence identity. Host adapters that previously treated the graph checkpoint key as a user conversation id should pass host `conversationId` explicitly and reserve `checkpointKey` for engine snapshots.
+
+---
+
+## [0.9.0] - 2026-05-22
+
+### Added
+
+- `appendStreamingProviderReasoningDetails` / `compactProviderReasoningDetails` / `compactReasoningDetailsInValue` in `@linnlabs/linnkit/runtime-kernel` — provider-agnostic helpers for merging adjacent streaming `reasoning_content` fragments.
+
+### Fixed
+
+- Streaming `reasoning_details` now merges adjacent pure text reasoning fragments before returning the final LLM result and before emitting provider sidecar updates, preventing audit records from storing token-by-token reasoning fragments.
+- `ToolNode` now drains every pending `assistant.tool_calls` item in the current batch before returning to the LLM, even when an earlier tool call fails. This preserves the protocol invariant that each tool call receives a corresponding tool output and avoids incomplete tool-call groups being dropped by downstream context assembly.
+- Tool protocol fuse handling now waits until the current batch has been fully consumed before throwing, so one repeated protocol error cannot strand later tool calls in the same assistant message.
+
+### Compatibility
+
+- Minor bump because `@linnlabs/linnkit/runtime-kernel` has new public exports and ToolNode batch execution behavior is stricter.
+
 ---
 
 ## [0.8.0] - 2026-05-13

package/README.md

@@ -1,6 +1,6 @@
 # linnkit
 
-**A fine-grained context engineering framework for Agent applications — control every token sent to the model, with clear run lifecycle, audit records, and testable protocol boundaries.**
+**A fine-grained context engineering framework for Agent applications — control every token sent to the model, with clear run lifecycle, audit records, and testable protocol boundaries.** It gives a small, auditable runtime for controlling the messages, tool results, summaries, and policies that shape every LLM call.
 
 [中文文档](./README.zh-CN.md) · [Integration Guide](./docs/integration/README.md) · [Changelog](./CHANGELOG.md)
 

package/README.zh-CN.md

@@ -1,6 +1,6 @@
 # linnkit
 
-**linnkit 是一个可以方便地精细化管理上下文的 Agent 框架，追求控制发给LLM的每一个 token，同时保留清晰的运行生命周期、审计记录和测试边界。**
+**linnkit 是一个可以方便地精细化管理上下文的 Agent 框架，追求控制发给LLM的每一个 token，同时保留清晰的运行生命周期、审计记录和测试边界。** 它提供了一种小巧、可审计的运行时环境，可对消息、工具结果、摘要及策略进行管控，而正是这些要素决定了每一次大语言模型调用的行为。
 
 [English](./README.md) · [接入文档](./docs/integration/README.md) · [更新日志](./CHANGELOG.md)
 

package/bin/linnkit.cjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+
+const { runCli } = require('../dist/cli.cjs');
+
+void runCli(process.argv.slice(2)).then((exitCode) => {
+  process.exitCode = exitCode;
+});

package/dist/{agentSpec-EkmviZjy.d.cts → agentSpec-Du4Iye0q.d.cts}

@@ -21,6 +21,7 @@ declare const AgentSpecBudgetPolicy: z.ZodObject<{
 type AgentSpecBudgetPolicy = z.infer<typeof AgentSpecBudgetPolicy>;
 declare const AgentSpecToolHistoryPolicy: z.ZodObject<{
     strategy: z.ZodOptional<z.ZodEnum<["per-pair", "per-run", "none"]>>;
+    retentionMode: z.ZodOptional<z.ZodEnum<["drop", "compress"]>>;
     keepLatestToolPairs: z.ZodOptional<z.ZodNumber>;
     keepLatestRuns: z.ZodOptional<z.ZodNumber>;
     maxInteractionGroups: z.ZodOptional<z.ZodNumber>;
@@ -29,6 +30,7 @@ declare const AgentSpecToolHistoryPolicy: z.ZodObject<{
     maxOutputSummaryTokens: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
     strategy?: "per-pair" | "per-run" | "none" | undefined;
+    retentionMode?: "drop" | "compress" | undefined;
     keepLatestToolPairs?: number | undefined;
     keepLatestRuns?: number | undefined;
     maxInteractionGroups?: number | undefined;
@@ -37,6 +39,7 @@ declare const AgentSpecToolHistoryPolicy: z.ZodObject<{
     maxOutputSummaryTokens?: number | undefined;
 }, {
     strategy?: "per-pair" | "per-run" | "none" | undefined;
+    retentionMode?: "drop" | "compress" | undefined;
     keepLatestToolPairs?: number | undefined;
     keepLatestRuns?: number | undefined;
     maxInteractionGroups?: number | undefined;
@@ -537,6 +540,7 @@ declare const AgentSpecContextPolicy: z.ZodObject<{
     }>>;
     toolHistory: z.ZodOptional<z.ZodObject<{
         strategy: z.ZodOptional<z.ZodEnum<["per-pair", "per-run", "none"]>>;
+        retentionMode: z.ZodOptional<z.ZodEnum<["drop", "compress"]>>;
         keepLatestToolPairs: z.ZodOptional<z.ZodNumber>;
         keepLatestRuns: z.ZodOptional<z.ZodNumber>;
         maxInteractionGroups: z.ZodOptional<z.ZodNumber>;
@@ -545,6 +549,7 @@ declare const AgentSpecContextPolicy: z.ZodObject<{
         maxOutputSummaryTokens: z.ZodOptional<z.ZodNumber>;
     }, "strip", z.ZodTypeAny, {
         strategy?: "per-pair" | "per-run" | "none" | undefined;
+        retentionMode?: "drop" | "compress" | undefined;
         keepLatestToolPairs?: number | undefined;
         keepLatestRuns?: number | undefined;
         maxInteractionGroups?: number | undefined;
@@ -553,6 +558,7 @@ declare const AgentSpecContextPolicy: z.ZodObject<{
         maxOutputSummaryTokens?: number | undefined;
     }, {
         strategy?: "per-pair" | "per-run" | "none" | undefined;
+        retentionMode?: "drop" | "compress" | undefined;
         keepLatestToolPairs?: number | undefined;
         keepLatestRuns?: number | undefined;
         maxInteractionGroups?: number | undefined;
@@ -906,6 +912,7 @@ declare const AgentSpecContextPolicy: z.ZodObject<{
     } | undefined;
     toolHistory?: {
         strategy?: "per-pair" | "per-run" | "none" | undefined;
+        retentionMode?: "drop" | "compress" | undefined;
         keepLatestToolPairs?: number | undefined;
         keepLatestRuns?: number | undefined;
         maxInteractionGroups?: number | undefined;
@@ -999,6 +1006,7 @@ declare const AgentSpecContextPolicy: z.ZodObject<{
     } | undefined;
     toolHistory?: {
         strategy?: "per-pair" | "per-run" | "none" | undefined;
+        retentionMode?: "drop" | "compress" | undefined;
         keepLatestToolPairs?: number | undefined;
         keepLatestRuns?: number | undefined;
         maxInteractionGroups?: number | undefined;
@@ -1186,6 +1194,7 @@ declare const AgentSpec: z.ZodObject<{
         }>>;
         toolHistory: z.ZodOptional<z.ZodObject<{
             strategy: z.ZodOptional<z.ZodEnum<["per-pair", "per-run", "none"]>>;
+            retentionMode: z.ZodOptional<z.ZodEnum<["drop", "compress"]>>;
             keepLatestToolPairs: z.ZodOptional<z.ZodNumber>;
             keepLatestRuns: z.ZodOptional<z.ZodNumber>;
             maxInteractionGroups: z.ZodOptional<z.ZodNumber>;
@@ -1194,6 +1203,7 @@ declare const AgentSpec: z.ZodObject<{
             maxOutputSummaryTokens: z.ZodOptional<z.ZodNumber>;
         }, "strip", z.ZodTypeAny, {
             strategy?: "per-pair" | "per-run" | "none" | undefined;
+            retentionMode?: "drop" | "compress" | undefined;
             keepLatestToolPairs?: number | undefined;
             keepLatestRuns?: number | undefined;
             maxInteractionGroups?: number | undefined;
@@ -1202,6 +1212,7 @@ declare const AgentSpec: z.ZodObject<{
             maxOutputSummaryTokens?: number | undefined;
         }, {
             strategy?: "per-pair" | "per-run" | "none" | undefined;
+            retentionMode?: "drop" | "compress" | undefined;
             keepLatestToolPairs?: number | undefined;
             keepLatestRuns?: number | undefined;
             maxInteractionGroups?: number | undefined;
@@ -1987,6 +1998,7 @@ declare const AgentSpec: z.ZodObject<{
         } | undefined;
         toolHistory?: {
             strategy?: "per-pair" | "per-run" | "none" | undefined;
+            retentionMode?: "drop" | "compress" | undefined;
             keepLatestToolPairs?: number | undefined;
             keepLatestRuns?: number | undefined;
             maxInteractionGroups?: number | undefined;
@@ -2128,6 +2140,7 @@ declare const AgentSpec: z.ZodObject<{
         } | undefined;
         toolHistory?: {
             strategy?: "per-pair" | "per-run" | "none" | undefined;
+            retentionMode?: "drop" | "compress" | undefined;
             keepLatestToolPairs?: number | undefined;
             keepLatestRuns?: number | undefined;
             maxInteractionGroups?: number | undefined;
@@ -2305,6 +2318,7 @@ declare const AgentSpec: z.ZodObject<{
         } | undefined;
         toolHistory?: {
             strategy?: "per-pair" | "per-run" | "none" | undefined;
+            retentionMode?: "drop" | "compress" | undefined;
             keepLatestToolPairs?: number | undefined;
             keepLatestRuns?: number | undefined;
             maxInteractionGroups?: number | undefined;
@@ -2470,6 +2484,7 @@ declare const AgentSpec: z.ZodObject<{
         } | undefined;
         toolHistory?: {
             strategy?: "per-pair" | "per-run" | "none" | undefined;
+            retentionMode?: "drop" | "compress" | undefined;
             keepLatestToolPairs?: number | undefined;
             keepLatestRuns?: number | undefined;
             maxInteractionGroups?: number | undefined;
@@ -2618,4 +2633,4 @@ declare const AgentSpec: z.ZodObject<{
 }>;
 type AgentSpec = z.infer<typeof AgentSpec>;
 
-export { AgentCapability as A, SYSTEM_REMINDER_BUILTIN_TRIGGER_KINDS as S, ToolBindingSpec as T, AgentSpec as a, AgentSpecAuditConfig as b, AgentSpecBudgetPolicy as c, AgentSpecCheckpointPolicy as d, AgentSpecContextPolicy as e, type AgentSpecContextPolicyInput as f, AgentSpecContextTracePolicy as g, AgentSpecMessageType as h, AgentSpecModelHints as i, AgentSpecMustKeepPolicy as j, AgentSpecMustKeepTruncationRule as k, AgentSpecProviderReplayPolicy as l, AgentSpecReasoningRetentionPolicy as m, AgentSpecSummarizationPolicy as n, AgentSpecSystemReminderExtraRule as o, AgentSpecSystemReminderPolicy as p, AgentSpecSystemReminderTrigger as q, AgentSpecTokenEstimationPolicy as r, AgentSpecToolHistoryPolicy as s, AgentSpecToolObservationGovernancePolicy as t, AgentSpecToolOutputPolicy as u, AgentSpecWorkingMemoryPolicy as v, defineContextPolicy as w };
+export { AgentSpecToolOutputPolicy as A, SYSTEM_REMINDER_BUILTIN_TRIGGER_KINDS as S, ToolBindingSpec as T, AgentSpecProviderReplayPolicy as a, AgentSpecCheckpointPolicy as b, AgentSpecSummarizationPolicy as c, AgentSpecContextTracePolicy as d, AgentSpecSystemReminderPolicy as e, AgentSpec as f, AgentSpecContextPolicy as g, type AgentSpecContextPolicyInput as h, AgentCapability as i, AgentSpecAuditConfig as j, AgentSpecBudgetPolicy as k, AgentSpecMessageType as l, AgentSpecModelHints as m, AgentSpecMustKeepPolicy as n, AgentSpecMustKeepTruncationRule as o, AgentSpecReasoningRetentionPolicy as p, AgentSpecSystemReminderExtraRule as q, AgentSpecSystemReminderTrigger as r, AgentSpecTokenEstimationPolicy as s, AgentSpecToolHistoryPolicy as t, AgentSpecToolObservationGovernancePolicy as u, AgentSpecWorkingMemoryPolicy as v, defineContextPolicy as w };

package/dist/{agentSpec-EkmviZjy.d.ts → agentSpec-Du4Iye0q.d.ts}

@@ -21,6 +21,7 @@ declare const AgentSpecBudgetPolicy: z.ZodObject<{
 type AgentSpecBudgetPolicy = z.infer<typeof AgentSpecBudgetPolicy>;
 declare const AgentSpecToolHistoryPolicy: z.ZodObject<{
     strategy: z.ZodOptional<z.ZodEnum<["per-pair", "per-run", "none"]>>;
+    retentionMode: z.ZodOptional<z.ZodEnum<["drop", "compress"]>>;
     keepLatestToolPairs: z.ZodOptional<z.ZodNumber>;
     keepLatestRuns: z.ZodOptional<z.ZodNumber>;
     maxInteractionGroups: z.ZodOptional<z.ZodNumber>;
@@ -29,6 +30,7 @@ declare const AgentSpecToolHistoryPolicy: z.ZodObject<{
     maxOutputSummaryTokens: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
     strategy?: "per-pair" | "per-run" | "none" | undefined;
+    retentionMode?: "drop" | "compress" | undefined;
     keepLatestToolPairs?: number | undefined;
     keepLatestRuns?: number | undefined;
     maxInteractionGroups?: number | undefined;
@@ -37,6 +39,7 @@ declare const AgentSpecToolHistoryPolicy: z.ZodObject<{
     maxOutputSummaryTokens?: number | undefined;
 }, {
     strategy?: "per-pair" | "per-run" | "none" | undefined;
+    retentionMode?: "drop" | "compress" | undefined;
     keepLatestToolPairs?: number | undefined;
     keepLatestRuns?: number | undefined;
     maxInteractionGroups?: number | undefined;
@@ -537,6 +540,7 @@ declare const AgentSpecContextPolicy: z.ZodObject<{
     }>>;
     toolHistory: z.ZodOptional<z.ZodObject<{
         strategy: z.ZodOptional<z.ZodEnum<["per-pair", "per-run", "none"]>>;
+        retentionMode: z.ZodOptional<z.ZodEnum<["drop", "compress"]>>;
         keepLatestToolPairs: z.ZodOptional<z.ZodNumber>;
         keepLatestRuns: z.ZodOptional<z.ZodNumber>;
         maxInteractionGroups: z.ZodOptional<z.ZodNumber>;
@@ -545,6 +549,7 @@ declare const AgentSpecContextPolicy: z.ZodObject<{
         maxOutputSummaryTokens: z.ZodOptional<z.ZodNumber>;
     }, "strip", z.ZodTypeAny, {
         strategy?: "per-pair" | "per-run" | "none" | undefined;
+        retentionMode?: "drop" | "compress" | undefined;
         keepLatestToolPairs?: number | undefined;
         keepLatestRuns?: number | undefined;
         maxInteractionGroups?: number | undefined;
@@ -553,6 +558,7 @@ declare const AgentSpecContextPolicy: z.ZodObject<{
         maxOutputSummaryTokens?: number | undefined;
     }, {
         strategy?: "per-pair" | "per-run" | "none" | undefined;
+        retentionMode?: "drop" | "compress" | undefined;
         keepLatestToolPairs?: number | undefined;
         keepLatestRuns?: number | undefined;
         maxInteractionGroups?: number | undefined;
@@ -906,6 +912,7 @@ declare const AgentSpecContextPolicy: z.ZodObject<{
     } | undefined;
     toolHistory?: {
         strategy?: "per-pair" | "per-run" | "none" | undefined;
+        retentionMode?: "drop" | "compress" | undefined;
         keepLatestToolPairs?: number | undefined;
         keepLatestRuns?: number | undefined;
         maxInteractionGroups?: number | undefined;
@@ -999,6 +1006,7 @@ declare const AgentSpecContextPolicy: z.ZodObject<{
     } | undefined;
     toolHistory?: {
         strategy?: "per-pair" | "per-run" | "none" | undefined;
+        retentionMode?: "drop" | "compress" | undefined;
         keepLatestToolPairs?: number | undefined;
         keepLatestRuns?: number | undefined;
         maxInteractionGroups?: number | undefined;
@@ -1186,6 +1194,7 @@ declare const AgentSpec: z.ZodObject<{
         }>>;
         toolHistory: z.ZodOptional<z.ZodObject<{
             strategy: z.ZodOptional<z.ZodEnum<["per-pair", "per-run", "none"]>>;
+            retentionMode: z.ZodOptional<z.ZodEnum<["drop", "compress"]>>;
             keepLatestToolPairs: z.ZodOptional<z.ZodNumber>;
             keepLatestRuns: z.ZodOptional<z.ZodNumber>;
             maxInteractionGroups: z.ZodOptional<z.ZodNumber>;
@@ -1194,6 +1203,7 @@ declare const AgentSpec: z.ZodObject<{
             maxOutputSummaryTokens: z.ZodOptional<z.ZodNumber>;
         }, "strip", z.ZodTypeAny, {
             strategy?: "per-pair" | "per-run" | "none" | undefined;
+            retentionMode?: "drop" | "compress" | undefined;
             keepLatestToolPairs?: number | undefined;
             keepLatestRuns?: number | undefined;
             maxInteractionGroups?: number | undefined;
@@ -1202,6 +1212,7 @@ declare const AgentSpec: z.ZodObject<{
             maxOutputSummaryTokens?: number | undefined;
         }, {
             strategy?: "per-pair" | "per-run" | "none" | undefined;
+            retentionMode?: "drop" | "compress" | undefined;
             keepLatestToolPairs?: number | undefined;
             keepLatestRuns?: number | undefined;
             maxInteractionGroups?: number | undefined;
@@ -1987,6 +1998,7 @@ declare const AgentSpec: z.ZodObject<{
         } | undefined;
         toolHistory?: {
             strategy?: "per-pair" | "per-run" | "none" | undefined;
+            retentionMode?: "drop" | "compress" | undefined;
             keepLatestToolPairs?: number | undefined;
             keepLatestRuns?: number | undefined;
             maxInteractionGroups?: number | undefined;
@@ -2128,6 +2140,7 @@ declare const AgentSpec: z.ZodObject<{
         } | undefined;
         toolHistory?: {
             strategy?: "per-pair" | "per-run" | "none" | undefined;
+            retentionMode?: "drop" | "compress" | undefined;
             keepLatestToolPairs?: number | undefined;
             keepLatestRuns?: number | undefined;
             maxInteractionGroups?: number | undefined;
@@ -2305,6 +2318,7 @@ declare const AgentSpec: z.ZodObject<{
         } | undefined;
         toolHistory?: {
             strategy?: "per-pair" | "per-run" | "none" | undefined;
+            retentionMode?: "drop" | "compress" | undefined;
             keepLatestToolPairs?: number | undefined;
             keepLatestRuns?: number | undefined;
             maxInteractionGroups?: number | undefined;
@@ -2470,6 +2484,7 @@ declare const AgentSpec: z.ZodObject<{
         } | undefined;
         toolHistory?: {
             strategy?: "per-pair" | "per-run" | "none" | undefined;
+            retentionMode?: "drop" | "compress" | undefined;
             keepLatestToolPairs?: number | undefined;
             keepLatestRuns?: number | undefined;
             maxInteractionGroups?: number | undefined;
@@ -2618,4 +2633,4 @@ declare const AgentSpec: z.ZodObject<{
 }>;
 type AgentSpec = z.infer<typeof AgentSpec>;
 
-export { AgentCapability as A, SYSTEM_REMINDER_BUILTIN_TRIGGER_KINDS as S, ToolBindingSpec as T, AgentSpec as a, AgentSpecAuditConfig as b, AgentSpecBudgetPolicy as c, AgentSpecCheckpointPolicy as d, AgentSpecContextPolicy as e, type AgentSpecContextPolicyInput as f, AgentSpecContextTracePolicy as g, AgentSpecMessageType as h, AgentSpecModelHints as i, AgentSpecMustKeepPolicy as j, AgentSpecMustKeepTruncationRule as k, AgentSpecProviderReplayPolicy as l, AgentSpecReasoningRetentionPolicy as m, AgentSpecSummarizationPolicy as n, AgentSpecSystemReminderExtraRule as o, AgentSpecSystemReminderPolicy as p, AgentSpecSystemReminderTrigger as q, AgentSpecTokenEstimationPolicy as r, AgentSpecToolHistoryPolicy as s, AgentSpecToolObservationGovernancePolicy as t, AgentSpecToolOutputPolicy as u, AgentSpecWorkingMemoryPolicy as v, defineContextPolicy as w };
+export { AgentSpecToolOutputPolicy as A, SYSTEM_REMINDER_BUILTIN_TRIGGER_KINDS as S, ToolBindingSpec as T, AgentSpecProviderReplayPolicy as a, AgentSpecCheckpointPolicy as b, AgentSpecSummarizationPolicy as c, AgentSpecContextTracePolicy as d, AgentSpecSystemReminderPolicy as e, AgentSpec as f, AgentSpecContextPolicy as g, type AgentSpecContextPolicyInput as h, AgentCapability as i, AgentSpecAuditConfig as j, AgentSpecBudgetPolicy as k, AgentSpecMessageType as l, AgentSpecModelHints as m, AgentSpecMustKeepPolicy as n, AgentSpecMustKeepTruncationRule as o, AgentSpecReasoningRetentionPolicy as p, AgentSpecSystemReminderExtraRule as q, AgentSpecSystemReminderTrigger as r, AgentSpecTokenEstimationPolicy as s, AgentSpecToolHistoryPolicy as t, AgentSpecToolObservationGovernancePolicy as u, AgentSpecWorkingMemoryPolicy as v, defineContextPolicy as w };