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

package/.build-stamp

@@ -1 +1 @@
-d8a476b01467d4b59495cc5a6332930a9ce6ba7001dd3a4bf3510bf13d6cd839
+da606dd0b2a1010436ae9ad72c5058abda8aa897bc1151dc063c247b76761373

package/guidelines/conventions/conventions.instruction.md

@@ -968,13 +968,15 @@ apps and libs never import it directly (`no-import-external-library`) — everyt
   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
+- The framework publishes five 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 —
   headings, links, control values, and `(disabled)` on a control or button that has it; the chat's own UI is
-  skipped via `data-agent-ui`, and a password value is never read), `readState(key)` (one masked store key),
-  `waitFor(key)` (park until that key moves), and `highlight(target)`. Declaring a hook tool under one of those
-  names shadows the built-in, so reuse them only to mean that.
+  skipped via `data-agent-ui`, and a password value is never read), `readState(key)` (one masked store key), and
+  `highlight(target)`. Declaring a hook tool under one of those names shadows the built-in, so reuse them only to
+  mean that. **There is no general-purpose wait**: a built-in one was reachable on every screen and a model spent
+  it on whatever key it liked, parking turns nobody asked to park. Waiting belongs to the screen that knows what
+  is worth waiting for — publish an `st.tool` beside the control that starts the work, and let it await the work.
 - **A tool that changes the screen waits for the screen before it answers.** `router.push` returns while the RSC
   payload is still in flight and a store action that fires `void fetch.*` commits a tick later, so `navigate`
   awaits `ScreenSettle.wait()` — DOM quiescence, bounded, because the client router hands its promise to nobody —
@@ -988,14 +990,14 @@ apps and libs never import it directly (`no-import-external-library`) — everyt
   call to read the result. A fire-and-forget tool leaves the agent to poll instead, which burns the whole
   `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 **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.
+- **A wait is a screen's own tool, declared where the slow work is.** For the job a tool cannot await — one
+  started in an earlier turn, or by a person clicking the button — publish an `st.tool` that parks on the thing
+  *that* screen knows about, and say in its `desc` what it waits for and roughly how long. A general built-in was
+  tried and removed: reachable on every screen with no idea what any key means, a model spent it on whatever key
+  looked promising and parked turns nobody asked to park. The screen that starts the work is the only place that
+  knows what finishing looks like, and a tool declared there is also one the agent cannot reach on a screen where
+  waiting makes no sense. Honour `AgentAbort.current` in the body and report with `AgentProgress.report`, so Stop
+  ends the wait and the row says how it is going.
 - **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.43",
+  "version": "3.0.0-alpha.44",
   "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.43",
+    "akanjs": "3.0.0-alpha.44",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "dayjs": "^1.11.20",