@jskit-ai/agent-docs 0.1.199 → 0.1.201

package/guide/agent/app-extras/assistant-conversation.md

@@ -249,7 +249,7 @@ The composable exposes the same `runtime` and `error` refs; it is unnecessary fo
 an application that only adds standard component slots.
 
 The composable's `presentation` option accepts a value, ref or getter. Supply transcript
-fields `assistantLabel`, `systemLabel`, `welcomeMessage`, `variant`, `visible`,
+fields `assistantLabel`, `systemLabel`, `welcomeMessage`, `variant`, `visible`, `retainWhenHidden`,
 `userMessageFormat` and `progressPreviewLimit`, and composer fields `ariaLabel`,
 `submitAriaLabel`, `submitLabel`, `placeholder` and `rows`. `layout: "compact"`
 keeps the existing compact composer. These change presentation through the
@@ -262,7 +262,9 @@ state for an exact actor, endpoint, surface, workspace and conversation. Release
 a retained handle with `release()`. Final view/reader release detaches browser
 observers; it does not stop server work. A lost receipt remains uncertain with
 **Check delivery** until inspection or canonical history proves acceptance.
-Reconnection reads state and does not resend the request.
+Reconnection reads state and does not resend the request. After an initial
+subscription failure or timeout, **Reload** retries that exact subscription on
+the connected socket with fresh authorization; it does not resend a message.
 
 Applications that create nonvisual tasks after setup can capture
 `useAssistantConversationFactory(commonOptions)` once during setup, then call
@@ -556,7 +558,7 @@ composer is present, and `stop` when `canStop` can become true.
 | `setDraft(text)` | Update the application draft synchronously. |
 | `submit({ configuration, attachments })` | Send or steer through the app's normal admission, attachment and delivery path. Use the delivery controller below for pending messages and failures; retain accepted-draft clearing and application admission. The element checks `canSend` before calling. |
 | `stop()` | Request cancellation through the backend owner. Report pending state, errors, and what actually stopped; the element checks stop availability. |
-| `loadMore({ complete })` | Prepend older turns, then call `complete({ changed })` after updating reactive state. Call it on failures too; this releases the scroll anchor. |
+| `loadMore({ complete })` | Prepend older turns, then call `complete({ changed })` synchronously after updating reactive state, before yielding to rendering. Call it on failures too; this releases the scroll anchor. Pending reader movement stays tracked if new replies change the transcript height before completion. |
 | `reload()` | Refresh authoritative history. |
 | `resend(id)`, `cancel(id)`, `edit(id)` | Optional overrides of the shared delivery actions. Keep the stable message identity when retrying. |
 | `openLink({ event, href, text })` | Optionally handle app-owned links and call `event.preventDefault()`. Otherwise a validated ordinary link keeps normal browser behavior. |
@@ -564,12 +566,49 @@ composer is present, and `stop` when `canStop` can become true.
 
 `scrollKey` changes when conversation ownership changes, resetting scroll and
 expansion state. `followLatestKey` requests following the newest message.
+`retainWhenHidden: true` keeps the original transcript scroll node while `visible`
+is false and suspends hidden scroll work. It captures a reader's visible turn
+before hiding and restores that turn's offset after reopening layout settles;
+readers following the latest message still follow new replies. An older-history
+load completed while hidden restores its original anchor after reopening. First
+open and a changed `scrollKey` still position the conversation at its latest
+message. Retained transcripts lay out their message rows without offscreen height
+estimates so later materialization cannot move the restored anchor; this opt-in
+uses more layout work for long histories. The default is false and retains the
+existing remove-and-follow behavior and offscreen layout optimization.
 Scrolling upward within 160 CSS pixels of the transcript's top requests older
 history through `loadMore`, including touch, wheel and keyboard scrolling.
 Only one request runs at a time, and prepending preserves the reading position.
 Initial positioning and conversation selection do not fetch older pages.
 `loadMoreError` pauses automatic loading; the older-messages button remains
 available for an explicit retry. Clear the error when retrying succeeds.
