@akanjs/cli 3.1.0-rc.13 → 3.1.0-rc.15

package/.build-stamp

@@ -1 +1 @@
-7bcd4fe279524ed2759e02783eb078a66b8ee0e6acee19a817c2f751ecba695a
+0462ae6cd06c1ee2d9d1dfa1d0d7da7a3b795b2312f3094265c359e2ac042d60

package/guidelines/agentRule/agentRule.instruction.md

@@ -180,6 +180,14 @@ pages declaring one name never clash, and a registry kept outside the surface re
   stores its uploads keeps a map beside the transcript keyed on name and size — the same guess `Attachment.same`
   has to make, and the one that is wrong for two crops of one export. So when both sides carry a `ref`, it *is* the
   answer to "the same file twice", and the heuristic is what is left for when they do not.
+- **A tool hands the model a file with `ToolReturn.attach(result, [attachment])`** (`akanjs/store`), which lands in
+  `ToolCallResult.attachments` beside the value — a `result` reaches the model as JSON text, so a URL in it is read
+  as letters and base64 as a wall of them. It takes a user attachment's shape and meets the same `accepts` check and
+  type allow-list; Anthropic carries it inside the `tool_result`, the chat-completions dialect (whose `tool` message
+  holds text alone) in one user message after the turn's tool messages. It is outside the 20,000-character ceiling
+  and held to the 4 MB per-file one, and only the latest turn's ride as bytes: an earlier one becomes a note telling
+  the model to call the tool again while the picture is on screen, since one picture costs over a thousand tokens on
+  every turn it rides.
 - **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
@@ -398,6 +406,10 @@ pages declaring one name never clash, and a registry kept outside the surface re
   renders one editor per row, and at most one of them is ever open, so one name is registered rather than fifty.
   It also means the verb is absent from the catalogue while nothing is open, which is honest — and costs the
   agent nothing, because the catalogue is re-read on the turn that follows the tool call that opened the form.
+- **A shell's `submit<Model>` refuses while an upload is in flight.** `Model.EditModal` (also while its submit is
+  disabled) and `Model.ViewEditModal` disable the button and answer `The <model> form is not ready to submit.` while
+  `<model>FormUploading` is not empty. That key is read `{ agent: false }`, so the refusal is how an agent learns of
+  the upload: call `submit<Model>` again once the file has landed, rather than setting the field a second time.
 
 ## Forms
 - **A form control publishes its own setter, and reading a form publishes one tool that fills several at once.**
@@ -614,14 +626,17 @@ pages declaring one name never clash, and a registry kept outside the surface re
   row, Tab completing its name, and Escape closing the menu and then, pressed again, the panel.
 
 ## Built-In Tools
-- The framework publishes five built-ins on every store surface: `navigate` (internal paths only, the same router
+- 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 — 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 — a key that is unknown or that this screen does not read is refused
-  *with the keys it can* read, the way `readScreen` names its sections), 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**:
+  *with the keys it can* read, the way `readScreen` names its sections), `highlight(target)`, and `viewImage(src)` (one
+  `<img>` on screen, redrawn as a JPEG at most 1568px long and attached to the result — `src` must be one this view
+  shows, as `readScreen({ images: true })` printed it, so the agent cannot have the browser fetch an address of its
+  own, and a `data:` one is refused). 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.
@@ -630,8 +645,8 @@ pages declaring one name never clash, and a registry kept outside the surface re
   awaits `ScreenSettle.wait()` — DOM quiescence, bounded, because the client router hands its promise to nobody —
   and the session awaits it after every tool that did not declare `settle: false` before taking the change report.
   Without it the report describes the moment before the change landed and the `readScreen` that follows reads the
-  page the user left. The reading built-ins (`readScreen`, `readState`, `highlight`) declare it, because a wait
-  costs 120ms of quiet at the very least and they change nothing a resource holds.
+  page the user left. The reading built-ins (`readScreen`, `readState`, `highlight`, `viewImage`) declare it,
+  because a wait costs 120ms of quiet at the very least and they change nothing a resource holds.
   New tools and state from a fresh route are still only listed from the next turn: the catalogue is snapshotted
   when the turn starts.
 - **A tool that waits for its own work costs no model turns; one that returns early costs one round trip per
@@ -665,8 +680,8 @@ pages declaring one name never clash, and a registry kept outside the surface re
 - **An image is always named, and its address rides only when asked for.** `readScreen` prints `[image: <alt>]`,
   and `[image]` for one with no `alt` — dropping the unlabelled one left a card that renders a picture reading
   exactly like a card that renders nothing, and "this page shows no image" is the one answer the screen cannot
-  support. `readScreen({ images: true })` appends `(<src>)` to each, for handing one to a tool that takes a
-  picture; it is off by default because a gallery is one long URL per thumbnail, which is the read's whole budget
+  support. `readScreen({ images: true })` appends `(<src>)` to each, for handing one to `viewImage` or another tool
+  that takes a picture; it is off by default because a gallery is one long URL per thumbnail, which is the read's whole budget
   spent on the part of the screen it can say the least about. A `data:` URL is never printed — that is the bytes
   themselves rather than somewhere to fetch them.
 - **A screen is only aimable if its names are printed.** `readScreen` writes `(#anchor)` beside a heading that

