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

package/.build-stamp

@@ -1 +1 @@
-eaeb44245969a1707e38a765624a1541652e2558214acaf1d91d2be618ba8bbe
+d8a476b01467d4b59495cc5a6332930a9ce6ba7001dd3a4bf3510bf13d6cd839

package/guidelines/conventions/conventions.instruction.md

@@ -680,7 +680,11 @@ apps and libs never import it directly (`no-import-external-library`) — everyt
   guard classes every endpoint takes (an array is ANDed, `null` clears what a library set); without one the chat
   cannot spend the LLM key.
   `persist` keeps the transcript across reloads (sessionStorage; `{ storage: "local" }` to outlive the tab),
-  default off. Re-skin through the `AgentChat` slot in `_overrides.tsx`.
+  default off, and `shortcut={false}` gives the browser back the Cmd/Ctrl+L the launcher otherwise captures.
+  **A session the chat made ends when the chat unmounts** — nothing renders its approvals once it is gone, so a
+  turn left running would drive a screen the user has navigated away from; a session handed down by an
+  `AgentProvider` or an `Agent.Zone` belongs to whoever provided it. Re-skin through the `AgentChat` slot in
+  `_overrides.tsx`.
 - **The LLM is configured in `option.ts`, never through the environment.** `option.setLlm({ apiKey, model, host })`
   — or `setLlm((options) => …)` to read the key out of the app's own env object, which is where a secret belongs —
   fills whichever adaptor holds `LlmAdaptorRole`, reaching it as the `llmOption` use. The settings are the role's
@@ -709,12 +713,18 @@ apps and libs never import it directly (`no-import-external-library`) — everyt
   reaches the chat as an attachment rather than the literal `[image]` it used to become. Persisting keeps each
   attachment's name and drops its content: web storage is a few megabytes, one screenshot fills a chunk of it, and
   a save that fails is silent — so keeping the bytes would quietly stop keeping the transcript.
+  **The ceilings are the message's, not the file's**: 4 MB per file, 8 MB and five files per message, and the same
+  file twice is refused by name. The bytes ride inside one turn's JSON, so what a provider refuses is the sum —
+  and a request that cannot be sent is one the user has to empty the composer to escape, which is why the refusal
+  happens at the paperclip and names the file it dropped.
 - **Speech is one engine contract and the framework's own policy.** `<Agent.Chat voice={engine} />` takes a
   `VoiceEngine` — `listen(handlers)` and `speak(sentence)`, both cancellable — and the chat decides everything
   else: a press-to-talk microphone whose transcript lands in the composer to be corrected, one utterance per
   press, sentence-at-a-time reading, barge-in on the next press or on Stop, and markdown stripped so `**bold**`
   is not pronounced. **A reply is read aloud only when the ask arrived by voice**, so a typed question never turns
   on the speakers — and it needs no wire field, because how a message was sent is the composer's own business.
+  A question or an approval the loop parked on is read aloud under that same condition, because the loop stops
+  there: a voice user who is never told about the card is a conversation that simply ends.
   The contract is a subscription rather than `listen(): Promise<string>` on purpose: a promise fits push-to-talk
   and nothing else, so hands-free could then only arrive as a breaking change. `useSpeech` in
   `libs/util/webkit` is the engine — the browser's own recognition and synthesis on the web, the Capacitor
@@ -903,17 +913,20 @@ apps and libs never import it directly (`no-import-external-library`) — everyt
   read unless a `mask:` model is named — the same rule and wording as `AgentBridge.read`.
 - **`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.
+  enforced by the prompt's own GET at call time. Arguments are positional and whitespace-separated, and quoting
+  is how a sentence stays one of them (`/reviewTask t1 "look at the totals"`) — a prompt taking a single `String`
+  is the common case, and an unquoted sentence would fill its second parameter with the second word.
 - **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
-  `/copy` are also dispatched *before* the is-a-turn-running check, because mid-turn is exactly when they are
-  reached for; `/new` therefore aborts the turn it is clearing and waits for it to wind down, since the loop
-  clears its own running flag a microtask later and a transcript emptied before that lands is one the dying turn
-  appends onto.
+  `/copy` are also dispatched *before* the is-a-turn-running check **and before the question card takes the
+  composer**, because mid-turn is exactly when they are reached for and a question the agent asked is the middle
+  of a turn like any other — answered as text, `/new` would have reached the model as the user's decision.
+  `/new` therefore aborts the turn it is clearing and waits for it to wind down, since the loop clears its own
+  running flag a microtask later and a transcript emptied before that lands is one the dying turn appends onto.
 - **A command's output is a `local` message: rendered in the transcript, withheld from the wire.** The transcript
   *is* the model's history, so `/help` text appended plainly would come back next turn as something the assistant
   believes it said. `session.note(text)` is the only way to write one, `session.report(error)` stays what a
@@ -939,8 +952,22 @@ apps and libs never import it directly (`no-import-external-library`) — everyt
   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.
+- **A stopped turn answers the calls it never ran, because an unanswered call ends the conversation.** Every
+  provider dialect refuses an assistant message whose `tool_calls` have no results — on that turn and on every
+  later one — so Stop landing between a call and its result would leave a transcript nothing can be sent from,
+  with no way out but `/new`. `Transcript.sanitize` holds the invariant in one place and runs where a transcript
+  is assembled rather than where each hole is made: the turn's own request, a transcript restored from storage,
+  and a stored transcript capped to its newest messages, whose window can start mid-pair. A call the loop never
+  reached is *answered* rather than erased — a model told the call was stopped asks again, where one shown no
+  call at all answers as if it had the result.
+- **A turn that failed says so on the wire.** `error` is a field only this wire has, so a provider mapping reads
+  `text` and drops it; `AgentService.explained` folds it into the text before any adaptor sees it, because an
+  assistant turn that says nothing is one the model repeats.
+- **↑ and ↓ in the composer walk what was sent**, seeded from the transcript so a persisted chat does not lose
+  only what was just typed. 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 `/` menu takes those
+  keys while it is open** — it is the thing on screen the arrows point at — with Enter picking the highlighted
+  row, Tab completing its name, and Escape closing the menu and then, pressed again, the panel.
 - The framework publishes six built-ins on every store surface: `navigate` (internal paths only, the same
   router `Link` rides), `goBack` (this session's history — global, because history is not a control a page owns and
   a page that draws no back link is not one you may not leave), `readScreen` (the rendered DOM as compact text —

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/cli",
-  "version": "3.0.0-alpha.42",
+  "version": "3.0.0-alpha.43",
   "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.42",
+    "akanjs": "3.0.0-alpha.43",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "dayjs": "^1.11.20",