+A transcript `error` appears in a compact, content-sized warning above the loaded
+messages. It does not replace history, remount the message body, clear a draft or
+reset an older-history reader. A failure to receive updates does not establish
+that the assistant stopped. While updates are unavailable, the supplied binding
+hides its stale working hint without disabling the existing Stop action; a fresh
+update restores the hint. `errorReloadable: true` offers **Reload chat** only
+inside that warning when the permanent `reloadable` control is off; it emits the
+same `reload` action and respects `reloading`. Enable it only when the current
+actor may recover that conversation. The supplied runtime binding derives this
+from its existing access-denial state; a 401/403 still clears private history and
+drafts and offers no error-only Reload. Restore access or sign in through the
+application before reopening. A subscription transport failure says **Chat
+updates could not reconnect. Reload chat to try again.** and retains its original
+error as `cause`; provider errors keep their own wording.
+
+When `runtime.logger` is supplied, subscriptions emit structured
+`assistant.conversation.subscription` records containing `stage`, `previousStage`,
+`durationMs`, `elapsedMs`, and the server-generated `subscriptionEpoch`. The
+conversation identity is included only after opening and authorization succeed;
+raw client subscription IDs and rejected conversation inputs are not logged. Stages cover
+authentication, action admission, conversation opening, observer attachment,
+snapshot reading and acknowledgement. The acknowledgement stage includes
+`snapshotTurns` and `snapshotLimit` when available, without message content.
+`acknowledgement-sent` records server dispatch, not client receipt. Diagnose the
+measured slow stage before changing the existing ten-second acknowledgement
+deadline.
+
 `reloadable`, `reloading`, `welcomeMessage`, and `variant: "main" | "task"`
 control the corresponding transcript presentation. `userMessageFormat` is
 `"formatted"` by default; `"plain"` preserves literal user-authored text.
