@skillstate/opencode 2.2.2 → 3.0.1

package/README.md

@@ -2,11 +2,10 @@
 
 # @skillstate/opencode
 
-**OpenCode platform adapter for the @skillstate/core runtime — the only case with real O(1) prompt economy via history trimming.**
+**OpenCode v2 plugin for the @skillstate/core runtime — three native tools and one additive system fragment.**
 
 [![npm version](https://img.shields.io/npm/v/@skillstate/opencode)](https://www.npmjs.com/package/@skillstate/opencode)
 [![node](https://img.shields.io/node/v/@skillstate/opencode)](https://www.npmjs.com/package/@skillstate/opencode)
-[![Tests](https://img.shields.io/badge/tests-873%20passing-brightgreen)](https://github.com/vitkuz573/skillstate)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/vitkuz573/skillstate/blob/main/LICENSE)
 
 </div>
@@ -14,11 +13,10 @@
 ---
 
 `@skillstate/opencode` integrates the paper-exact runtime
-([`@skillstate/core`](../core)) into **OpenCode**. It emits a `SKILL.md` so the
-host discovers the skill, and a plugin that hooks
-`experimental.chat.messages.transform` to **trim history before every LLM
-call** — dropping old messages and injecting only the state, which is genuine
-**O(1)** prompt footprint.
+([`@skillstate/core`](../core)) into **OpenCode v2**. The integration is the
+npm package itself, loaded from the PROJECT `opencode.json(c)` under the v2
+`plugins` key. It registers three native tools and one `context` hook, and it
+is project-local and inert when the project has no `.skillstate/` state.
 
 > **@non-paper** — no adapters exist in arXiv 2608.26263v3. This adapter is an
 > additive integration, not part of the paper.
@@ -29,160 +27,214 @@ call** — dropping old messages and injecting only the state, which is genuine
 npm i @skillstate/core @skillstate/opencode
 ```
 
-Requires Node.js >= 20. TypeScript types are bundled.
+Requires Node.js >= 20 and OpenCode >= 2.0. TypeScript types are bundled, and
+`@opencode/plugin` is a real dependency — the plugin is typed against the
+host's own API rather than against hand-written local declarations.
 
-## Quick start
+## Configure OpenCode
+
+`skillstate init` writes this for you. By hand:
+
+```jsonc
+// opencode.json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugins": ["@skillstate/opencode"]
+}
+```
+
+That is the whole configuration. The MCP server is deliberately NOT
+registered here — see below.
+
+OpenCode v1 is not supported: the config key was `plugin`, and a v1 plugin
+implementation does not run in v2 at all. `skillstate init` migrates a config
+written by an earlier version — our entry is removed from the legacy `plugin`
+array, the key is dropped when nothing of yours is left in it, and an
+`mcp.skillstate` entry from a previous install is removed.
+
+### Why there is no MCP entry here
+
+The MCP server is still shipped and still registered for **Claude Code,
+Codex and any other MCP-capable host** — there it is the only way in. In
+OpenCode the plugin already provides native tools, so registering both is not
+free redundancy:
+
+    native   3 tools    3 357 chars   ~839 tokens
+    MCP     14 tools    9 814 chars  ~2 454 tokens
+    extra                 6 457 chars  ~1 614 tokens on EVERY request
+
+`spec.get` pours a further 1 286 characters of prose into context per call.
+
+Worse, the two surfaces disagree about what may be written, over one file:
+
+    native write -> {"added":["decision"],"updated":[],"deleted":[]}
+    MCP    write -> {"valid":false,"error":"Unknown key: decision"}
+
+The native tools are schema-free; the MCP server validates against the
+procedural spec. With both advertised, whether a note is saved depends on
+which one the model happened to pick.
+
+## What the plugin registers
 
 ```ts
-import { OpenCodeAdapter } from '@skillstate/opencode';
-import { INTERCODE_CTF_SPEC } from '@skillstate/core/schemas';
-
-const adapter = new OpenCodeAdapter();
-
-// SKILL.md with frontmatter (name/description/version) + an
-// execution_context block pointing at the persisted state file:
-const skillMd = adapter.generateSkillMd(INTERCODE_CTF_SPEC, './.skillstate.json');
-
-// Plugin with real O(1) history trimming via experimental.chat.messages.transform.
-// The state path is resolved per session from the host cwd inside the plugin —
-// no baked path:
-const plugin = adapter.generatePluginCode();
-
-// Default keeps the last 3 non-system messages + state injection.
-// Configure history depth:
-const plugin2 = adapter.generatePluginCode({
-  maxHistoryMessages: 5,   // keep last 5 non-system messages
-});
-
-// Persist the plugin to disk atomically:
-const saved = await adapter.savePluginCode(
-  './skillstate.plugin.ts',
-  { maxHistoryMessages: 5 },
-);
+import SkillStatePlugin from '@skillstate/opencode';
+
+await SkillStatePlugin.setup(ctx);
 ```
 
-## Install into OpenCode (host)
+| Registration | Detail |
+| --- | --- |
+| `ctx.tool.transform(...)` | `skillstate_read`, `skillstate_update`, `skillstate_merge` |
+| `ctx.session.hook('context')` | `notes`: pushes ONE bounded fragment onto `event.system`. `paper`: replaces the context with the A.4 prompt |
+| `ctx.event.subscribe(...)` | session parent edges, for sub-agent scoping; in paper mode also the `state_patch` sink |
+
+Nothing else. It does not register `compaction`, `generate` or `title` hooks,
+and in the default `notes` mode it never touches `event.messages`.
+
+### Modes
+
+`notes` is the default and stays the default. `paper` is the paper's own
+specification and is opt-in:
+
+```jsonc
+// skillstate.json in the project root
+{ "mode": "paper" }
+```
+
+```sh
+SKILLSTATE_MODE=paper opencode   # environment wins over the file
+```
+
+`paper` replaces the model-facing context with `Aₜ = (P, Σₜ, Oₜ)` — the
+Appendix A.4 prompt, byte-verbatim — and applies the `state_patch` the model
+emits in response, parsed from the `session.text.ended` event. Prompt size is
+then constant regardless of transcript length.
+
+Note that paper mode means the model no longer sees its own transcript: §3.2
+discards the reasoning trace by construction. Anything worth remembering has
+to be in Σₜ. An unrecognised mode value falls back to `notes` and is reported
+rather than silently applied.
 
-Tested end-to-end against OpenCode ≥ 1.17 (`@opencode-ai/plugin` 1.15.x
-hook contracts). Four steps:
+### Tools
 
-**1. Generate the plugin file** (one-off, or wire into a build script):
+Every tool returns a discriminated result, because a tool that declares an
+`output` schema must return a value matching it — a failure path that returned
+only text is rejected by the host with "tool did not return its declared
+output", which loses the reason.
 
 ```ts
-// scripts/gen-plugin.mjs  (run with: node scripts/gen-plugin.mjs)
-import { OpenCodeAdapter } from '@skillstate/opencode';
-import { writeFileSync } from 'node:fs';
+{ ok: true,  value: {...} }
+{ ok: false, error: "..." }   // e.g. a patch over the 64 KiB budget
+```
+
+| Tool | Purpose |
+| --- | --- |
+| `skillstate_read` | what this session has already saved |
+| `skillstate_update` | merge a patch — the only write path (`null` deletes a key) |
+| `skillstate_merge` | fold sub-agent notes back into the root session |
+
+Scoping is automatic: the session's own scope comes from
+`ToolContext.sessionID` plus the session registry, so the model never passes a
+session id and can never write another agent's file by guessing one.
+
+## Why the transcript is never rewritten
 
-const adapter = new OpenCodeAdapter();
-const code = adapter.generatePluginCode({ maxHistoryMessages: 3 });
-writeFileSync('/abs/path/to/skillstate.plugin.ts', code);
+The previous version of this plugin rewrote the conversation on every model
+request:
+
+```ts
+// removed — this is what broke it
+const trimmed = messages.filter((m) => m.info.role !== 'system').slice(-maxHistory);
+messages.length = 0;
+messages.push(...systemMessages, ...trimmed, stateMessage);
 ```
 
-Put the generated `skillstate.plugin.ts` anywhere stable (absolute path is
-safest), e.g. `<project>/.opencode-runtime/skillstate.plugin.ts`. The plugin
-must be able to resolve `@skillstate/opencode` at load time (install it in
-the project or globally) — hook logic lives in that package.
+Two independent failures in three lines:
 
-**2. Create the initial state file** (`<project>/.skillstate/skillstate.json`),
-matching your spec schema, e.g. for `INTERCODE_CTF_SPEC`:
+1. `slice(-3)` **deleted the task statement, the tool results and the error
+   messages** the agent had just been given. It was reasoning about work it
+   could no longer see. Users reported that the agent "started talking
+   nonsense and would not do my tasks" — it could not, because the task was
+   no longer in the prompt.
+2. The injected message was appended **last**, as `role: "user"`. For a chat
+   model the last user message is the current instruction, so a JSON blob of
+   state displaced the user's actual request.
 
-```json
-{
-  "discovered_flags": [],
-  "tested_hypotheses": [],
-  "active_files": [],
-  "working_dir": "/abs/work/dir",
-  "cmd_summary": "initialized"
-}
+The old test suite asserted the bug — `expect(messages).toHaveLength(1 + 3 + 1)`.
+It is replaced by `tests/opencode/context-integrity.test.ts`, which asserts the
+opposite.
+
+Four rules, each enforced by a test:
+
+| Rule | Enforced by |
+| --- | --- |
+| `notes` mode never mutates `event.messages` | `context-integrity.test.ts` |
+| Never inject behavioural instructions | `system-hint.test.ts` |
+| Inert until a state file exists | `plugin.test.ts` |
+| `paper` mode replaces the context with exactly Aₜ | `paper-mode.test.ts` |
+
+Measured on a live OpenCode 2.0.19, one session, five turns:
+
+```
+turn 1: messages= 3  hint=True  marker=True  override=False
+turn 3: messages= 7  hint=True  marker=True  override=False
+turn 5: messages=11  hint=True  marker=True  override=False
 ```
 
-**3. Register the plugin in `opencode.jsonc`** — add a `file://` entry to the
-`plugin` array (local paths are resolved by OpenCode and imported directly;
-TypeScript is supported because plugins load under Bun):
+The transcript grows. Under the previous version it was pinned at 3.
 
-```jsonc
-{
-  "plugin": [
-    "@ai-sdk/anthropic",
-    "file:///abs/path/to/skillstate.plugin.ts"
-  ]
-}
+### The system fragment
+
+Advisory, bounded, and deliberately dull. It names the state file, renders the
+current notes (a large document is summarized to a key list plus a pointer to
+`skillstate_read`), lists the tools, and says the notes are a side channel
+rather than the task. It contains no "you must", no "always", and no output
+format — that framing is what turned a persistence aid into a prompt override.
+
+The wording is a product requirement, not prose taste, and
+`system-hint.test.ts` fails the build if that framing creeps back.
+
+## Design notes
+
+- **Per-project addressing.** State resolves from
+  `ctx.location.project.canonical`, never `process.cwd()` — one v2 server
+  serves many projects, so the process cwd is the wrong answer.
+- **Sub-agent isolation.** The parent edge comes from the real event stream
+  (`session.created` / `session.forked`, `data.parentID`). A session is
+  scoped to `<parentPrefix>-<full session id>`; the full id, not a prefix, so
+  two siblings sharing an 8-char prefix cannot collapse into one file.
+- **No premature trust.** A session not yet seen on the stream is treated as a
+  root session, which is what a single-session user expects.
+- **Durability.** Every mutation runs under the core cross-process lock and
+  lands via temp-sibling → fsync → rename. Reads never throw.
+- **Bounded prompt cost.** State above 4 KB is summarized rather than inlined,
+  and a patch above 64 KiB is refused with a reason.
+
+## The paper adapter
+
+`OpenCodeAdapter` is still exported. It is the paper-exact `PlatformAdapter`
+(A.4 prompt format) used by the benchmark — it is **not** the host
+integration, and nothing in the plugin path calls it. Note that its
+`injectState` still emits the paper's `STATE_PATCH_CONTRACT`, which is
+exactly the instruction pattern the plugin avoids.
+
+## Tests
+
+```bash
+npm test -- --project opencode
 ```
 
-**4. Install the SKILL.md** — write `adapter.generateSkillMd(spec, statePath)`
-to `~/.config/opencode/skills/skillstate/SKILL.md` (global) or
-`.opencode/skills/skillstate/SKILL.md` (project). Keep the frontmatter fields
-`name` (must match the folder name) and a one-line `description`; the
-generated frontmatter may need a manual trim to those two fields.
-
-Verify with `opencode debug config` (plugin entry shows under `plugin`) and
-`opencode debug skill` (your skill is listed). Hook notes for OpenCode ≥ 1.17:
-`messages.transform` receives `{ info: Message, parts: Part[] }` entries and
-must mutate `output.messages` **in place**; the plugin injects state as a
-synthetic `{ info, parts }` message.
-
-## API / Exports
-
-Root path `@skillstate/opencode` exports the adapter and the static plugin:
-
-- `new OpenCodeAdapter()` — implements `PlatformAdapter` (`name = 'opencode'`).
-- `generateSkillMd(spec, statePath?): string` — a `SKILL.md` body with
-  frontmatter and a state-based process description.
-- `generatePluginCode(options?): string` — a thin plugin loader
-  (`import { createSkillStatePlugin } from '@skillstate/opencode'`;
-  `options.maxHistoryMessages`, default 3). State resolution is always
-  per-project and lives inside the static plugin. Hooks:
-  `experimental.chat.messages.transform` (real history trimming),
-  `experimental.session.compacting` (inject state into compaction context),
-  `tool.execute.after` (persist `state_patch` to disk).
-- `createSkillStatePlugin({ maxHistoryMessages? })` — the static plugin
-  factory (single source of truth for the hook logic); state is resolved from
-  the session cwd on every hook call via
-  `resolveStatePathForCwd(process.cwd(), os.homedir(), agentId)`. The
-  `event` hook registers sub-agent sessions from the host bus
-  (`session.created`/`session.updated` carry `info.parentID`): a sub-agent
-  session resolves to `agents/<parentPrefix>-<sessionPrefix>/` instead of
-  overwriting its parent's state file.
-- `resolveStatePathForCwd(cwd, home?, agentId?): string` — the per-project
-  state path resolution (pure path arithmetic, no filesystem access).
-- `pluginAgentId(input, messages?)` / `scopedAgentId(agentId)` /
-  `registerSessionParent(sessionId, parentId)` / `resetSessionParents()` —
-  the agent-scope plumbing (session id → `agents/` directory name).
-- `readSkillState` / `saveSkillState` / `mergePatch` / `extractPatch` — the
-  plugin's state helpers, shared by the static plugin.
-- `savePluginCode(target, options?): Promise<string>` — writes the plugin
-  atomically and returns the destination. `target` accepts a raw path or a
-  `{ root, name }` ref confined by `resolveStatePath` (`..` escapes throw).
-- `injectState(state, spec): string` / `formatPrompt(state, observation, spec): string`.
-- `extractPatch(response): StatePatch | null` / `extractAction(response): string | null`.
-
-## Notes
-
-- **Real O(1).** Unlike Claude Code (append-only hooks) and Codex
-  (hooks + experimental app-server fork-trim), OpenCode exposes
-  `experimental.chat.messages.transform`, so the plugin drops old messages
-  instead of just hiding them — only the last N non-system messages plus an
-  injected state message reach the LLM.
-- The generated plugin is a **thin loader**: it imports
-  `createSkillStatePlugin` from `@skillstate/opencode` (one source of truth).
-  Hook logic lives only in `src/plugin.ts` — regenerate rather than editing
-  generated files. **WHERE STATE LIVES** (each opencode session reads AND
-  writes the same path within its cwd — no cross-file surprises):
-  - main session: `<cwd>/.skillstate/skillstate.json`
-  - sub-agent session (Task sub-agents carry `parentID` on the session):
-    `<cwd>/.skillstate/agents/<parentPrefix>-<sessionPrefix>/skillstate.json`
-  - a session started in `$HOME`: the global bucket
-    `~/.skillstate/global/...` with the same main/sub split.
-- Depends on [`@skillstate/core`](../core) for `PromptTransformer`,
-  `atomicWriteFile`, and `resolveStatePath`.
-
-## Related
-
-- Paper: [arXiv:2608.26263](https://arxiv.org/abs/2608.26263).
-- Core runtime: [`@skillstate/core`](../core).
-- [`state.md`](../../state.md) — design notes.
-- Other adapters: `@skillstate/claude`, `@skillstate/codex`, `@skillstate/mcp`.
+| File | Covers |
+| --- | --- |
+| `context-integrity.test.ts` | the transcript is never rewritten |
+| `system-hint.test.ts` | the fragment never overrides the model |
+| `session-registry.test.ts` | the v2 event shape, the session tree, eviction |
+| `state-store.test.ts` | addressing, atomicity, merge semantics |
+| `tools.test.ts` | schemas, validation, scoping, refusals |
+| `plugin.test.ts` | setup, teardown, per-project addressing |
+
+Coverage thresholds are 100% on statements, branches, functions and lines.
 
 ## License
 
-[MIT](LICENSE) © 2026 Vitaly Kuzyaev
+MIT

package/dist/feedback.d.ts

@@ -0,0 +1,178 @@
+/**
+ * Corrective feedback for a rejected state patch, in paper mode.
+ *
+ * ── The hole this closes ─────────────────────────────────────────────────
+ *
+ * `PaperStateSink` computed a {@link SinkOutcome} for every assistant text
+ * block and `plugin.ts` discarded it. All seven rejection reasons were
+ * calculated and thrown away, so a model whose `state_patch` failed to parse
+ * received a byte-identical next prompt and no indication that anything had
+ * gone wrong.
+ *
+ * The consequences were not subtle. Σₜ stops moving — a model that has been
+ * silently failing for ten steps sees the same stale state each time and
+ * keeps producing output the integration cannot accept. On a long-horizon
+ * task, which is the entire reason the paper exists, that is total failure
+ * that looks like the model refusing to work.
+ *
+ * `SkillStateRuntime` does not have this problem: it owns the loop, so
+ * `runtime.ts:404` can re-prompt the model with `withRetryFeedback` and try
+ * again inside the same step. A host plugin cannot do that. It cannot invoke
+ * a tool on the model's behalf, and the v2 session API has no response hook
+ * to re-enter the model from.
+ *
+ * ── Where the feedback goes, and why there ───────────────────────────────
+ *
+ * Appendix A.4 gives the model exactly three things: P (instructions), Σₜ
+ * (state), and Oₜ (latest observation). A rejected patch is a fact about the
+ * environment — the integration refused it and can say why. That is an
+ * OBSERVATION, not an instruction, and Oₜ is where observations go.
+ *
+ * Putting it there rather than in P is not a stylistic choice:
+ *
+ * - P is the specification. Appending a correction to P would make the
+ *   prompt shape drift from A.4 and, worse, would inject a *behavioural*
+ *   instruction into the one surface that is supposed to be the operator's
+ *   spec. `tests/opencode/system-hint.test.ts` exists precisely to keep
+ *   behavioural instructions out of the model's view.
+ * - Oₜ is already the mechanism by which the host tells the model what
+ *   happened. Using it keeps the change inside the paper's own shape instead
+ *   of around it.
+ * - The next step's Oₜ is the tool result. Prepending the rejection to it
+ *   means the model reads, in order: what you did was rejected, and here is
+ *   the environment's response, and here is the tool output. That is the
+ *   order the events happened in.
+ *
+ * ── Why the reason is shown once ─────────────────────────────────────────
+ *
+ * A correction that repeats forever becomes wallpaper. By step ten the model
+ * has seen the same complaint nine times and it carries no more information
+ * than a constant line in the prompt would. So a rejection is delivered to
+ * exactly the next prompt and then dropped: if the model fails the same way
+ * again, that is a fresh rejection with a fresh reason, and a reader counting
+ * the prompts can see the failure is ongoing rather than stale.
+ *
+ * This also means feedback is *not* a retry mechanism. It does not re-prompt,
+ * it does not roll back, and it does not count attempts. The host's agent
+ * loop remains the executor, and §7's bounded retry cycle stays where the
+ * paper put it — inside a runtime that can actually own the loop.
+ *
+ * @non-paper — a host-integration affordance. It uses the paper's Oₜ slot but
+ * is not prescribed by the paper.
+ */
+import type { SinkOutcome, SinkRejection } from './response-sink.js';
+/**
+ * A corrective note waiting to be shown to the model, in a plain string.
+ *
+ * Held as a string rather than as a {@link SinkOutcome} because what reaches
+ * the prompt is prose the model can act on, not a type the model can read.
+ * The structured outcome stays in the sink for diagnostics and tests.
+ */
+export type PendingFeedback = string;
+/**
+ * §6.4: the synthetic observation a failed step produces.
+ *
+ * Verbatim in shape from the paper — `Invalid state patch after N attempts:
+ * <last error>` — and the reason it exists rather than a retry continuing is
+ * that a step which has spent its attempts is a different event from one which
+ * is still trying. The model needs to know the step is over and the state was
+ * not written, or it has no way to tell a stalled loop from a slow one.
+ *
+ * Returns `''` when there is nothing to report, because `attempts` below one
+ * means no attempt was made and a synthetic observation describing zero
+ * attempts would be a sentence about nothing.
+ */
+/**
+ * The correction text for one rejection.
+ *
+ * Returns `''` for a reason with no entry rather than throwing or returning
+ * `undefined`. `SinkRejection` is a closed union today, so the table is total
+ * — but it is a `Record` over a type that grows, and a reason added without a
+ * message must degrade to "no correction" instead of throwing. This runs
+ * inside the plugin's event loop, where a throw would end the subscription and
+ * silently stop session scoping for the rest of the process's life.
+ */
+export declare function feedbackFor(rejection: SinkRejection): PendingFeedback;
+/**
+ * Holds at most one pending correction per session.
+ *
+ * Keyed by session, because sub-agents each write their own scope: a
+ * correction for one agent's rejected patch must not be shown to another.
+ *
+ * Bounded by construction — one string per session, overwritten by the next
+ * rejection, dropped once delivered. A long-lived server running many
+ * sessions accumulates one entry per session that has failed, which is the
+ * set of sessions worth reporting on anyway, and never more per session.
+ */
+export declare class FeedbackQueue {
+    private readonly pending;
+    /**
+     * Record the outcome of one block.
+     *
+     * An applied patch CLEARS any pending correction: the model did the right
+     * thing, so a stale complaint must not be carried into the next prompt
+     * alongside good news. Anything else leaves the previous correction in
+     * place, because a second failure before the first was delivered is still
+     * a failure, and the newest reason is the most useful one.
+     */
+    record(sessionID: string, outcome: SinkOutcome): void;
+    /**
+     * Take the pending correction for a session, if any, and clear it.
+     *
+     * Consuming on read is what makes the correction show up exactly once. A
+     * caller that only ever peeked would turn a one-step correction into a
+     * permanent line in the prompt.
+     */
+    take(sessionID: string): PendingFeedback | undefined;
+    /** Peek without consuming. For diagnostics and tests. */
+    peek(sessionID: string): PendingFeedback | undefined;
+    /**
+     * Take the pending correction only if no synthetic observation is owed.
+     *
+     * §6.4: when every attempt fails, the step's observation is the synthetic
+     * `Invalid state patch after N attempts: <last error>` — not the running
+     * correction, and not nothing. Delivering both would show the model two
+     * complaints, one of which is stale by definition: the correction belongs to
+     * the attempt that just ended, while the synthetic observation reports the
+     * whole step.
+     *
+     * The correction is still cleared when it is dropped. Holding it would put
+     * the same reason in front of the model a second time, on the next step,
+     * where it would be describing a step that is over.
+     */
+    takeUnlessInvalidated(sessionID: string, attempts: number, lastError: string | undefined): PendingFeedback | undefined;
+    /** Forget everything (test isolation, plugin reload). */
+    clear(): void;
+    /** How many sessions currently hold a pending correction. */
+    get size(): number;
+}
+/**
+ * Prepend a correction to an observation.
+ *
+ * The observation is a single line in A.4 (`Latest Observation: …`), so the
+ * two are joined on one line rather than separated by a blank line that the
+ * template does not have. The correction is marked so the model can tell it
+ * apart from environment output — without a marker, a correction would be
+ * indistinguishable from a tool result, and the model could reasonably read
+ * it as data rather than as a report about its own last turn.
+ *
+ * A blank observation is left to carry the correction alone rather than
+ * becoming `"prefix: "`, which would read as a message addressed to nobody.
+ */
+export declare function applyFeedback(observation: string, feedback: PendingFeedback | undefined): string;
+/**
+ * Prepend a line from the environment to the observation slot.
+ *
+ * Shared by the two things the environment has to say to the model — a patch
+ * it refused, and an action it is carrying out — because they need the same
+ * shape and must not be told apart by accident.
+ *
+ * The marker is a parameter for exactly that reason. An earlier version reused
+ * {@link applyFeedback} for both, and the hard-coded
+ * `[state patch rejected]` would have told the model its patch was refused at
+ * the very moment the runtime was accepting it and asking for the next step —
+ * a message not merely useless but actively false, and the kind of false that
+ * makes a model re-derive state it has already recorded.
+ */
+export declare function applyObservation(observation: string, marker: string, line: string): string;
+//# sourceMappingURL=feedback.d.ts.map

package/dist/feedback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"feedback.d.ts","sourceRoot":"","sources":["../src/feedback.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAErE;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC;AAkCrC;;;;;;;;;;;;GAYG;AACH;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,SAAS,EAAE,aAAa,GAAG,eAAe,CAErE;AAED;;;;;;;;;;GAUG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsC;IAE9D;;;;;;;;OAQG;IACH,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,IAAI,CAUpD;IAED;;;;;;OAMG;IACH,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAKnD;IAED,yDAAyD;IACzD,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAEnD;IAED;;;;;;;;;;;;;OAaG;IACH,qBAAqB,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,eAAe,GAAG,SAAS,CAQrH;IAED,yDAAyD;IACzD,KAAK,IAAI,IAAI,CAEZ;IAED,6DAA6D;IAC7D,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAC3B,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,eAAe,GAAG,SAAS,GACpC,MAAM,CAGR;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAC9B,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,GACX,MAAM,CAGR"}