@akanjs/cli 3.0.0-beta.4 → 3.0.0-beta.6

package/.build-stamp

@@ -1 +1 @@
-b129370a860bac06e3d96a976bd13d89caf64cc7a00d87d4adde5461f7179cf5
+fdc8c6e78c40accb0f6e5b895d646ae64cea4b64c0f22eb726690c373e78c22a

package/guidelines/agentRule/agentRule.instruction.md

@@ -48,7 +48,9 @@ apps and libs never import it directly (`no-import-external-library`) — everyt
   slots: `AgentLauncher`, `AgentBubble`, `AgentComposer`, `AgentApproval`,
   `AgentQuestion`, `AgentQueued`, `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
+  one it is replacing. The attachment row is exported on its own as `AgentAttachments`, because a replaced
+  `AgentBubble` that redraws it by hand forks the rule for which carrier is shown how — and then keeps whatever
+  that rule was on the day it was copied. `AgentCode` is where a highlighter binds — the fence's language reaches it — and a
   replacement for `AgentBubble` carries its own `memo`, since the transcript re-renders on every delta. Only then
   `AgentChat`, which replaces the panel whole: it also replaces the slash commands, the compaction notice and the
   approval gate, so reach for it when the *layout* differs, not when the look does.
@@ -110,8 +112,9 @@ apps and libs never import it directly (`no-import-external-library`) — everyt
   arrives as an image. `accepts.document` is one boolean over every non-image type, so an adaptor whose API has a
   block for only some of them — Anthropic's `document` is PDF and nothing else — names the rest in the text rather
   than dropping them, which is the wire's own rule applied at the one layer that knows which blocks exist. 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.
+  attachment's name, type, address and `ref` and drops only 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, while an id is the handle a restored conversation has left to find the file with.
   **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
@@ -127,11 +130,13 @@ apps and libs never import it directly (`no-import-external-library`) — everyt
   Nothing downstream trusts the result: an attachment whose `mimeType` is not a string is noted like any other
   unreadable one, and its chip renders its name with no preview, because the host wrote the object and the declared
   type is a claim rather than a check. A field that arrives wrong costs that attachment, never the turn.
-- **A `url` carrier is an address the *provider* fetches, so a reader that uploads has to know its storage is
-  reachable.** This is the one way an attachment fails with nobody reporting it: the default storage backend
-  serves a path only the app can resolve, the adaptor hands it over as written, and the model answers about a
-  picture it never saw. Answer `data` when the provider cannot reach the URL — the choice is the reader's,
-  because the reader is what chose to upload.
+- **A `url` carrier is an address the *provider* fetches, and bytes beside it win.** A reader that uploads answers
+  `{ url }` when its storage is publicly reachable, and `{ data }` — or both — when it is not: an attachment
+  carrying both is read from its bytes and displayed from its address, so the chip draws a thumbnail and the model
+  still gets the picture. That precedence exists because the other order fails the one way nothing reports: the
+  default storage backend serves a path only the app can resolve, the adaptor would hand it over as written, and
+  the model answers about a picture it never saw. Send a provider-reachable URL **alone** — paired with bytes it
+  costs the provider hop whatever the bytes weigh, for a fetch the provider would have done itself.
 - **An image type the provider has no block for is refused at the adaptor, not upstream.** `accepts.image` is one
   boolean, so `AgentService.readable` passes every `image/*` through, and the built-in composer reader base64s
   every `image/*` as well — an `AttachReader` answering `null` means "not mine" and falls through to it, so an app

package/guidelines/conventions/conventions.instruction.md

@@ -464,6 +464,24 @@ Full contract — credential handshake, room revalidation, socket cleanup scopin
 - **A cleanup registered with `ws.on("disconnect" | "unsubscribe", fn)` is scoped to the call that registered it**
   — a room for a `pubsub` subscribe, the socket for a `message` handler. Cleanup that must happen either way
   registers for both.
+- **A call's deadline is the endpoint's `{ timeout: <ms> }`, and there is nowhere else to put one.** It bounds
+  both ends: the `Timeout` middleware — registered by default, and standing aside for every endpoint that
+  declares none — rejects the call with `base.error.gatewayTimeout`, and the same value is serialized to the
+  client as that call's request budget. Declared nowhere, a call takes the client's own default of **30
+  seconds**, so an endpoint whose real work runs longer (provisioning, a firmware flow, an external
+  orchestration) has to declare one or it dies mid-flight with a transport error that does not say whether the
+  server ever received it. A caller overrides it per call with `fetch.x(…, { timeout })` — `false` waits as long
+  as the runtime will — and an app moves its own default with `fetch.instance.setTimeout(ms)`. An upload is
+  never bounded. **Losing the race does not cancel the work**: the handler runs to completion with nobody
+  holding its result, so a deadline is an answer to the caller, not an undo.
+- **A cached answer is the endpoint's `{ cache: <ms> }`, and only a `query` taking no internal argument may have
+  one.** The `Cache` middleware is registered by default and stands aside for every endpoint that declares
+  nothing. Internal arguments are how a call learns who is asking (`.with(Self)`), so an endpoint that has them
+  answers per caller and one shared entry would be one caller's answer handed to the next — that endpoint and
+  every `mutation` are named in the log and left uncached. Guards run on every hit; what is cached is the
+  handler's result, so `resolveReturn` still masks fields and resolves relations per call; a cache backend that
+  is down is warned about and the call runs uncached. The default chain is `Logging → Timeout → Cache → handler`,
+  and there is no `Retry` middleware.
 
 ### Authorization Defaults
 

package/guidelines/transportRule/transportRule.instruction.md

@@ -28,6 +28,55 @@ mutation is mounted under. `conventions` carries the invariants — this is the
   neither again, and cleanup that must happen either way registers for both. From a `message` handler it belongs to
   the socket and runs at close. A handler that throws is logged and never blocks the rest of the teardown.
 
+## Request Deadlines
+
+- **`{ timeout: <ms> }` in an endpoint's signal option is the whole configuration surface**, and it reaches both
+  ends of the call. Server side, the `Timeout` middleware races the handler against it and answers
+  `base.error.gatewayTimeout` (504) once it is spent. Client side, `FetchSerializer` ships the value on the
+  serialized endpoint and `fetch.<endpoint>()` uses it as that request's `AbortSignal.timeout` budget, so the
+  browser does not abandon a call the server is still allowed to be working on.
+- **The middleware is registered by default and has no default of its own.** An endpoint that declares no
+  `timeout` is passed straight through — a default here would put a deadline on every endpoint in the app that
+  nobody asked for, which is why the middleware used to be opt-in and, being opt-in, made the declared value
+  dead. It clears its timer in a `finally`: the race's loser is a pending timer per call otherwise, and with a
+  five-minute budget that is a five-minute hold on the event loop for a call that answered in a millisecond.
+- **Without a declaration the client's own default applies — 30 seconds** (`DEFAULT_TIMEOUT_MS`,
+  `fetch/client/httpClient.ts`), and the server imposes nothing. Nothing else bounds a request: `Bun.serve` runs
+  with `idleTimeout: 0`, so a long call is only ever ended by one of these two.
+- **Precedence is caller, then endpoint, then client default.** `fetch.x(…, { timeout: 5_000 })` overrides what
+  the endpoint declared; `{ timeout: false }` waits as long as the runtime will. An app moves its own default
+  with `fetch.instance.setTimeout(ms)` — `lib/useClient.ts` is generated, so the `timeout` option on
+  `FetchClient.build` belongs to the template that writes it, not to app code.
+- **A file upload is never bounded**, on any of those paths: a large body on a slow uplink is a request that is
+  working, and the request body is the only thing the client can tell that from.
+- **The deadline answers the caller; it does not undo the call.** `Promise.race` cannot cancel `next()`, so a
+  handler that timed out keeps running and keeps writing. Reach for a `timeout` to bound what a *caller* waits
+  for, not to bound an effect — an operation that must not half-happen needs its own idempotency or compensation.
+- The failure is the same `base.error.gatewayTimeout` key whichever side gave up, so the user reads one sentence
+  in their own language either way. What differs is the status code — 504 from the server's middleware, 408 from
+  the client's own abort — and nothing downstream branches on that.
+
+## Cached Answers
+
+- **`{ cache: <ms> }` in an endpoint's signal option is the whole cache surface.** The `Cache` middleware is
+  registered by default and stands aside unless an endpoint declares one — it used to be opt-in and to ignore the
+  declared value for a hard-coded 60 seconds, which is the same shape the `timeout` bug had.
+- **Only a `query` that takes no internal argument may carry one.** The handler's inputs are its declared
+  arguments plus its internal ones, so an endpoint with none of the latter answers the same thing to everyone who
+  may read it — which is the only answer a shared entry can hold. An endpoint that takes `.with(Self)` answers
+  per caller, and one entry would be one caller's answer handed to the next; that endpoint and every `mutation`
+  are named once in the log and left uncached rather than silently ignored.
+- **The guards run on every hit.** A cache hit skips `next()`, and `next()` is what runs them, so the middleware
+  calls `context.checkGuards()` itself before handing the entry over. Shared is not public.
+- **The entry is the handler's result, not the response.** The middleware wraps execution, so `resolveReturn`
+  still runs per call on the cached value — field masking, `hidden`/`secret` stripping and relation resolution are
+  never cached, and a relation still costs its own load. The cache saves the handler, not the serialization.
+- **A cache backend that is down does not take the endpoint down.** A failed read is warned and the call runs
+  uncached; a failed write is warned and dropped.
+- The default middleware chain is `Logging → Timeout → Cache → handler`: a hung cache backend is bounded by the
+  same deadline as the handler it stands in for. **`Retry` was removed** — an automatic re-run of an endpoint
+  whose failure it cannot classify replays whatever the first attempt already did.
+
 ## Binary Pubsub
 
 - **`pubsub(Binary)` sends its payload in a websocket binary frame**, skipping the JSON `{ type: "pub" }`

package/package.json

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