@yolk-sdk/agent 0.1.0-canary.106 → 0.1.0-canary.108

package/README.md

@@ -20,47 +20,47 @@ Published package metadata requires Node.js 22+.
 
 ## Subpaths
 
-| Subpath                                                  | Purpose                                                                                                                      |
-| -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
-| `@yolk-sdk/agent/protocol`                               | Wire messages, events, content, usage, tool schemas                                                                          |
-| `@yolk-sdk/agent/loop`                                   | Stateless LLM/tool loop                                                                                                      |
-| `@yolk-sdk/agent/loop/testing`                           | Faux provider and tool executor test helpers                                                                                 |
-| `@yolk-sdk/agent/runtime`                                | Transcript or append-backed runtime orchestration                                                                            |
-| `@yolk-sdk/agent/client`                                 | HTTP/NDJSON transport, HITL resume, retry/error state helpers                                                                |
-| `@yolk-sdk/agent/compaction`                             | Host-owned compaction budgets, checkpoints, formatting, retry                                                                |
-| `@yolk-sdk/agent/classification`                         | Classifier model contract: typed questions, answers, usage, errors                                                           |
-| `@yolk-sdk/agent/tools`                                  | Tool registry, typed inputs, interactions, subagents/questions, durable tool ledger, staged tool plans, tool change previews |
-| `@yolk-sdk/agent/react`                                  | Headless React chat hook, reducer, selectors, and render model                                                               |
-| `@yolk-sdk/agent/oauth`                                  | Provider-neutral OAuth token and broker contracts                                                                            |
-| `@yolk-sdk/agent/providers/openai`                       | OpenAI/Codex OAuth and broker helpers                                                                                        |
-| `@yolk-sdk/agent/providers/openai/codex`                 | OpenAI Codex request and auth helpers                                                                                        |
-| `@yolk-sdk/agent/providers/openai/codex-usage`           | Codex subscription-allowance snapshots                                                                                       |
-| `@yolk-sdk/agent/providers/openai/codex-provider`        | Codex LLM provider factory                                                                                                   |
-| `@yolk-sdk/agent/providers/openai/provider`              | OpenAI-compatible LLM provider factory                                                                                       |
-| `@yolk-sdk/agent/providers/openai/conformance`           | Synthetic OpenAI chat, Codex Responses, and Codex usage fixtures and conformance cases                                       |
-| `@yolk-sdk/agent/providers/openai/realtime`              | OpenAI Realtime session config and event codecs                                                                              |
-| `@yolk-sdk/agent/providers/openai/speech`                | OpenAI text-to-speech and transcription adapters                                                                             |
-| `@yolk-sdk/agent/providers/vercel/ai-gateway-provider`   | Vercel AI Gateway Chat Completions provider factory                                                                          |
-| `@yolk-sdk/agent/providers/vercel/ai-gateway-classifier` | Vercel AI Gateway classifier (`POST /v1/evaluate`) layer                                                                     |
-| `@yolk-sdk/agent/providers/vercel/conformance`           | Verified Gateway chat fixtures, synthetic classifier fixtures, and conformance cases                                         |
-| `@yolk-sdk/agent/providers/opencode/go-provider`         | OpenCode Go Chat Completions, Messages, and Responses provider                                                               |
-| `@yolk-sdk/agent/providers/opencode/usage`               | OpenCode Go subscription-allowance snapshots                                                                                 |
-| `@yolk-sdk/agent/providers/opencode/conformance`         | Synthetic OpenCode Go (per protocol, commentary replay, usage) fixtures and conformance cases                                |
-| `@yolk-sdk/agent/providers/anthropic`                    | Anthropic/Claude OAuth and broker helpers                                                                                    |
-| `@yolk-sdk/agent/providers/anthropic/claude`             | Claude request and auth helpers                                                                                              |
-| `@yolk-sdk/agent/providers/anthropic/usage`              | Claude subscription-allowance snapshots                                                                                      |
-| `@yolk-sdk/agent/providers/anthropic/claude-provider`    | Claude LLM provider factory                                                                                                  |
-| `@yolk-sdk/agent/providers/anthropic/conformance`        | Synthetic Anthropic Messages and Claude usage fixtures and conformance cases                                                 |
-| `@yolk-sdk/agent/providers/xai`                          | Grok subscription OAuth and token broker helpers                                                                             |
-| `@yolk-sdk/agent/providers/xai/grok`                     | Grok subscription request and auth helpers                                                                                   |
-| `@yolk-sdk/agent/providers/xai/grok-provider`            | Grok subscription LLM provider factory                                                                                       |
-| `@yolk-sdk/agent/providers/xai/usage`                    | Grok subscription-allowance snapshots                                                                                        |
-| `@yolk-sdk/agent/providers/xai/conformance`              | Synthetic Grok Responses and Grok usage fixtures and conformance cases                                                       |
-| `@yolk-sdk/agent/providers/subscription-usage`           | Shared allowance snapshot and safe error schemas                                                                             |
-| `@yolk-sdk/agent/skillset`                               | Portable skill and slash-command parsing/catalogs                                                                            |
-| `@yolk-sdk/agent/voice`                                  | Voice protocol, controller, tool handler, projection, speech                                                                 |
-| `@yolk-sdk/agent/voice/browser`                          | Browser WebRTC voice transport                                                                                               |
-| `@yolk-sdk/agent/voice/react`                            | Headless browser voice React hook                                                                                            |
+| Subpath                                                  | Purpose                                                                                                                                                        |
+| -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@yolk-sdk/agent/protocol`                               | Wire messages, events, content, usage, tool schemas                                                                                                            |
+| `@yolk-sdk/agent/loop`                                   | Stateless LLM/tool loop, host instructions                                                                                                                     |
+| `@yolk-sdk/agent/loop/testing`                           | Faux provider and tool executor test helpers                                                                                                                   |
+| `@yolk-sdk/agent/runtime`                                | Transcript or append-backed runtime orchestration                                                                                                              |
+| `@yolk-sdk/agent/client`                                 | HTTP/NDJSON transport, HITL resume, retry/error state helpers                                                                                                  |
+| `@yolk-sdk/agent/compaction`                             | Host-owned compaction budgets, checkpoints, formatting, retry                                                                                                  |
+| `@yolk-sdk/agent/classification`                         | Classifier model contract: typed questions, answers, usage, errors                                                                                             |
+| `@yolk-sdk/agent/tools`                                  | Tool registry, deferred loading (`tool_search`), typed inputs, interactions, subagents/questions, durable tool ledger, staged tool plans, tool change previews |
+| `@yolk-sdk/agent/react`                                  | Headless React chat hook, reducer, selectors, and render model                                                                                                 |
+| `@yolk-sdk/agent/oauth`                                  | Provider-neutral OAuth token and broker contracts                                                                                                              |
+| `@yolk-sdk/agent/providers/openai`                       | OpenAI/Codex OAuth and broker helpers                                                                                                                          |
+| `@yolk-sdk/agent/providers/openai/codex`                 | OpenAI Codex request and auth helpers                                                                                                                          |
+| `@yolk-sdk/agent/providers/openai/codex-usage`           | Codex subscription-allowance snapshots                                                                                                                         |
+| `@yolk-sdk/agent/providers/openai/codex-provider`        | Codex LLM provider factory                                                                                                                                     |
+| `@yolk-sdk/agent/providers/openai/provider`              | OpenAI-compatible LLM provider factory                                                                                                                         |
+| `@yolk-sdk/agent/providers/openai/conformance`           | Synthetic OpenAI chat, Codex Responses, and Codex usage fixtures and conformance cases                                                                         |
+| `@yolk-sdk/agent/providers/openai/realtime`              | OpenAI Realtime session config and event codecs                                                                                                                |
+| `@yolk-sdk/agent/providers/openai/speech`                | OpenAI text-to-speech and transcription adapters                                                                                                               |
+| `@yolk-sdk/agent/providers/vercel/ai-gateway-provider`   | Vercel AI Gateway Chat Completions provider factory                                                                                                            |
+| `@yolk-sdk/agent/providers/vercel/ai-gateway-classifier` | Vercel AI Gateway classifier (`POST /v1/evaluate`) layer                                                                                                       |
+| `@yolk-sdk/agent/providers/vercel/conformance`           | Verified Gateway chat fixtures, synthetic classifier fixtures, and conformance cases                                                                           |
+| `@yolk-sdk/agent/providers/opencode/go-provider`         | OpenCode Go Chat Completions, Messages, and Responses provider                                                                                                 |
+| `@yolk-sdk/agent/providers/opencode/usage`               | OpenCode Go subscription-allowance snapshots                                                                                                                   |
+| `@yolk-sdk/agent/providers/opencode/conformance`         | Synthetic OpenCode Go (per protocol, commentary replay, usage) fixtures and conformance cases                                                                  |
+| `@yolk-sdk/agent/providers/anthropic`                    | Anthropic/Claude OAuth and broker helpers                                                                                                                      |
+| `@yolk-sdk/agent/providers/anthropic/claude`             | Claude request and auth helpers                                                                                                                                |
+| `@yolk-sdk/agent/providers/anthropic/usage`              | Claude subscription-allowance snapshots                                                                                                                        |
+| `@yolk-sdk/agent/providers/anthropic/claude-provider`    | Claude LLM provider factory                                                                                                                                    |
+| `@yolk-sdk/agent/providers/anthropic/conformance`        | Synthetic Anthropic Messages and Claude usage fixtures and conformance cases                                                                                   |
+| `@yolk-sdk/agent/providers/xai`                          | Grok subscription OAuth and token broker helpers                                                                                                               |
+| `@yolk-sdk/agent/providers/xai/grok`                     | Grok subscription request and auth helpers                                                                                                                     |
+| `@yolk-sdk/agent/providers/xai/grok-provider`            | Grok subscription LLM provider factory                                                                                                                         |
+| `@yolk-sdk/agent/providers/xai/usage`                    | Grok subscription-allowance snapshots                                                                                                                          |
+| `@yolk-sdk/agent/providers/xai/conformance`              | Synthetic Grok Responses and Grok usage fixtures and conformance cases                                                                                         |
+| `@yolk-sdk/agent/providers/subscription-usage`           | Shared allowance snapshot and safe error schemas                                                                                                               |
+| `@yolk-sdk/agent/skillset`                               | Portable skill and slash-command parsing/catalogs                                                                                                              |
+| `@yolk-sdk/agent/voice`                                  | Voice protocol, controller, tool handler, projection, speech                                                                                                   |
+| `@yolk-sdk/agent/voice/browser`                          | Browser WebRTC voice transport                                                                                                                                 |
+| `@yolk-sdk/agent/voice/react`                            | Headless browser voice React hook                                                                                                                              |
 
 ## Imports
 
@@ -297,6 +297,21 @@ configuration. Anthropic Claude forwards `low`, `medium`, `high`, and `xhigh` th
 `output_config.effort`. It omits `minimal`, which Anthropic does not support. Hosts remain
 responsible for choosing an effort accepted by the selected provider and model.
 
+### Prompt caching
+
+Provider prompt caching is always on (ADR 0008). Set `cacheKey` (for example the session id) on
+`run` or `runRuntime` so providers route a conversation to its cached prefix: Anthropic gets
+`cache_control` breakpoints and a Claude session header derived from the key, Codex and Grok `prompt_cache_key` plus their session headers, Vercel AI
+Gateway `caching: 'auto'` and `x-session-affinity`, and OpenCode Go `x-opencode-session`. The
+generic OpenAI-compatible chat provider sends nothing unless its config sets `cacheKeyHeaders`.
+Claude entries last five minutes unless the provider sets `promptCacheTtl: '1h'`.
+
+Keep the prefix byte-identical: per-request facts (fresh signed URLs, the current time) belong in
+`LLMRequest.turnContext`, which adapters append after the conversation (Anthropic after every
+breakpoint; Gateway's automatic markers still read the prefix before it). Loop hosts set it by
+decorating `LLMProvider`. `LLMRequest.toolChoice: 'none'` forbids tool calls but keeps the tool
+definitions; on Anthropic a changed `tool_choice` invalidates the cached messages.
+
 ### Anthropic tool schemas
 
 Claude subscription OAuth rejects some valid JSON Schema constructs that Effect Schema can emit
@@ -416,6 +431,8 @@ policy and emits protocol-visible retry/error state:
   [stream diagnostics guide](https://github.com/magoz/yolk-sdk/blob/main/apps/docs/content/docs/troubleshooting.mdx#diagnose-chat-stream-failures-with-stream-diagnostics).
 - Chat Completions and Responses HTTP failures copy the envelope string `code` (falling back to
   `type`) into `provider.providerCode`; free-text upstream bodies stay out of `LLMError`.
+- Claude subscription (`anthropic_claude`) HTTP and stream errors use `error.details.error_code`
+  (for example `claude_code_version_too_old`), then `error.type`, then `error.code`.
 - `AgentRetry.provider` exposes current retry metadata and chosen `delayMs`.
 - `AgentError.provider` preserves final terminal metadata.
 - `AgentErrorCode` includes `rate_limit`, `overloaded`, `context_overflow`, and generic
@@ -925,10 +942,15 @@ This package declares them; it does not run scripts.
 
 - `makeTool({ output })` adds declaration-only `ToolDef.outputSchema`, lowered like `parameters`.
 - `callableBy: 'all' | 'model' | 'codemode'` (default `all`) decides who may call a tool. For
-  `codemode` only, `discovery: 'listed' | 'search'` (default `listed`) decides how scripts find it.
+  `codemode` only, `discovery: 'listed' | 'search' | 'pinned'` (default `listed`; `pinned` is
+  always listed, outside the catalog budget) decides how scripts find it.
   Codemode-only tools never reach providers. Approval, input, interaction, activated background,
   `question`, `subagent`, and nested-access tools never run from code mode (stageable approval tools
-  are only staged; see Staged tool plans); `resolveTools` rejects `callableBy: 'codemode'` on them.
+  are only staged; see Staged tool plans); `resolveTools` rejects `callableBy: 'codemode'` on them,
+  except a stageable approval tool, which may be stage-only: never declared, only `stage()`d from
+  scripts (see [ADR 0007](https://github.com/magoz/yolk-sdk/blob/main/docs/adr/0007-tool-exposure-and-catalog.md)).
+- `instruct: ({ tools }) => RunInstruction` on a nested-access registration contributes a host
+  instruction (see Host instructions), collected in `ResolvedToolSet.instructions`.
 - `nestedToolAccess: true` gives a registration's `execute` a `nested` executor over the other
   code-mode-callable tools of the same resolution and host context. Nested calls run through the
   resolved execute path and fail closed with model-visible error results. Assign nested call ids as
@@ -942,6 +964,48 @@ This package declares them; it does not run scripts.
   Size the record with `makeNestedToolCallRecorder({ maxCalls })`; per-status `counts` cover
   every call, dropped ones included.
 
+## Deferred tools
+
+`loading: 'deferred'` (on `makeTool`, `ToolDef`, or the MCP/connector `exposure` resolvers) keeps a
+model-callable tool out of provider requests until the model loads it, so hosts can connect many
+tools without spending context on them ([ADR 0007](https://github.com/magoz/yolk-sdk/blob/main/docs/adr/0007-tool-exposure-and-catalog.md)).
+
+- When any tool is deferred, `resolveTools` adds the package `tool_search` tool (read access,
+  model-only; `makeToolSearchTool`). Its result names the tools it loaded; opt out with
+  `resolveTools(modules, context, { toolSearch: false })`, or register your own `tool_search`.
+- Activation is derived from the transcript, never stored: each request declares
+  `declaredToolDefs(tools, messages)`, the eager tools plus deferred tools a `tool_search` result
+  activated, so replayed and resumed steps declare the same tools. Loading a tool changes the
+  declared tools, which start the request, so that request misses the prompt cache once; later
+  requests reuse the new prefix. Prefer code mode scripts for exploratory use.
+- Deferral saves context; it is not authority. Approval-gated tools keep their approval when
+  deferred. `loading` on a `callableBy: 'codemode'` tool is a type error (`invalid_tool_exposure` at
+  resolution for raw definitions); `tool_search`, `question`, `subagent`, input, interaction, plan
+  review, background, and nested-access tools cannot be deferred (`deferred_unsupported_tool`).
+
+## Host instructions
+
+A `RunInstruction` (`{ key, state, render }`) is host context kept current in the conversation,
+for example the code mode catalog (`ResolvedToolSet.instructions`). Pass it as
+`RunConfig.instructions` or `RuntimeConfig.instructions`.
+
+- Before each model request the loop compares `state` with the latest instruction message of the
+  same `key` and, only when it changed, appends a user-role message with `render(state)` and the
+  non-model-visible `instruction: { key, state }` envelope. Earlier messages never change, so a
+  changing instruction never invalidates the cached request prefix. `state: undefined` appends a
+  removal notice once.
+- `render` gets only the current state: compaction keeps the latest message of each key
+  (`latestInstructionMessages`), so each one must stand alone.
+- The appended messages join the run's created messages (persist them with the turn) but emit no
+  `UserMessage` event. Durable hosts driving `runModelTurn` append and persist
+  `instructionMessages(transcript, instructions)` before each step themselves; `runModelTurn` does
+  not accept `instructions`.
+- Window compaction keeps instruction messages after its summary; custom compaction must keep
+  `latestInstructionMessages(...)` too. Chat projections hide them (`isInstructionMessage`) and
+  `toAgentMessages` round-trips them. Duplicate keys fail resolution (`duplicate_instruction`).
+- Hosts that cannot append messages to their conversation may put `render(state)` into the system
+  prompt instead, only while `state` is defined (`undefined` renders the removal notice).
+
 ## Durable tool ledger
 
 Steps that hosts re-execute (Vercel Workflow's queue is at-least-once) must not repeat writes.
@@ -1009,8 +1073,11 @@ aborts, and implementation bugs outside typed tool execution.
   or step when call ids can repeat), keep its operations interruptible, and reserve about 15 s of
   the step budget after `deadline` for recording outcomes.
 - If you send `ToolDef`s to providers yourself (outside `run`/`runModelTurn`), filter them with
-  protocol `providerToolDefs`; codemode-only tools must never reach providers. Executor decorators
-  outside `ResolvedToolSet.execute` do not see nested code mode calls.
+  protocol `declaredToolDefs(tools, messages)`: codemode-only tools must never reach providers, and
+  deferred tools only once a `tool_search` result activated them.
+- Durable hosts driving `runModelTurn` append and persist `instructionMessages(...)` before each
+  model step (see Host instructions).
+- Executor decorators outside `ResolvedToolSet.execute` do not see nested code mode calls.
 - Compact context and decide memory/search policy.
 
 ## Boundaries

package/dist/compaction/window.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"window.d.mts","names":[],"sources":["../../src/compaction/window.ts"],"mappings":"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"}
+{"version":3,"file":"window.d.mts","names":[],"sources":["../../src/compaction/window.ts"],"mappings":"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"}

package/dist/compaction/window.mjs

@@ -1,6 +1,6 @@
 import { estimateAgentMessagesTokens } from "./estimator.mjs";
 import { Data, Predicate } from "effect";
-import { CompactionEnd, CompactionStart } from "@yolk-sdk/agent/protocol";
+import { CompactionEnd, CompactionStart, isInstructionMessage, latestInstructionMessages } from "@yolk-sdk/agent/protocol";
 //#region src/compaction/window.ts
 const defaultCompactionTailMessageCount = 16;
 const defaultMinimumCompactionMessages = 2;
@@ -51,7 +51,13 @@ const planWindowCompaction = (messages, options) => {
 const applyCompactionPlan = (plan, options) => {
 	if (Predicate.isTagged(plan, "Skip")) return skippedCompactionResult(plan.reason, plan.messages, plan.beforeTokens);
 	const estimateTokens = estimator(options.estimateTokens);
-	const messages = [options.summaryMessage, ...plan.recentMessages];
+	const recentKeys = new Set(plan.recentMessages.flatMap((message) => isInstructionMessage(message) ? [message.instruction.key] : []));
+	const keptInstructions = latestInstructionMessages(plan.compactedMessages).filter((message) => !recentKeys.has(message.instruction.key));
+	const messages = [
+		options.summaryMessage,
+		...keptInstructions,
+		...plan.recentMessages
+	];
 	const afterTokens = estimateTokens(messages);
 	if (afterTokens >= plan.beforeTokens) return skippedCompactionResult("not_smaller", plan.messages, plan.beforeTokens);
 	return CompactionResult.Compacted({

package/dist/compaction/window.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"window.mjs","names":[],"sources":["../../src/compaction/window.ts"],"sourcesContent":["import {\n  CompactionEnd,\n  CompactionStart,\n  type AgentEvent,\n  type AgentMessage\n} from '@yolk-sdk/agent/protocol'\nimport { estimateAgentMessagesTokens, type TranscriptTokenEstimator } from './estimator.ts'\nimport { Data, Predicate } from 'effect'\n\nexport const defaultCompactionTailMessageCount = 16\n\nexport const defaultMinimumCompactionMessages = 2\n\nexport type CompactionSkipReason =\n  | 'too_few_messages'\n  | 'below_threshold'\n  | 'empty_window'\n  | 'not_smaller'\n\nexport type WindowCompactionPlanOptions = {\n  readonly thresholdTokens: number\n  readonly tailMessageCount?: number\n  readonly minMessages?: number\n  readonly estimateTokens?: TranscriptTokenEstimator\n}\n\nexport type WindowCompactionPlan = Data.TaggedEnum<{\n  Skip: {\n    readonly reason: CompactionSkipReason\n    readonly messages: ReadonlyArray<AgentMessage>\n    readonly beforeTokens: number\n  }\n  Compact: {\n    readonly messages: ReadonlyArray<AgentMessage>\n    readonly compactedMessages: ReadonlyArray<AgentMessage>\n    readonly recentMessages: ReadonlyArray<AgentMessage>\n    readonly tailStartIndex: number\n    readonly beforeTokens: number\n  }\n}>\n\nexport type SkippedCompactionPlan = Extract<WindowCompactionPlan, { readonly _tag: 'Skip' }>\n\nexport type CompactCompactionPlan = Extract<WindowCompactionPlan, { readonly _tag: 'Compact' }>\n\nconst WindowCompactionPlan = Data.taggedEnum<WindowCompactionPlan>()\n\nexport type CompactionResult = Data.TaggedEnum<{\n  Skipped: {\n    readonly reason: CompactionSkipReason\n    readonly messages: ReadonlyArray<AgentMessage>\n    readonly events: ReadonlyArray<AgentEvent>\n    readonly beforeTokens: number\n  }\n  Compacted: {\n    readonly strategy: string\n    readonly messages: ReadonlyArray<AgentMessage>\n    readonly events: ReadonlyArray<AgentEvent>\n    readonly beforeTokens: number\n    readonly afterTokens: number\n    readonly compactedMessages: ReadonlyArray<AgentMessage>\n    readonly recentMessages: ReadonlyArray<AgentMessage>\n    readonly summaryMessage: AgentMessage\n  }\n}>\n\nexport type SkippedCompactionResult = Extract<CompactionResult, { readonly _tag: 'Skipped' }>\n\nexport type CompletedCompactionResult = Extract<CompactionResult, { readonly _tag: 'Compacted' }>\n\nexport const CompactionResult = Data.taggedEnum<CompactionResult>()\n\nexport type ApplyCompactionPlanOptions = {\n  readonly strategy: string\n  readonly summaryMessage: AgentMessage\n  readonly estimateTokens?: TranscriptTokenEstimator\n}\n\nconst estimator = (estimateTokens?: TranscriptTokenEstimator) =>\n  estimateTokens ?? estimateAgentMessagesTokens\n\nconst skippedCompactionResult = (\n  reason: CompactionSkipReason,\n  messages: ReadonlyArray<AgentMessage>,\n  beforeTokens: number\n): SkippedCompactionResult =>\n  CompactionResult.Skipped({\n    reason,\n    messages,\n    events: [],\n    beforeTokens\n  })\n\nexport const windowTailStartIndex = (\n  messages: ReadonlyArray<AgentMessage>,\n  tailMessageCount: number\n) => {\n  const tailCount = Math.min(Math.max(0, tailMessageCount), Math.max(0, messages.length - 1))\n  const initialIndex = Math.max(1, messages.length - tailCount)\n  let index = initialIndex\n\n  while (index > 1 && messages[index]?._tag === 'ToolResult') {\n    index -= 1\n  }\n\n  return index\n}\n\nexport const planWindowCompaction = (\n  messages: ReadonlyArray<AgentMessage>,\n  options: WindowCompactionPlanOptions\n): WindowCompactionPlan => {\n  const estimateTokens = estimator(options.estimateTokens)\n  const beforeTokens = estimateTokens(messages)\n  const minMessages = options.minMessages ?? defaultMinimumCompactionMessages\n\n  if (messages.length <= minMessages) {\n    return WindowCompactionPlan.Skip({\n      reason: 'too_few_messages',\n      messages,\n      beforeTokens\n    })\n  }\n\n  if (beforeTokens < options.thresholdTokens) {\n    return WindowCompactionPlan.Skip({\n      reason: 'below_threshold',\n      messages,\n      beforeTokens\n    })\n  }\n\n  const tailStart = windowTailStartIndex(\n    messages,\n    options.tailMessageCount ?? defaultCompactionTailMessageCount\n  )\n\n  const compactedMessages = messages.slice(0, tailStart)\n  const recentMessages = messages.slice(tailStart)\n\n  if (compactedMessages.length === 0 || recentMessages.length === 0) {\n    return WindowCompactionPlan.Skip({\n      reason: 'empty_window',\n      messages,\n      beforeTokens\n    })\n  }\n\n  return WindowCompactionPlan.Compact({\n    messages,\n    compactedMessages,\n    recentMessages,\n    tailStartIndex: tailStart,\n    beforeTokens\n  })\n}\n\nexport const applyCompactionPlan = (\n  plan: WindowCompactionPlan,\n  options: ApplyCompactionPlanOptions\n): CompactionResult => {\n  if (Predicate.isTagged(plan, 'Skip')) {\n    return skippedCompactionResult(plan.reason, plan.messages, plan.beforeTokens)\n  }\n\n  const estimateTokens = estimator(options.estimateTokens)\n  const messages = [options.summaryMessage, ...plan.recentMessages]\n  const afterTokens = estimateTokens(messages)\n\n  if (afterTokens >= plan.beforeTokens) {\n    return skippedCompactionResult('not_smaller', plan.messages, plan.beforeTokens)\n  }\n\n  return CompactionResult.Compacted({\n    strategy: options.strategy,\n    messages,\n    events: [\n      CompactionStart.make({ strategy: options.strategy }),\n      CompactionEnd.make({\n        strategy: options.strategy,\n        beforeTokens: plan.beforeTokens,\n        afterTokens\n      })\n    ],\n    beforeTokens: plan.beforeTokens,\n    afterTokens,\n    compactedMessages: plan.compactedMessages,\n    recentMessages: plan.recentMessages,\n    summaryMessage: options.summaryMessage\n  })\n}\n"],"mappings":";;;;AASA,MAAa,oCAAoC;AAEjD,MAAa,mCAAmC;AAkChD,MAAM,uBAAuB,KAAK,WAAiC;AAyBnE,MAAa,mBAAmB,KAAK,WAA6B;AAQlE,MAAM,aAAa,mBACjB,kBAAkB;AAEpB,MAAM,2BACJ,QACA,UACA,iBAEA,iBAAiB,QAAQ;CACvB;CACA;CACA,QAAQ,CAAC;CACT;AACF,CAAC;AAEH,MAAa,wBACX,UACA,qBACG;CACH,MAAM,YAAY,KAAK,IAAI,KAAK,IAAI,GAAG,gBAAgB,GAAG,KAAK,IAAI,GAAG,SAAS,SAAS,CAAC,CAAC;CAE1F,IAAI,QADiB,KAAK,IAAI,GAAG,SAAS,SAAS,SAC5B;CAEvB,OAAO,QAAQ,KAAK,SAAS,QAAQ,SAAS,cAC5C,SAAS;CAGX,OAAO;AACT;AAEA,MAAa,wBACX,UACA,YACyB;CAEzB,MAAM,eADiB,UAAU,QAAQ,cACP,EAAE,QAAQ;CAC5C,MAAM,cAAc,QAAQ,eAAA;CAE5B,IAAI,SAAS,UAAU,aACrB,OAAO,qBAAqB,KAAK;EAC/B,QAAQ;EACR;EACA;CACF,CAAC;CAGH,IAAI,eAAe,QAAQ,iBACzB,OAAO,qBAAqB,KAAK;EAC/B,QAAQ;EACR;EACA;CACF,CAAC;CAGH,MAAM,YAAY,qBAChB,UACA,QAAQ,oBAAA,EACV;CAEA,MAAM,oBAAoB,SAAS,MAAM,GAAG,SAAS;CACrD,MAAM,iBAAiB,SAAS,MAAM,SAAS;CAE/C,IAAI,kBAAkB,WAAW,KAAK,eAAe,WAAW,GAC9D,OAAO,qBAAqB,KAAK;EAC/B,QAAQ;EACR;EACA;CACF,CAAC;CAGH,OAAO,qBAAqB,QAAQ;EAClC;EACA;EACA;EACA,gBAAgB;EAChB;CACF,CAAC;AACH;AAEA,MAAa,uBACX,MACA,YACqB;CACrB,IAAI,UAAU,SAAS,MAAM,MAAM,GACjC,OAAO,wBAAwB,KAAK,QAAQ,KAAK,UAAU,KAAK,YAAY;CAG9E,MAAM,iBAAiB,UAAU,QAAQ,cAAc;CACvD,MAAM,WAAW,CAAC,QAAQ,gBAAgB,GAAG,KAAK,cAAc;CAChE,MAAM,cAAc,eAAe,QAAQ;CAE3C,IAAI,eAAe,KAAK,cACtB,OAAO,wBAAwB,eAAe,KAAK,UAAU,KAAK,YAAY;CAGhF,OAAO,iBAAiB,UAAU;EAChC,UAAU,QAAQ;EAClB;EACA,QAAQ,CACN,gBAAgB,KAAK,EAAE,UAAU,QAAQ,SAAS,CAAC,GACnD,cAAc,KAAK;GACjB,UAAU,QAAQ;GAClB,cAAc,KAAK;GACnB;EACF,CAAC,CACH;EACA,cAAc,KAAK;EACnB;EACA,mBAAmB,KAAK;EACxB,gBAAgB,KAAK;EACrB,gBAAgB,QAAQ;CAC1B,CAAC;AACH"}
+{"version":3,"file":"window.mjs","names":[],"sources":["../../src/compaction/window.ts"],"sourcesContent":["import {\n  CompactionEnd,\n  CompactionStart,\n  isInstructionMessage,\n  latestInstructionMessages,\n  type AgentEvent,\n  type AgentMessage\n} from '@yolk-sdk/agent/protocol'\nimport { estimateAgentMessagesTokens, type TranscriptTokenEstimator } from './estimator.ts'\nimport { Data, Predicate } from 'effect'\n\nexport const defaultCompactionTailMessageCount = 16\n\nexport const defaultMinimumCompactionMessages = 2\n\nexport type CompactionSkipReason =\n  | 'too_few_messages'\n  | 'below_threshold'\n  | 'empty_window'\n  | 'not_smaller'\n\nexport type WindowCompactionPlanOptions = {\n  readonly thresholdTokens: number\n  readonly tailMessageCount?: number\n  readonly minMessages?: number\n  readonly estimateTokens?: TranscriptTokenEstimator\n}\n\nexport type WindowCompactionPlan = Data.TaggedEnum<{\n  Skip: {\n    readonly reason: CompactionSkipReason\n    readonly messages: ReadonlyArray<AgentMessage>\n    readonly beforeTokens: number\n  }\n  Compact: {\n    readonly messages: ReadonlyArray<AgentMessage>\n    readonly compactedMessages: ReadonlyArray<AgentMessage>\n    readonly recentMessages: ReadonlyArray<AgentMessage>\n    readonly tailStartIndex: number\n    readonly beforeTokens: number\n  }\n}>\n\nexport type SkippedCompactionPlan = Extract<WindowCompactionPlan, { readonly _tag: 'Skip' }>\n\nexport type CompactCompactionPlan = Extract<WindowCompactionPlan, { readonly _tag: 'Compact' }>\n\nconst WindowCompactionPlan = Data.taggedEnum<WindowCompactionPlan>()\n\nexport type CompactionResult = Data.TaggedEnum<{\n  Skipped: {\n    readonly reason: CompactionSkipReason\n    readonly messages: ReadonlyArray<AgentMessage>\n    readonly events: ReadonlyArray<AgentEvent>\n    readonly beforeTokens: number\n  }\n  Compacted: {\n    readonly strategy: string\n    readonly messages: ReadonlyArray<AgentMessage>\n    readonly events: ReadonlyArray<AgentEvent>\n    readonly beforeTokens: number\n    readonly afterTokens: number\n    readonly compactedMessages: ReadonlyArray<AgentMessage>\n    readonly recentMessages: ReadonlyArray<AgentMessage>\n    readonly summaryMessage: AgentMessage\n  }\n}>\n\nexport type SkippedCompactionResult = Extract<CompactionResult, { readonly _tag: 'Skipped' }>\n\nexport type CompletedCompactionResult = Extract<CompactionResult, { readonly _tag: 'Compacted' }>\n\nexport const CompactionResult = Data.taggedEnum<CompactionResult>()\n\nexport type ApplyCompactionPlanOptions = {\n  readonly strategy: string\n  readonly summaryMessage: AgentMessage\n  readonly estimateTokens?: TranscriptTokenEstimator\n}\n\nconst estimator = (estimateTokens?: TranscriptTokenEstimator) =>\n  estimateTokens ?? estimateAgentMessagesTokens\n\nconst skippedCompactionResult = (\n  reason: CompactionSkipReason,\n  messages: ReadonlyArray<AgentMessage>,\n  beforeTokens: number\n): SkippedCompactionResult =>\n  CompactionResult.Skipped({\n    reason,\n    messages,\n    events: [],\n    beforeTokens\n  })\n\nexport const windowTailStartIndex = (\n  messages: ReadonlyArray<AgentMessage>,\n  tailMessageCount: number\n) => {\n  const tailCount = Math.min(Math.max(0, tailMessageCount), Math.max(0, messages.length - 1))\n  const initialIndex = Math.max(1, messages.length - tailCount)\n  let index = initialIndex\n\n  while (index > 1 && messages[index]?._tag === 'ToolResult') {\n    index -= 1\n  }\n\n  return index\n}\n\nexport const planWindowCompaction = (\n  messages: ReadonlyArray<AgentMessage>,\n  options: WindowCompactionPlanOptions\n): WindowCompactionPlan => {\n  const estimateTokens = estimator(options.estimateTokens)\n  const beforeTokens = estimateTokens(messages)\n  const minMessages = options.minMessages ?? defaultMinimumCompactionMessages\n\n  if (messages.length <= minMessages) {\n    return WindowCompactionPlan.Skip({\n      reason: 'too_few_messages',\n      messages,\n      beforeTokens\n    })\n  }\n\n  if (beforeTokens < options.thresholdTokens) {\n    return WindowCompactionPlan.Skip({\n      reason: 'below_threshold',\n      messages,\n      beforeTokens\n    })\n  }\n\n  const tailStart = windowTailStartIndex(\n    messages,\n    options.tailMessageCount ?? defaultCompactionTailMessageCount\n  )\n\n  const compactedMessages = messages.slice(0, tailStart)\n  const recentMessages = messages.slice(tailStart)\n\n  if (compactedMessages.length === 0 || recentMessages.length === 0) {\n    return WindowCompactionPlan.Skip({\n      reason: 'empty_window',\n      messages,\n      beforeTokens\n    })\n  }\n\n  return WindowCompactionPlan.Compact({\n    messages,\n    compactedMessages,\n    recentMessages,\n    tailStartIndex: tailStart,\n    beforeTokens\n  })\n}\n\nexport const applyCompactionPlan = (\n  plan: WindowCompactionPlan,\n  options: ApplyCompactionPlanOptions\n): CompactionResult => {\n  if (Predicate.isTagged(plan, 'Skip')) {\n    return skippedCompactionResult(plan.reason, plan.messages, plan.beforeTokens)\n  }\n\n  const estimateTokens = estimator(options.estimateTokens)\n\n  // Host instructions (ADR 0007) the summary would fold away stay verbatim after it: the loop\n  // compares instruction state with the uncompacted transcript and would never re-append them.\n  const recentKeys = new Set(\n    plan.recentMessages.flatMap(message =>\n      isInstructionMessage(message) ? [message.instruction.key] : []\n    )\n  )\n\n  const keptInstructions = latestInstructionMessages(plan.compactedMessages).filter(\n    message => !recentKeys.has(message.instruction.key)\n  )\n\n  const messages = [options.summaryMessage, ...keptInstructions, ...plan.recentMessages]\n  const afterTokens = estimateTokens(messages)\n\n  if (afterTokens >= plan.beforeTokens) {\n    return skippedCompactionResult('not_smaller', plan.messages, plan.beforeTokens)\n  }\n\n  return CompactionResult.Compacted({\n    strategy: options.strategy,\n    messages,\n    events: [\n      CompactionStart.make({ strategy: options.strategy }),\n      CompactionEnd.make({\n        strategy: options.strategy,\n        beforeTokens: plan.beforeTokens,\n        afterTokens\n      })\n    ],\n    beforeTokens: plan.beforeTokens,\n    afterTokens,\n    compactedMessages: plan.compactedMessages,\n    recentMessages: plan.recentMessages,\n    summaryMessage: options.summaryMessage\n  })\n}\n"],"mappings":";;;;AAWA,MAAa,oCAAoC;AAEjD,MAAa,mCAAmC;AAkChD,MAAM,uBAAuB,KAAK,WAAiC;AAyBnE,MAAa,mBAAmB,KAAK,WAA6B;AAQlE,MAAM,aAAa,mBACjB,kBAAkB;AAEpB,MAAM,2BACJ,QACA,UACA,iBAEA,iBAAiB,QAAQ;CACvB;CACA;CACA,QAAQ,CAAC;CACT;AACF,CAAC;AAEH,MAAa,wBACX,UACA,qBACG;CACH,MAAM,YAAY,KAAK,IAAI,KAAK,IAAI,GAAG,gBAAgB,GAAG,KAAK,IAAI,GAAG,SAAS,SAAS,CAAC,CAAC;CAE1F,IAAI,QADiB,KAAK,IAAI,GAAG,SAAS,SAAS,SAC5B;CAEvB,OAAO,QAAQ,KAAK,SAAS,QAAQ,SAAS,cAC5C,SAAS;CAGX,OAAO;AACT;AAEA,MAAa,wBACX,UACA,YACyB;CAEzB,MAAM,eADiB,UAAU,QAAQ,cACP,EAAE,QAAQ;CAC5C,MAAM,cAAc,QAAQ,eAAA;CAE5B,IAAI,SAAS,UAAU,aACrB,OAAO,qBAAqB,KAAK;EAC/B,QAAQ;EACR;EACA;CACF,CAAC;CAGH,IAAI,eAAe,QAAQ,iBACzB,OAAO,qBAAqB,KAAK;EAC/B,QAAQ;EACR;EACA;CACF,CAAC;CAGH,MAAM,YAAY,qBAChB,UACA,QAAQ,oBAAA,EACV;CAEA,MAAM,oBAAoB,SAAS,MAAM,GAAG,SAAS;CACrD,MAAM,iBAAiB,SAAS,MAAM,SAAS;CAE/C,IAAI,kBAAkB,WAAW,KAAK,eAAe,WAAW,GAC9D,OAAO,qBAAqB,KAAK;EAC/B,QAAQ;EACR;EACA;CACF,CAAC;CAGH,OAAO,qBAAqB,QAAQ;EAClC;EACA;EACA;EACA,gBAAgB;EAChB;CACF,CAAC;AACH;AAEA,MAAa,uBACX,MACA,YACqB;CACrB,IAAI,UAAU,SAAS,MAAM,MAAM,GACjC,OAAO,wBAAwB,KAAK,QAAQ,KAAK,UAAU,KAAK,YAAY;CAG9E,MAAM,iBAAiB,UAAU,QAAQ,cAAc;CAIvD,MAAM,aAAa,IAAI,IACrB,KAAK,eAAe,SAAQ,YAC1B,qBAAqB,OAAO,IAAI,CAAC,QAAQ,YAAY,GAAG,IAAI,CAAC,CAC/D,CACF;CAEA,MAAM,mBAAmB,0BAA0B,KAAK,iBAAiB,EAAE,QACzE,YAAW,CAAC,WAAW,IAAI,QAAQ,YAAY,GAAG,CACpD;CAEA,MAAM,WAAW;EAAC,QAAQ;EAAgB,GAAG;EAAkB,GAAG,KAAK;CAAc;CACrF,MAAM,cAAc,eAAe,QAAQ;CAE3C,IAAI,eAAe,KAAK,cACtB,OAAO,wBAAwB,eAAe,KAAK,UAAU,KAAK,YAAY;CAGhF,OAAO,iBAAiB,UAAU;EAChC,UAAU,QAAQ;EAClB;EACA,QAAQ,CACN,gBAAgB,KAAK,EAAE,UAAU,QAAQ,SAAS,CAAC,GACnD,cAAc,KAAK;GACjB,UAAU,QAAQ;GAClB,cAAc,KAAK;GACnB;EACF,CAAC,CACH;EACA,cAAc,KAAK;EACnB;EACA,mBAAmB,KAAK;EACxB,gBAAgB,KAAK;EACrB,gBAAgB,QAAQ;CAC1B,CAAC;AACH"}

package/dist/loop/index.d.mts

@@ -7,5 +7,6 @@ import { LLMProvider, LLMRequest } from "./services/llm-provider.mjs";
 import { LoopConfig, LoopConfigSettings } from "./services/loop-config.mjs";
 import { ToolExecutionOptions, ToolExecutor } from "./services/tool-executor.mjs";
 import { decorateLLMProvider, makeAgentLoopLayer } from "./layer.mjs";
+import { RunInstruction, instructionMessages } from "./instructions.mjs";
 import { AgentLoopRunId, ModelTurnConfig, PreparedToolBatch, RunConfig, ToolBatchConfig, loadInteractionReceipts, prepareToolBatch, run, runModelTurn, runToolBatch } from "./run.mjs";
-export { AbortError, type AgentLoopError, type AgentLoopRunId, type CollectModelTurnAttemptResult, ContextTransformError, type ContextTransformResult, ContextTransformer, FauxExhaustedError, LLMDone, LLMError, LLMEvent, LLMProvider, type LLMProviderError, LLMProviderToolResult, LLMReasoningDelta, type LLMRequest, LLMResponseIssue, LLMTextDelta, LLMToolCall, LLMToolInputDelta, LLMToolInputStart, LLMUsage, LoopConfig, type LoopConfigSettings, type ModelTurnCollection, type ModelTurnConfig, type ModelTurnResult, type PreparedToolBatch, type RunConfig, type ToolBatchConfig, ToolError, type ToolExecutionOptions, ToolExecutor, accumulateAssistantMessage, agentLoopErrorToAgentError, collectModelTurn, collectModelTurnAttempt, collectReasoning, collectText, collectToolCalls, decorateLLMProvider, loadInteractionReceipts, makeAgentLoopLayer, prepareToolBatch, run, runModelTurn, runToolBatch };
+export { AbortError, type AgentLoopError, type AgentLoopRunId, type CollectModelTurnAttemptResult, ContextTransformError, type ContextTransformResult, ContextTransformer, FauxExhaustedError, LLMDone, LLMError, LLMEvent, LLMProvider, type LLMProviderError, LLMProviderToolResult, LLMReasoningDelta, type LLMRequest, LLMResponseIssue, LLMTextDelta, LLMToolCall, LLMToolInputDelta, LLMToolInputStart, LLMUsage, LoopConfig, type LoopConfigSettings, type ModelTurnCollection, type ModelTurnConfig, type ModelTurnResult, type PreparedToolBatch, type RunConfig, type RunInstruction, type ToolBatchConfig, ToolError, type ToolExecutionOptions, ToolExecutor, accumulateAssistantMessage, agentLoopErrorToAgentError, collectModelTurn, collectModelTurnAttempt, collectReasoning, collectText, collectToolCalls, decorateLLMProvider, instructionMessages, loadInteractionReceipts, makeAgentLoopLayer, prepareToolBatch, run, runModelTurn, runToolBatch };

package/dist/loop/index.mjs

@@ -7,5 +7,6 @@ import { LLMProvider } from "./services/llm-provider.mjs";
 import { LoopConfig } from "./services/loop-config.mjs";
 import { ToolExecutor } from "./services/tool-executor.mjs";
 import { decorateLLMProvider, makeAgentLoopLayer } from "./layer.mjs";
+import { instructionMessages } from "./instructions.mjs";
 import { loadInteractionReceipts, prepareToolBatch, run, runModelTurn, runToolBatch } from "./run.mjs";
-export { AbortError, ContextTransformError, ContextTransformer, FauxExhaustedError, LLMDone, LLMError, LLMEvent, LLMProvider, LLMProviderToolResult, LLMReasoningDelta, LLMResponseIssue, LLMTextDelta, LLMToolCall, LLMToolInputDelta, LLMToolInputStart, LLMUsage, LoopConfig, ToolError, ToolExecutor, accumulateAssistantMessage, agentLoopErrorToAgentError, collectModelTurn, collectModelTurnAttempt, collectReasoning, collectText, collectToolCalls, decorateLLMProvider, loadInteractionReceipts, makeAgentLoopLayer, prepareToolBatch, run, runModelTurn, runToolBatch };
+export { AbortError, ContextTransformError, ContextTransformer, FauxExhaustedError, LLMDone, LLMError, LLMEvent, LLMProvider, LLMProviderToolResult, LLMReasoningDelta, LLMResponseIssue, LLMTextDelta, LLMToolCall, LLMToolInputDelta, LLMToolInputStart, LLMUsage, LoopConfig, ToolError, ToolExecutor, accumulateAssistantMessage, agentLoopErrorToAgentError, collectModelTurn, collectModelTurnAttempt, collectReasoning, collectText, collectToolCalls, decorateLLMProvider, instructionMessages, loadInteractionReceipts, makeAgentLoopLayer, prepareToolBatch, run, runModelTurn, runToolBatch };

package/dist/loop/instructions.d.mts

@@ -0,0 +1,39 @@
+import * as Schema from "effect/Schema";
+import { AgentMessage, UserMessage } from "@yolk-sdk/agent/protocol";
+
+//#region src/loop/instructions.d.ts
+/**
+ * A host instruction kept current in the conversation (ADR 0007), for example the code mode tool
+ * catalog. Before each model request the loop compares `state` with the state of the latest
+ * instruction message with the same `key` in the transcript; only when they differ it appends one
+ * user-role instruction message whose content is `render(current)`. Earlier messages never change,
+ * so a changing instruction never rewrites the cached request prefix, and a redelivered step
+ * decides the same from the same transcript.
+ */
+type RunInstruction = {
+  readonly key: string; /** The current state; `undefined` when the instruction no longer applies. */
+  readonly state: Schema.Json | undefined;
+  /**
+   * The model-visible text of a state, or a removal notice (`undefined`). Self-contained: it never
+   * sees the previous state, because compaction keeps only the latest message of each key
+   * (`latestInstructionMessages`), so that message alone must carry the whole instruction.
+   */
+  readonly render: (current: Schema.Json | undefined) => string;
+};
+/**
+ * The instruction messages a model request needs before it runs, in `instructions` order. States
+ * compare as JSON values, independent of object key order. A removal is recorded once as an
+ * instruction message without a state.
+ */
+declare const instructionMessages: (messages: ReadonlyArray<AgentMessage>, instructions: ReadonlyArray<RunInstruction>) => ReadonlyArray<UserMessage>;
+/**
+ * The instruction messages a request needs, appended. They join the run's created messages (so
+ * hosts persist them with the turn) but emit no `UserMessage` event: they are not user input.
+ */
+declare const withInstructionMessages: (messages: ReadonlyArray<AgentMessage>, instructions: ReadonlyArray<RunInstruction> | undefined) => {
+  messages: readonly (UserMessage | import("@yolk-sdk/agent/protocol").AssistantAgentMessage | import("@yolk-sdk/agent/protocol").ToolResultMessage)[];
+  appended: readonly UserMessage[];
+};
+//#endregion
+export { RunInstruction, instructionMessages, withInstructionMessages };
+//# sourceMappingURL=instructions.d.mts.map

package/dist/loop/instructions.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instructions.d.mts","names":[],"sources":["../../src/loop/instructions.ts"],"mappings":";;;;;;AAgBA;;;;;;KAAY,cAAA;EAAA,SACD,GAAA,UAQA;EAAA,SANA,KAAA,EAAO,MAAA,CAAO,IAAA;EAMW;;;AAAgB;AAQpD;EARoC,SAAzB,MAAA,GAAS,OAAA,EAAS,MAAA,CAAO,IAAI;AAAA;;;;;;cAQ3B,mBAAA,GACX,QAAA,EAAU,aAAA,CAAc,YAAA,GACxB,YAAA,EAAc,aAAA,CAAc,cAAA,MAC3B,aAAA,CAAc,WAAA;;;;;cA6BJ,uBAAA,GACX,QAAA,EAAU,aAAA,CAAc,YAAA,GACxB,YAAA,EAAc,aAAA,CAAc,cAAA"}

package/dist/loop/instructions.mjs

@@ -0,0 +1,42 @@
+import { UserMessage, interactionJsonEquals, latestInstructionState } from "@yolk-sdk/agent/protocol";
+//#region src/loop/instructions.ts
+/**
+* The instruction messages a model request needs before it runs, in `instructions` order. States
+* compare as JSON values, independent of object key order. A removal is recorded once as an
+* instruction message without a state.
+*/
+const instructionMessages = (messages, instructions) => instructions.flatMap((instruction) => {
+	const previous = latestInstructionState(messages, instruction.key);
+	const current = instruction.state;
+	if (current === void 0) {
+		if (previous === void 0) return [];
+		return [UserMessage.make({
+			content: instruction.render(void 0),
+			instruction: { key: instruction.key }
+		})];
+	}
+	if (previous !== void 0 && interactionJsonEquals(previous, current)) return [];
+	const content = instruction.render(current);
+	return content.trim().length === 0 ? [] : [UserMessage.make({
+		content,
+		instruction: {
+			key: instruction.key,
+			state: current
+		}
+	})];
+});
+/**
+* The instruction messages a request needs, appended. They join the run's created messages (so
+* hosts persist them with the turn) but emit no `UserMessage` event: they are not user input.
+*/
+const withInstructionMessages = (messages, instructions) => {
+	const appended = instructions === void 0 || instructions.length === 0 ? [] : instructionMessages(messages, instructions);
+	return {
+		messages: appended.length === 0 ? messages : [...messages, ...appended],
+		appended
+	};
+};
+//#endregion
+export { instructionMessages, withInstructionMessages };
+
+//# sourceMappingURL=instructions.mjs.map

package/dist/loop/instructions.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"instructions.mjs","names":[],"sources":["../../src/loop/instructions.ts"],"sourcesContent":["import type * as Schema from 'effect/Schema'\nimport {\n  interactionJsonEquals,\n  latestInstructionState,\n  UserMessage,\n  type AgentMessage\n} from '@yolk-sdk/agent/protocol'\n\n/**\n * A host instruction kept current in the conversation (ADR 0007), for example the code mode tool\n * catalog. Before each model request the loop compares `state` with the state of the latest\n * instruction message with the same `key` in the transcript; only when they differ it appends one\n * user-role instruction message whose content is `render(current)`. Earlier messages never change,\n * so a changing instruction never rewrites the cached request prefix, and a redelivered step\n * decides the same from the same transcript.\n */\nexport type RunInstruction = {\n  readonly key: string\n  /** The current state; `undefined` when the instruction no longer applies. */\n  readonly state: Schema.Json | undefined\n  /**\n   * The model-visible text of a state, or a removal notice (`undefined`). Self-contained: it never\n   * sees the previous state, because compaction keeps only the latest message of each key\n   * (`latestInstructionMessages`), so that message alone must carry the whole instruction.\n   */\n  readonly render: (current: Schema.Json | undefined) => string\n}\n\n/**\n * The instruction messages a model request needs before it runs, in `instructions` order. States\n * compare as JSON values, independent of object key order. A removal is recorded once as an\n * instruction message without a state.\n */\nexport const instructionMessages = (\n  messages: ReadonlyArray<AgentMessage>,\n  instructions: ReadonlyArray<RunInstruction>\n): ReadonlyArray<UserMessage> =>\n  instructions.flatMap(instruction => {\n    const previous = latestInstructionState(messages, instruction.key)\n    const current = instruction.state\n\n    if (current === undefined) {\n      if (previous === undefined) return []\n\n      return [\n        UserMessage.make({\n          content: instruction.render(undefined),\n          instruction: { key: instruction.key }\n        })\n      ]\n    }\n\n    if (previous !== undefined && interactionJsonEquals(previous, current)) return []\n\n    const content = instruction.render(current)\n\n    return content.trim().length === 0\n      ? []\n      : [UserMessage.make({ content, instruction: { key: instruction.key, state: current } })]\n  })\n\n/**\n * The instruction messages a request needs, appended. They join the run's created messages (so\n * hosts persist them with the turn) but emit no `UserMessage` event: they are not user input.\n */\nexport const withInstructionMessages = (\n  messages: ReadonlyArray<AgentMessage>,\n  instructions: ReadonlyArray<RunInstruction> | undefined\n) => {\n  const appended =\n    instructions === undefined || instructions.length === 0\n      ? []\n      : instructionMessages(messages, instructions)\n\n  return { messages: appended.length === 0 ? messages : [...messages, ...appended], appended }\n}\n"],"mappings":";;;;;;;AAiCA,MAAa,uBACX,UACA,iBAEA,aAAa,SAAQ,gBAAe;CAClC,MAAM,WAAW,uBAAuB,UAAU,YAAY,GAAG;CACjE,MAAM,UAAU,YAAY;CAE5B,IAAI,YAAY,KAAA,GAAW;EACzB,IAAI,aAAa,KAAA,GAAW,OAAO,CAAC;EAEpC,OAAO,CACL,YAAY,KAAK;GACf,SAAS,YAAY,OAAO,KAAA,CAAS;GACrC,aAAa,EAAE,KAAK,YAAY,IAAI;EACtC,CAAC,CACH;CACF;CAEA,IAAI,aAAa,KAAA,KAAa,sBAAsB,UAAU,OAAO,GAAG,OAAO,CAAC;CAEhF,MAAM,UAAU,YAAY,OAAO,OAAO;CAE1C,OAAO,QAAQ,KAAK,EAAE,WAAW,IAC7B,CAAC,IACD,CAAC,YAAY,KAAK;EAAE;EAAS,aAAa;GAAE,KAAK,YAAY;GAAK,OAAO;EAAQ;CAAE,CAAC,CAAC;AAC3F,CAAC;;;;;AAMH,MAAa,2BACX,UACA,iBACG;CACH,MAAM,WACJ,iBAAiB,KAAA,KAAa,aAAa,WAAW,IAClD,CAAC,IACD,oBAAoB,UAAU,YAAY;CAEhD,OAAO;EAAE,UAAU,SAAS,WAAW,IAAI,WAAW,CAAC,GAAG,UAAU,GAAG,QAAQ;EAAG;CAAS;AAC7F"}

package/dist/loop/run.d.mts

@@ -3,6 +3,7 @@ import { ContextTransformer } from "./services/context-transformer.mjs";
 import { LLMProvider } from "./services/llm-provider.mjs";
 import { LoopConfig } from "./services/loop-config.mjs";
 import { ToolExecutor } from "./services/tool-executor.mjs";
+import { RunInstruction } from "./instructions.mjs";
 import { Effect, Stream } from "effect";
 import { AgentEvent, AgentMessage, AgentModelCapabilities, AgentReasoningEffort, AgentUsage, HitlRequest, HitlResponse, InputToolHandler, InteractionHost, InteractionPreflight, InteractionReceipt, InteractionRef, ToolApprovalPreviewer, ToolCall, ToolDef } from "@yolk-sdk/agent/protocol";
 
@@ -12,6 +13,11 @@ type RunConfig = {
   readonly messages: ReadonlyArray<AgentMessage>;
   readonly systemPrompt: string;
   readonly tools: ReadonlyArray<ToolDef>;
+  /** Host instructions kept current in the conversation (ADR 0007), for example
+   * `ResolvedToolSet.instructions`: before each model request a changed one is appended as a
+   * user-role instruction message, never rewriting earlier messages.
+   */
+  readonly instructions?: ReadonlyArray<RunInstruction>;
   readonly hitlResponses?: ReadonlyArray<HitlResponse>; /** Server-side input validators by tool name (from ResolvedToolSet.inputs). */
   readonly inputs?: Readonly<Record<string, InputToolHandler>>;
   /** Server-side interaction preflight by tool name (from ResolvedToolSet.interactions).
@@ -35,9 +41,16 @@ type RunConfig = {
   readonly resume?: boolean;
   readonly model: string;
   readonly reasoningEffort?: AgentReasoningEffort;
-  readonly capabilities?: AgentModelCapabilities;
+  readonly capabilities?: AgentModelCapabilities; /** Forwarded as `LLMRequest.cacheKey` on every model request of this run. */
+  readonly cacheKey?: string;
 };
-type ModelTurnConfig = RunConfig & {
+/**
+ * One model step for durable hosts. They append and persist `instructionMessages(...)` before
+ * the step themselves (ADR 0007), so `instructions` is not accepted here: a step cannot report
+ * messages it appended, and they would be re-appended, unpersisted, on every step.
+ */
+type ModelTurnConfig = Omit<RunConfig, 'instructions'> & {
+  readonly instructions?: never;
   readonly turn: number;
 };
 type ToolBatchConfig = {

package/dist/loop/run.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"run.d.mts","names":[],"sources":["../../src/loop/run.ts"],"mappings":"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"}
+{"version":3,"file":"run.d.mts","names":[],"sources":["../../src/loop/run.ts"],"mappings":"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"}

package/dist/loop/run.mjs

@@ -4,13 +4,14 @@ import { ContextTransformer } from "./services/context-transformer.mjs";
 import { LLMProvider } from "./services/llm-provider.mjs";
 import { LoopConfig } from "./services/loop-config.mjs";
 import { ToolExecutor, unavailableToolExecutor } from "./services/tool-executor.mjs";
+import { withInstructionMessages } from "./instructions.mjs";
 import "../protocol/change-preview.mjs";
 import { truncateCodePoints } from "../protocol/bounded-text.mjs";
 import { validInteractionReceipt as validInteractionReceipt$1 } from "../protocol/tool.mjs";
 import { withToolArgumentsErrorHint } from "../protocol/tool-argument-hints.mjs";
 import { Array as Array$1, Clock, Data, Effect, Match, Option, Predicate, Ref, Stream, Struct } from "effect";
 import * as Schema$1 from "effect/Schema";
-import { AgentAwaitingInput, AgentEnd, AgentRetry, AgentStart, AssistantMessageEvent, InputRequest, InputRequested, InteractionRequest, InteractionRequested, InteractionResponse, LLMReasoningDelta, LLMStreamEnd, LLMStreamStart, LLMTextDelta, ProviderToolResult, QuestionRequest, QuestionRequested, QuestionToolParams, SubagentCompleted, SubagentStarted, ToolApprovalRequest, ToolApprovalRequested, ToolExecutionAccepted, ToolExecutionCompleted, ToolExecutionError, ToolExecutionStarted, ToolInputDelta, ToolInputEnd, ToolInputStart, ToolResult, TurnEnd, TurnStart, UsageUpdate, addAgentUsage, assistantHostToolCalls, contentParts, contentPreview, decodeBackgroundToolInput, formatInputResponseContent, formatQuestionResponseContent, hitlResponseEvent, inputRequestId, inputResponseStructuredContent, interactionRequestId, makeSubagentRunId, providerToolDefs, questionResponseStructuredContent, toolResultMessageFromResult, zeroAgentUsage } from "@yolk-sdk/agent/protocol";
+import { AgentAwaitingInput, AgentEnd, AgentRetry, AgentStart, AssistantMessageEvent, InputRequest, InputRequested, InteractionRequest, InteractionRequested, InteractionResponse, LLMReasoningDelta, LLMStreamEnd, LLMStreamStart, LLMTextDelta, ProviderToolResult, QuestionRequest, QuestionRequested, QuestionToolParams, SubagentCompleted, SubagentStarted, ToolApprovalRequest, ToolApprovalRequested, ToolExecutionAccepted, ToolExecutionCompleted, ToolExecutionError, ToolExecutionStarted, ToolInputDelta, ToolInputEnd, ToolInputStart, ToolResult, TurnEnd, TurnStart, UsageUpdate, addAgentUsage, assistantHostToolCalls, contentParts, contentPreview, declaredToolDefs, decodeBackgroundToolInput, formatInputResponseContent, formatQuestionResponseContent, hitlResponseEvent, inputRequestId, inputResponseStructuredContent, interactionRequestId, makeSubagentRunId, providerToolDefs, questionResponseStructuredContent, toolResultMessageFromResult, zeroAgentUsage } from "@yolk-sdk/agent/protocol";
 //#region src/loop/run.ts
 const objectField = (input, key) => {
 	if (!Predicate.isObjectOrArray(input)) return;
@@ -783,14 +784,23 @@ const makeModelOnlyAfterLlmStream = (input, llmEventsRef) => Stream.unwrap(Effec
 		})
 	]);
 }));
+/**
+* One provider request. `transcript` is the full conversation before any context transform:
+* deferred tools activated by `tool_search` results in it are declared (ADR 0007).
+*/
+const providerRequest = (config, messages, transcript) => {
+	const request = {
+		messages,
+		tools: declaredToolDefs(config.tools, transcript),
+		model: config.model,
+		reasoningEffort: config.reasoningEffort,
+		systemPrompt: config.systemPrompt
+	};
+	if (config.cacheKey !== void 0) request.cacheKey = config.cacheKey;
+	return request;
+};
 const makeLlmStream = (input, llmEvents, result) => {
-	const makeStream = () => input.provider.stream({
-		messages: result.messages,
-		tools: providerToolDefs(input.config.tools),
-		model: input.config.model,
-		reasoningEffort: input.config.reasoningEffort,
-		systemPrompt: input.config.systemPrompt
-	});
+	const makeStream = () => input.provider.stream(providerRequest(input.config, result.messages, input.currentMessages));
 	return Stream.fromIterable(result.events).pipe(Stream.concat(withProviderRetries(makeStream(), input.loopConfig, makeStream, 1))).pipe(Stream.tap((event) => {
 		if (!isLlmEvent(event)) return Effect.void;
 		const appendEvent = Ref.update(llmEvents, (events) => [...events, event]);
@@ -799,13 +809,7 @@ const makeLlmStream = (input, llmEvents, result) => {
 	}), Stream.flatMap((event) => Predicate.isTagged(event, "AgentRetry") ? Stream.make(event) : isLlmEvent(event) ? Stream.fromIterable(toLlmEvent(event)) : Stream.make(event)), Stream.concat(makeAfterLlmStream(input, llmEvents)));
 };
 const makeModelOnlyLlmStream = (input, llmEvents, result) => {
-	const makeStream = () => input.provider.stream({
-		messages: result.messages,
-		tools: providerToolDefs(input.config.tools),
-		model: input.config.model,
-		reasoningEffort: input.config.reasoningEffort,
-		systemPrompt: input.config.systemPrompt
-	});
+	const makeStream = () => input.provider.stream(providerRequest(input.config, result.messages, input.currentMessages));
 	return Stream.fromIterable(result.events).pipe(Stream.concat(withProviderRetries(makeStream(), input.loopConfig, makeStream, 1))).pipe(Stream.tap((event) => {
 		if (!isLlmEvent(event)) return Effect.void;
 		const appendEvent = Ref.update(llmEvents, (events) => [...events, event]);
@@ -822,13 +826,27 @@ const withoutConsumedAnswers = (config) => Struct.omit(config, [
 	"awaitingRequests",
 	"resume"
 ]);
+/**
+* Appends the instruction messages this model request needs (ADR 0007) to the turn's messages and
+* to the run's created messages, so later turns and the host's persisted transcript see them.
+*/
+const withTurnInstructions = (input) => Effect.gen(function* () {
+	const { messages, appended } = withInstructionMessages(input.currentMessages, input.config.instructions);
+	if (appended.length === 0) return input;
+	yield* Ref.update(input.createdMessages, (created) => [...created, ...appended]);
+	return {
+		...input,
+		currentMessages: messages
+	};
+});
 const makeTurnStream = (input) => Stream.suspend(() => {
 	if (input.turn > input.loopConfig.maxTurns) return Stream.fail(new AbortError({ reason: "max_turns" }));
 	const llmStream = Stream.unwrap(Effect.gen(function* () {
 		const llmEvents = yield* Ref.make([]);
-		const result = yield* input.contextTransformer.transform(input.currentMessages);
+		const instructed = yield* withTurnInstructions(input);
+		const result = yield* input.contextTransformer.transform(instructed.currentMessages);
 		yield* validateCapabilities(input.config, result.messages);
-		return makeLlmStream(input, llmEvents, result);
+		return makeLlmStream(instructed, llmEvents, result);
 	}));
 	return Stream.fromIterable([TurnStart.make({ turn: input.turn }), LLMStreamStart.make({ turn: input.turn })]).pipe(Stream.concat(llmStream));
 });