@akanjs/cli 3.0.0-alpha.53 → 3.0.0-alpha.55

package/.build-stamp

@@ -1 +1 @@
-75e6ebc02c938b9bfa7b3bbce9bbe0a59753853c08b168184806c0321e3bb71e
+3dcdd65ef34286ed395d168f590ad6a2698d350ab28abc84526d3e3781eae948

package/guidelines/agentRule/agentRule.instruction.md

@@ -27,6 +27,14 @@ apps and libs never import it directly (`no-import-external-library`) — everyt
   cannot spend the LLM key.
   `persist` keeps the transcript across reloads (sessionStorage; `{ storage: "local" }` to outlive the tab),
   default off, and `shortcut={false}` gives the browser back the Cmd/Ctrl+L the launcher otherwise captures.
+  **`persist` also takes a `SessionHistory` of the app's own** — `{ load, save, clear }` — which is how a
+  transcript lives on a server instead of in web storage. All three may answer asynchronously; a `load` still in
+  flight when the user sends the first message is **dropped, not merged**, because the conversation on screen is
+  the one they are having — which makes **sending on mount a race the restore loses**, so an opening prompt waits
+  for `session.isRestoring` to clear or goes into `defaultDraft` and lets the user send it. Saves are chained rather than fired per change, so a slow store cannot land an older
+  transcript last. **Every session option on the chat — `runner`, `instructions`, `maxTurns`, `compact`,
+  `builtins`, `persist`, `onCompact` — is ignored when an enclosing `Agent.Zone` or `AgentProvider` already holds
+  a session**: the chat binds to that one, and the options belong to whoever built it.
   **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.
@@ -34,7 +42,10 @@ apps and libs never import it directly (`no-import-external-library`) — everyt
   `open` / `onOpenChange` drive it from the app's own control (`launcher={false}` then draws no launcher of its
   own), `launcherClassName` / `panelClassName` reach one surface each where `className` reaches both, `intro`
   replaces the empty-state line — where starter questions go — and `header` adds controls beside the built-in
-  clear and close. Then the slots: `AgentLauncher`, `AgentBubble`, `AgentComposer`, `AgentApproval`,
+  clear and close. `chrome={false}` drops the header bar whole, for an `inline` chat inside a panel the app
+  already titles, and `defaultDraft` opens the composer with text in it without sending it. A panel driven by a
+  controlled `open` with **no** `onOpenChange` draws no close button at all rather than an inert one. Then the
+  slots: `AgentLauncher`, `AgentBubble`, `AgentComposer`, `AgentApproval`,
   `AgentQuestion`, `AgentMenu`, `AgentMarkdown` and `AgentCode` each replace one part in `_overrides.tsx`, and
   `akanjs/ui` exports every default beside them (`DefaultBubble`, `DefaultComposer`, …) so a skin composes the
   one it is replacing. `AgentCode` is where a highlighter binds — the fence's language reaches it — and a