package/guidelines/conventions/conventions.instruction.md

@@ -374,8 +374,8 @@ orchestration in `service`, client state in `store`; `Template` is forms, `Unit`
 ### Calls, Queries, Agents (summaries)
 
 - **Wire (`transportRule`)**: a deadline is the endpoint's `{ timeout: <ms> }` (undeclared, the client quits at
-  30 s; the handler is not cancelled); `{ cache }` only on a `query` with no internal argument, dropped early by
-  `invalidate(endpoint, args?)` on a plugged `EndpointCacheControl`; `{ rateLimit }` per endpoint,
+  30 s; the handler is not cancelled); `{ cache }` only on a `query` with no internal argument, capped at one day,
+  dropped early by `invalidate(endpoint, args?)` on a plugged `EndpointCacheControl`; `{ rateLimit }` per endpoint,
   `option.setRateLimit` per app, `plug(RateLimit)` for a business key. `socketId` names a connection, not a caller. A
   device proves itself with a `MachineToken`. Server to server, `fetch.clone({ origin })` opens no socket
   without `connect: true`, retries through `retry`, and rethrows a remote `Err` as is — never wrapped or re-keyed.
@@ -417,6 +417,10 @@ orchestration in `service`, client state in `store`; `Template` is forms, `Unit`
   `plug(StorageAdaptorRole)` · `use<T>()` only for a legacy `option.ts` singleton · `env(...)` for config.
 - `memory(...)` takes a scalar or model class (`memory(Map, { of: CallStateInput })`); never hand-encode JSON into a
   `String` memory.
+- A file your own code stored through `plug(StorageAdaptorRole)` has its disk path at
+  `storage.resolveLocalPath?.(path, access)` (`fieldRule`): `null` means refused (answer 404, never fall back to
+  `readData()`), `undefined` means the adaptor keeps no local files, and a key that comes from a request passes
+  `access: "public"`. A `File` field is not one: `libs/shared` stores it through its own `StorageApi`.
 - **A new adapter is an `adapt()` singleton in `srvkit/`**, injected with `plug(TheClass)`, key `as const`. Never
   register it in `lib/option.ts` (it self-registers); never construct a `Logger` in it (`this.logger` exists);
   lifecycle work in `override async onInit()`. A per-use value object is a plain class. Legacy

package/guidelines/modelStore/modelStore.instruction.md

@@ -42,6 +42,13 @@ Generate client state coordination for a module. Store connects generated fetch
 - A model whose form holds a large `field.visual` body can pass the 256KB per-draft cap, and a draft over it is
   dropped with a warning rather than truncated.
 
+## File Uploads
+- `upload<Field>On<Model>(fileList, idx?)` is generated for every `File` field. `Field.Img` / `Imgs` / `File` /
+  `Files` handed the generated `set<Field>On<Model>` upload through it, so do not write an upload action.
+- `<model>FormUploading` holds the uploads in flight per field (`{}` when idle). The generated submit paths save
+  nothing until it is empty; a hand-written submit reads `Object.keys(st.use.<model>FormUploading()).length`. Full
+  contract: `fieldRule`.
+
 ## Review Checklist
 - The instruction points to current docs pages, not removed docs routes.
 - Generated examples use current Akan builder APIs and scanner-friendly filenames.

package/guidelines/workspaceRecipes/workspaceRecipes.instruction.md

@@ -571,6 +571,8 @@ akan sync automatically generates APIs across all layers. Only write custom logi
 | `[slice]List`, `[slice]InitList`, `[slice]Insight`, `[slice]Selection`, `hasMoreOf[Slice]` | Slice states |
 | `init[Slice](args)`, `refresh[Slice]()`, `setPageOf[Slice](page)`, `loadMoreOf[Slice]()` | Slice actions |
 | `set[Field]On[Model](value)` | Auto-setters for each model field |
+| `upload[Field]On[Model](fileList, idx?)` | Upload into a `File` field, scoped to the form that started it |
+| `[model]FormUploading` | Pending uploads per `File` field (`{}` when idle); submits save nothing until empty |
 
 **Rule**: Write custom store actions only for toast messages (`msg.loading`/`msg.success`) or multi-step workflows. State fields and CRUD actions are already auto-generated.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/cli",
-  "version": "3.1.0-rc.13",
+  "version": "3.1.0-rc.15",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -39,7 +39,7 @@
     "@earendil-works/pi-tui": "1.3.0",
     "@inquirer/prompts": "^8.7.3",
     "@tailwindcss/node": "^4.3.3",
-    "akanjs": "3.1.0-rc.13",
+    "akanjs": "3.1.0-rc.15",
     "chalk": "^6.0.1",
     "commander": "^15.0.0",
     "dayjs": "^1.11.23",