@akanjs/cli 3.0.0-alpha.41 → 3.0.0-alpha.42

package/.build-stamp

@@ -1 +1 @@
-ebe6f07427135e1b11548007c742cfa1e62256965f0de2c84b3f816d97ef8688
+eaeb44245969a1707e38a765624a1541652e2558214acaf1d91d2be618ba8bbe

package/guidelines/conventions/conventions.instruction.md

@@ -689,6 +689,13 @@ apps and libs never import it directly (`no-import-external-library`) — everyt
   providers the way middleware is applied: `option.applyAdaptor(LlmAdaptorRole, ClaudeLlm)`, where the
   implementation is an `adapt()` class in a `srvkit/` implementing `LlmAdaptor.chat(request, onDelta?)` — ignore
   `onDelta` and the chat still answers whole.
+- **An adaptor answers `null` for "not configured" and *throws* for a refusal it can explain.** The two are
+  different things to be told: collapsing both into `null`, the way the adapter convention otherwise reads, left a
+  user reading `llmUnavailable` — "no model is configured" — about a conversation that had merely outgrown the
+  context window. A thrown `Err` reaches the chat as its own text, so the reason the provider gave is what the
+  user sees. It travels as the dictionary key plus the values that key interpolates, on both the JSON and the SSE
+  path, and **`fetchRunner` resolves it against the dictionary one step before the transcript** — the endpoint has
+  no language to resolve it in and the browser does, which is why the key was reaching the screen raw.
 - **A file the user attaches rides the message, and nothing is stored.** The composer takes a paperclip, a drop and
   a paste; an image rides as bytes and a text file as text, which is all a browser reads with no dependency.
   Everything else is the app's own reader — `<Agent.Chat attach={…} />`, one `File` in, a `MessageAttachment` or
@@ -897,9 +904,9 @@ apps and libs never import it directly (`no-import-external-library`) — everyt
 - **`prompt()` endpoints double as the chat's slash commands.** There is no listing endpoint — the client reads
   its own serialized signals — so a prompt's dictionary `.desc()` is what the menu shows, and its guards are
   enforced by the prompt's own GET at call time.
-- **The chat answers five slash commands of its own**, listed in the same `/` menu ahead of the prompts:
-  `/new` (`/clear`), `/retry`, `/copy`, `/help` and `/tools`. An app writes none of them and cannot add one — the
-  extension point for a product's own command is a `prompt()` endpoint, which is guarded and server-side.
+- **The chat answers six slash commands of its own**, listed in the same `/` menu ahead of the prompts:
+  `/new` (`/clear`), `/retry`, `/compact`, `/copy`, `/help` and `/tools`. An app writes none of them and cannot add
+  one — the extension point for a product's own command is a `prompt()` endpoint, which is guarded and server-side.
   **A built-in wins a name collision with a prompt of the same name**, the mirror image of the tool rule: a
   component's `st.tool` shadows a built-in it means to replace, but no library's prompt may take `/new` away from
   the user who typed it — so a shadowed prompt is dropped from the menu rather than listed twice. `/new` and
@@ -916,6 +923,22 @@ apps and libs never import it directly (`no-import-external-library`) — everyt
   only in that browser, so an export is the one path a wrong answer has to whoever could fix it — which is why it
   carries the route and the timestamp. `/retry` replays only the trailing user message, leaving anything before it
   in place, so a prompt's own preamble is not sent twice.
+- **A long conversation summarizes itself, because nothing else is keeping it inside the model's window.** The
+  loop runs in the browser and the relay holds no session, so an uncompacted chat grows until the provider
+  refuses the whole request — a refusal, never a shorter answer, which is why compaction runs *before* the turn
+  that would have overflowed rather than as a recovery after it. Past `compact.at` estimated tokens (four
+  characters to a token, over the JSON the turn posts; 24k by default, well under the smallest window a provider
+  is likely to have, since the tools and the screen context ride on top of it and neither compacts) the history above the last `keep` messages
+  becomes one message standing in for it, flagged `summary` on the wire — `<Agent.Chat compact={{ at, keep }} />`
+  tunes it per provider and `{ at: 0 }` turns it off, and `/compact` does the same on demand keeping nothing.
+  **The cut only ever lands on a user message**: everything above one is settled, so the kept half can never open
+  with a `tool` result whose call was summarized away, a shape every provider dialect rejects. The summarizing
+  turn carries no tools and no screen context — it summarizes the conversation, it does not act on it — and it is
+  fed a *bounded* digest rather than the transcript itself, since the transcript being summarized is the one that
+  no longer fits. A summary that cannot be produced leaves the transcript alone and the turn goes out as it would
+  have; one that fails to shrink anything is not retried until another threshold's worth has been added. On the
+  wire a summary wears the user's role because the wire has no other, so a provider mapping frames it as a system
+  message and `/retry` steps over it — replaying it would send the notes back as a question.
 - **↑ and ↓ in the composer walk what was sent.** A single-line input has nothing of its own on the vertical
   arrows, and the half-written draft they were walked away from comes back at the bottom of the walk.
 - The framework publishes six built-ins on every store surface: `navigate` (internal paths only, the same
@@ -939,12 +962,13 @@ apps and libs never import it directly (`no-import-external-library`) — everyt
   `maxTurns` budget in seconds on a job measured in minutes. Say so in the `desc` ("takes about two minutes; do
   not poll while it runs") and, for a route full of slow work, in an `Agent.Guide`.
 - **`waitFor(key, equals?, timeoutSeconds?)` is for the job the *tool* cannot await** — started in an earlier turn,
-  or by a person clicking the button. It parks on a published state key, the ones `readState` lists, and resumes
-  the moment the key moves; `equals` waits for one value, omitted it waits for any change. Deliberately not a bare
-  sleep: a sleep only makes the polling slower, and a screen able to report progress reports it into the store, so
-  a screen that reports none publishes a key with `st.expose` — worth doing anyway, since the key becomes readable
-  too. Running out is not a failure, it answers with what the key holds now (default 120s, clamped to 600), and a
-  key this screen does not read is refused by name with the ones it does.
+  or by a person clicking the button. It parks on a **store state key a mounted component subscribes**, exactly the
+  set `readState` reads, and resumes the moment the key moves; `equals` waits for one value, omitted it waits for
+  any change. **Not a resource**: `st.expose` and `st.useState` register on the surface, whose values already ride
+  inline in the screen context block, and `waitFor` refuses one of those names like any other. Deliberately not a
+  bare sleep either — a sleep only makes the polling slower, and a value worth waiting minutes for is server-derived
+  state, which lives in the store already. Running out is not a failure, it answers with what the key holds now
+  (default 120s, clamped to 600), and a key this screen does not read is refused by name with the ones it does.
 - **Stop reaches a tool that is still running.** The session races every call against its abort signal, so a
   two-minute tool does not hold the loop for two minutes after the user presses Stop. The signal itself arrives
   through `AgentAbort.current` — the same module slot `AgentProgress` is — and honouring it is optional, since the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/cli",
-  "version": "3.0.0-alpha.41",
+  "version": "3.0.0-alpha.42",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -34,7 +34,7 @@
     "@langchain/openai": "^1.4.6",
     "@tailwindcss/node": "^4.3.0",
     "@trapezedev/project": "^7.1.4",
-    "akanjs": "3.0.0-alpha.41",
+    "akanjs": "3.0.0-alpha.42",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "dayjs": "^1.11.20",