@@ -112,6 +123,24 @@ apps and libs never import it directly (`no-import-external-library`) — everyt
   `data-agent-zone` container; guides follow the layout cascade (ancestors and own, never a sibling's). Zone
   membership is positional — there is no per-declaration zone key, so a lib component joins whatever zone the app
   mounts it in.
+- **`builtins` decides which of the runtime's own tools a session gets** — all of them by default, `false` none,
+  an array exactly the ones it names, on `Agent.Zone` and `Agent.Chat` alike. A zone whose conversation must stay
+  on one screen takes `navigate` and `goBack` off it: `<Agent.Zone id="wizard" builtins={["readScreen",
+  "readState"]}>`. The tools are **withheld, not discouraged** — a withheld name answers the same "unknown tool"
+  a name that was never registered gets, so no prompt can talk the model past it, and the narrowing is the
+  session's alone: the surface is shared, and the neighbouring zone still navigates. Shadowing a built-in by
+  declaring a hook tool of the same name works at the root and **not inside a zone**, where the hook entry is
+  registered under its scope-prefixed name and never collides — `builtins` is the zone's answer. A tool the screen
+  declares under a built-in name is the screen's, not the runtime's, so `builtins={false}` leaves it standing.
+- **A zone can be handed a session instead of building one**: `<Agent.Zone session={mine} onSession={…}>`. The app
+  then owns it, so unmounting the zone leaves it running — the opposite of a session the zone made, which it
+  aborts. `onSession` fires either way, for a page that wants to send into the conversation from outside it.
+- **`akanjs/ui` exports what a custom transport or transcript needs**, so no app reaches into the package's
+  internals: `httpRunner` (the wire the default runner speaks — point it at an endpoint of the app's own and
+  streaming is kept), `fetchRunner` (the default, to wrap), `AgentSession`, `AgentProvider`, and the
+  `AgentRunner` / `RunnerRequest` / `RunnerEvent` / `ChatMessage` / `SessionHistory` / `PublishedTool` /
+  `ContextBlock` types. `onCompact(replaced, summary)` reports a compaction's cut, for a host that keeps a
+  server-side summary and has to move its own watermark to the same place.
 - **Route guidance is `<Agent.Guide instructions="..." />`** rendered from a `_layout.tsx` or a page — the render
   tree is the cascade: nested Guides concatenate outer-to-inner and navigating away withdraws them. It is a
   component, not a pageConfig field. Module `*.abstract.md` files are developer docs and are never served to the
@@ -386,7 +415,8 @@ apps and libs never import it directly (`no-import-external-library`) — everyt
 ## Built-In Tools
 - 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 —
+  a page that draws no back link is not one you may not leave — a screen that must not be left withholds them
+  with `builtins`, not with prose), `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), and
   `highlight(target)`. Declaring a hook tool under one of those names shadows the built-in, so reuse them only to

package/guidelines/conventions/conventions.instruction.md

@@ -96,6 +96,17 @@ back.
   the resolved data as a prop. A component is a PascalCase binding whose own initializer is `async`, so an async
   handler declared inside a synchronous component, an inline `onClick={async () => …}`, and
   `lazy(async () => import(…))` are all untouched.
+- **Never call `fetch.init*` from a client file** (`no-init-fetch-in-client.grit`). `fetch.init<Model><Suffix>` and
+  `fetch.get<Model>Init<Suffix>` compose the slice's list and insight queries into the hydration snapshot that
+  `Load.Units` / `Load.View` seed the store from. From a route it resolves before the first byte; after hydration it
+  is two extra round-trips for a shell the browser already painted, landing in a value nothing reads. Load it in the
+  page and pass the result down as an `init` prop — or hand the unawaited promise across — and reload from the client
+  through the generated `st.do.init<Model><Suffix>()`. The gate is the file: the real `"use client"` directive (the
+  same text as a string literal or inside sample code is not one) plus `*.store.ts`, which is client-only by role and
+  carries no directive. The name is matched by shape, since a lint rule cannot know which slices exist: the
+  generated one always carries two capital-led segments (`init` + `Capitalize<refName>` + `Capitalize<suffix>`), so
+  a hand-written `initPayment` is out and `initializeSomething` was never in. `view` / `edit` hydrate alike but are
+  left unmatched — `edit<X>` is a plausible custom endpoint name.
 - `noArrayIndexKey` and `useExhaustiveDependencies` are **off** on purpose: `key={idx}` for embedded scalars and
   short dependency arrays are intentional, not oversights.
 - **A grit plugin diagnostic is suppressed as `lint/plugin`, not `plugin`** — `// biome-ignore lint/plugin: <reason>`
@@ -607,10 +618,13 @@ commands, transcript compaction, and the built-in tool semantics: `get_guideline
   `filter` 0): `title` is the one line a human scans for, `desc` is prose, `tag` is a keyword list, `filter` is a
   scoping value (status, owner, role) that must be matchable but must never outrank a real title hit.
 - `thumb` is mirrored for rendering a hit and is **not** indexed — never expect it to match.
-- **A `secret`, `hidden`, or `resolve()` field with `text` throws at class-build time**, not at query time. That is
-  deliberate: the mirror is plaintext, so an indexed secret would leak through search. Do not work around it. The
-  same throw covers a `text` field *underneath* one of those — a scalar's own field is reachable through its parent,
-  so `f.secret(Noti)` where `Noti.label` carries a role is rejected at the parent, not silently indexed.
+- **`field.secret`, `field.hidden` and `resolve()` take no `text` role — it is a compile error**, because the
+  mirror is plaintext and an indexed secret would leak through search. The class build throws the same refusal as
+  a backstop, for an option object the excess-property check cannot see through, and names the way out: drop the
+  role, or leave the field unmasked. Do not work around either. The throw also covers a `text` field *underneath*
+  one of those — a scalar's own field is reachable through its parent, so `f.secret(Noti)` where `Noti.label`
+  carries a role is rejected at the parent, not silently indexed; that one is only reachable at runtime, since the
+  pairing spans two files.
 - The role works on a relation too (`image: field(File, { text: "thumb" })`) and on an array (`playing: field([String],
   { text: "tag" })`); an array of objects indexes by leaf key, including an array leaf (`works[*].tags`). A field
   inside a `Map` indexes nothing: there is no fixed path to extract it from.

package/package.json

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