@@ -1407,7 +1446,12 @@ await conversation.select({
 ```
 
 Selecting a native engine used earlier restores its latest retained binding.
-Changing a model on the current engine retains that native conversation. Before
+Changing a model on the current engine retains that native conversation. OpenCode
+retains it only within the same `integrationId`: selecting a different integration
+reserves a fresh native binding while preserving the application conversation and
+history. Returning to OpenCode restores only a binding for that integration; an
+unselected account change still fails its identity guard. Selection never submits
+a prompt or replays a retained failed or uncertain request. Before
 the next request, JSKIT supplies missed messages, corrections and removed message
 identities as quoted history. Unchanged messages are not injected again. All
 corrections are included, even outside the recent-history window; if they exceed
@@ -1415,6 +1459,14 @@ corrections are included, even outside the recent-history window; if they exceed
 with a briefing. Nothing is silently dropped. The application remains responsible
 for authorizing edits to its transcript.
 
+An application whose established selection policy creates a fresh native
+conversation can pass `retireNative: true` to `select()`. This uses the same
+selection transaction and allocates a new binding even for a compatible model
+or effort change; it does not restore an earlier retained binding. Written
+history and predecessor receipts remain, and the next request receives the
+retained discussion through the existing history handoff. The operation does
+not submit a prompt. Omit this option for the native reuse policy above.
+
 Selection requires idle work and confirmed process cleanup. An uncertain receipt
 may remain with another selected engine, but the same message ID cannot be sent
 there again. Return to its original engine and use `inspectDelivery()` to resolve
@@ -2025,14 +2077,27 @@ driver uses this backend. Ordinary applications use the common conversation API
 with its supplied execution and credential defaults.
 
 Changed instructions use the existing thread-control restoration and verification
-before sending new work; they do not replace the shared process. Ordinary turns
-preserve the instruction binding. Native compaction remains the engine's job.
+before sending new work; they do not replace the shared process. A healthy active
+turn retains its installed instruction snapshot even if the source changes or is
+temporarily unavailable. The next idle admission rereads the latest instructions;
+if native work starts during that refresh, instruction-only recovery defers
+without explicitly interrupting it.
+Real account, environment, socket and provider recovery still runs normally.
+Native compaction remains the engine's job.
 JSKIT owns the local history adapter used for model-provider changes. It keeps
 native history intact and translates only outgoing requests. For qualified
 DeepSeek and GLM models, an OpenAI encrypted compaction is supplemented with the
 exact readable records from its saved native boundary. Recovery is bounded and
 fails explicitly for unsupported or ambiguous history, including native Undo or
 fork records. It never silently truncates, retries inference or rewrites a rollout.
+For outgoing OpenAI history, a nonempty historical function-call name outside
+`^[a-zA-Z0-9_-]+$` is quoted as assistant context with its exact call identity,
+name and arguments. Its paired result stays in its original position as labeled
+untrusted history, preserving supported text and images. Valid calls and unmatched
+results stay unchanged; ambiguous identities or unsupported paired content fail
+before the provider request. This does not rename tools, replay them or change the
+selected model. Native previous-model compaction and its fallback remain Codex's
+responsibility; this translation alone does not prove live compaction succeeds.
 
 For a supported external provider, supply the existing `connections` resolver and
 select `{ systemPrompt, integrationId, effort }`. For example, an integration
@@ -2214,6 +2279,19 @@ This advanced host operation has no HTTP, socket or client counterpart and accep
 no caller-supplied engine, native descriptor or host override. Ordinary standalone
 applications keep using `open()` and their existing storage contract.
 
+Existing detached run/stream facades can call
+`runtime.runNativeDetachedConversation({ id, context, input, options })` on that
+same runtime. Authorization uses `runDetachedConversation`. Its configured host
+returns `{ sessionId: id, engine, native, input, context, options }`, with the
+admitted context separate from the original engine options. Optional submitted
+`options` go only to that host; they never select a native owner or override the
+host. The driver uses the existing native execution and cleanup owners without
+opening Main, creating a retained handle or writing canonical message history.
+The application retains profile approval, write leases and original event/result
+codecs. Codex/OpenCode facade profile events remain unawaited;
+Claude acquires its entry before the profile event and awaits that event before
+starting work. This operation has no browser, HTTP or socket counterpart.
+
 The same advanced host can prepare native readiness before retaining a handle
 with `runtime.ensureNativeConversation({ id, context })`. Authorization uses
 operation `ensure`; only the configured host supplies the prepared
@@ -2436,7 +2514,9 @@ pauses/resumes an active goal only when still authorized, verifies the owned
 shell environment after reload and never retries the caller's operation.
 Changed instructions or an unknown installation update native configuration and
 add one explicit developer-context revision before new work. Acknowledged ordinary
-turns and socket reconnects do not repeat it. Compaction rebuilds context with the
+active turns keep their installed instructions rather than interrupting for a
+source-only change. Idle admission rereads the source, and socket reconnects with
+unchanged acknowledged instructions do not repeat the revision. Compaction rebuilds context with the
 current configuration; restricted consumers retain their own execution environment.
 The same provider owner selects and replaces cached providers, constructs native
 connections, acquires the shared runtime and retries an unconfirmed observation
@@ -2539,6 +2619,19 @@ accounting and the engine's own compaction remain native behavior.
 
 API-model apps can use `createAiConnectionClient` with an authorized AI integration resolver (see [Assistant](./assistant.md)), or `createAiClient` for existing environment-based configurations, and the tool-catalog helpers
 from `@jskit-ai/assistant-core/server`, or the complete assistant runtime.
+`createAiConnectionClient` preserves immediate rejection for a provider error,
+cancellation or invalid tool call. It does not wait for transport EOF to report
+that failure. Later text, tool calls, completion frames or transport errors cannot
+replace the reported failure or become another yielded chunk. The original signal
+reason remains the cancellation error. This does not retry the request or execute
+later tool calls.
+The common API conversation enables `reportUnavailableToolCalls` only for its
+application catalogue. A well-formed object call rejected specifically as an
+unavailable tool reaches that existing catalogue, which records a no-effect
+refusal and supplies it to the same bounded model/tool loop. This grants no tool
+access. Provider-executed calls, malformed or non-object arguments and every
+other validation error remain rejected. Direct SDK clients retain strict
+validation by default.
 Ordinary native conversations use `createConversationRuntime` and the supplied
 server/client integration described above. The native facilities below support
 hosts that already own managed execution, credential homes, authorized native
@@ -2584,6 +2677,10 @@ completion and the interruption barrier for steering. Normalized owner events
 let the host persist admissions and publish application state; receiver
 completion alone does not prove process exit. `claudeNativeMessageId()`
 retains the same stable native message IDs used by the Vibe64 adapter.
+An exact native acknowledgement ends its ACK deadline before the admission
+writer runs; a slow write remains awaited, and a rejected write rejects admission.
+A missing acknowledgement remains uncertain. Native failure-result text stays
+in the turn's error rather than becoming an assistant answer.
 The turn owner preserves the production receiver's block lifecycle: deltas are
 temporary, block-stop removes them, and completed snapshots use their native
 UUIDs. It does not group distinct history snapshots into a synthetic reply.
@@ -2780,6 +2877,19 @@ Set transport limits appropriate to the host; the default payload limit is
 unbounded. A request abort retires the local request; interrupt a running native
 turn with `turn/interrupt` when cancellation must stop provider work.
 
+The original public import contracts remain available alongside these host and
+testing surfaces. `/server/codex-client` exports `CodexAppServerJsonRpcClient`
+and `socketPathFromCodexAppServerEndpoint`; `/server/codex-events` retains its
+original event classification, text and notification helpers; `/server/codex-turn`
+retains `createCodexAppServerDetachedTurnWatcher` and the original turn-status
+predicates. `/server/opencode-client` retains `createOpenCodeServerClient`,
+`readBoundedResponse`, `OPENCODE_RESPONSE_LIMIT_BYTES` and
+`openCodeAssistantMessageText`. These exports forward to the same native owners;
+using a low-level client does not supply application authorization, account
+isolation or native cancellation. `/client/conversation-submit` retains
+`createAssistantTextSubmission`, also exported by `/client/conversation`.
+The newer host exports remain available.
+
 Managed Codex hosts use `createCodexAppServerRunOwner` from
 `/server/codex-turn`. It constructs the native notification queue from the
 supplied request-context and logging facilities and its own shutdown fence.
@@ -2856,6 +2966,13 @@ The provider-selection facet restores Helper ownership before model discovery or
 account description, retaining supplied-provider reuse, lifecycle gating and the
 original per-connection catalog cache. Authorized scope/account preparation,
 deadlines and result policy remain with the host.
+Provider lifecycle work retains its owner-local FIFO and shutdown task tracking.
+Its shared critical sections serialize only the same native runtime directory;
+a held catalogue in a different owner and runtime does not delay cached Stop or
+provider creation. Work in the same owner still follows its FIFO across runtime
+directories. Catalogue preparation remains tracked before its directory is known.
+Rejected work leaves both queues usable, and a settled runtime tail cannot remove
+newer queued work. Peer inventory, exit proof and recovery barriers are unchanged.
 Legacy detached host operations use that same owner's `acquireDetachedThread`,
 `detachedThreadId` and `dispatchDetachedTurn`. The ID projection accepts the
 original native response shapes and requested-thread fallback after either

package/guide/agent/app-extras/assistant-voice.md

@@ -231,8 +231,13 @@ target interrupts it.
 The speaker button changes the requested preference. Its optional
 `binding.onReadAloudChange(value)` callback runs only for that explicit change,
 never for preference hydration, microphone actions or navigation. The application
-owns storing it for the correct authenticated user. `defaults.readAloud` initializes
-a new session; it is not a second preference store. Sound on applies to future
+owns storing it for the correct authenticated user. A live optional
+`binding.readAloudChangePending: true` fences the next explicit preference change
+before the local toggle. The session exposes that computed flag; controls disable
+only the speaker choice (or an explicit `speakerDisabled` prop), leaving
+**Enable sound**, microphone capture and typing available. `defaults.readAloud` initializes
+a new session and hydrates a live boolean preference without emitting the callback;
+it is not a second preference store. Sound on applies to future
 outputs and does not replay history. If browser playback is blocked, the speaker
 choice stays on and **Enable sound** retries unlocking it. Microphone permission
 and capture continue independently, including while sound unlock is pending.
@@ -440,3 +445,47 @@ input; once that earlier admission settles, the existing capture owner finalizes
 and sends the retained utterance exactly once. Resuming before admission settles
 keeps that recording open. Cancellation retires the requested finish; genuinely
 unknown delivery remains unresolved until the person uses existing recovery.
+
+### Optional activity narration
+
+A host can supply a live `binding.narration` object with `turns`, `loading`,
+`working`, `eligible`, `vocalizeThinking`, `vocalizeInterimTurns` and
+`thinkingSounds`. Without it, the existing canonical-answer behavior is unchanged.
+The host owns these preferences and eligibility; JSKIT does not persist them or
+change the shared default for read aloud.
+
+The retained narration tracker observes thinking/commentary once, retires old or
+disabled content, and settles an unchanged trailing phrase after 700ms while work
+continues. The tracker retains the full activity history, so later short deltas can continue
+beyond 4000 cumulative characters. The original splitter caps each newly observed
+delta at 4000 characters before producing activity chunks of at most 300
+characters; a larger single burst can lose its remaining tail. With thinking sounds
+selected, an idle working conversation may say “Hmm...” after 20 seconds; it does
+not overlap existing audio.
+
+Optional activity joins the original speech queue. Canonical answers take priority
+and keep their existing output IDs and playback callbacks. Activity and thinking
+sounds have no canonical output identity and emit no `onPlayback` receipt; they
+cannot satisfy lesson audio completion. Optional speech yields to microphone
+startup, capture and transcription. Canonical answers retain full duplex playback.
+Hiding the avatar is presentation only and does not disable either facility.
+
+Stop speaking, speaker-off hydration, target retirement, loading, hidden pages and
+close retire the applicable optional speech and timers. Returning or enabling a
+flag does not replay old activity. An explicit new request or speaker choice can
+lift the existing Stop-speaking silence policy; preference hydration never writes
+back through `onReadAloudChange`.
+
+For a binding that opts into narration, hiding the browser tab consumes newly
+observed canonical outputs without speaking or replaying them on return. A
+streamed output first finalized while hidden is interrupted with its existing
+output ID, never reported as completed. Completed answers already queued while
+visible may finish playing when no capture is active.
+
+Hiding that tab cancels microphone startup and unfinished capture. These current
+words are discarded under the original Main capture policy; an earlier pending,
+admitted or unresolved delivery retains its text, ID and destination. Returning
+does not restart capture; use Talk explicitly. This document-hidden boundary is
+independent of avatar collapse or chat minimization, which preserve the session
+and ordinary full duplex. Bindings without narration retain their existing tab
+behavior; page suspension still uses the original transport recovery.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/agent-docs",
-  "version": "0.1.199",
+  "version": "0.1.201",
   "description": "Distributed JSKIT agent references, prompts, guides, and generated reference maps.",
   "type": "module",
   "files": [

package/patterns/feature-package/example/booking-engine/package.json

@@ -5,7 +5,7 @@
   "private": true,
   "type": "module",
   "dependencies": {
-    "@jskit-ai/kernel": "0.1.227",
+    "@jskit-ai/kernel": "0.1.229",
     "json-rest-schema": "^1.0.17"
   },
   "exports": {

package/patterns/minimal-foundation/example/package.json

@@ -34,7 +34,7 @@
   "dependencies": {
     "@local/main": "0.1.0",
     "@fastify/static": "^10.1.3",
-    "@jskit-ai/kernel": "0.1.227",
+    "@jskit-ai/kernel": "0.1.229",
     "@tanstack/vue-query": "^5.101.0",
     "fastify": "^5.8.5",
     "json-rest-schema": "^1.0.17",
@@ -42,13 +42,13 @@
     "vue": "^3.5.43",
     "vue-router": "^5.3.1",
     "vuetify": "^4.1.2",
-    "@jskit-ai/http-runtime": "0.1.225",
+    "@jskit-ai/http-runtime": "0.1.227",
     "@fastify/fast-json-stringify-compiler": "^5.1.0",
     "@vue/devtools-api": "^8.2.1"
   },
   "devDependencies": {
-    "@jskit-ai/config-eslint": "0.1.224",
-    "@jskit-ai/jskit-catalog": "0.1.252",
+    "@jskit-ai/config-eslint": "0.1.226",
+    "@jskit-ai/jskit-catalog": "0.1.254",
     "@playwright/test": "1.61.1",
     "@vitejs/plugin-vue": "^6.0.7",
     "eslint": "^10.8.0",

package/patterns/shell-foundation/example/package.json

@@ -34,7 +34,7 @@
   "dependencies": {
     "@local/main": "0.1.0",
     "@fastify/static": "^10.1.3",
-    "@jskit-ai/kernel": "0.1.227",
+    "@jskit-ai/kernel": "0.1.229",
     "@tanstack/vue-query": "^5.101.0",
     "fastify": "^5.8.5",
     "json-rest-schema": "^1.0.17",
@@ -42,15 +42,15 @@
     "vue": "^3.5.43",
     "vue-router": "^5.3.1",
     "vuetify": "^4.1.2",
-    "@jskit-ai/http-runtime": "0.1.225",
+    "@jskit-ai/http-runtime": "0.1.227",
     "@mdi/js": "^7.4.47",
-    "@jskit-ai/shell-web": "0.1.231",
+    "@jskit-ai/shell-web": "0.1.233",
     "@fastify/fast-json-stringify-compiler": "^5.1.0",
     "@vue/devtools-api": "^8.2.1"
   },
   "devDependencies": {
-    "@jskit-ai/config-eslint": "0.1.224",
-    "@jskit-ai/jskit-catalog": "0.1.252",
+    "@jskit-ai/config-eslint": "0.1.226",
+    "@jskit-ai/jskit-catalog": "0.1.254",
     "@playwright/test": "1.61.1",
     "@vitejs/plugin-vue": "^6.0.7",
     "eslint": "^10.8.0",

package/patterns/shell-foundation/example/packages/main/package.json

@@ -9,7 +9,7 @@
   },
   "description": "App-local runtime composition and lightweight glue.",
   "dependencies": {
-    "@jskit-ai/kernel": "0.1.227"
+    "@jskit-ai/kernel": "0.1.229"
   },
   "jskit": {
     "kind": "runtime",