@jskit-ai/agent-docs 0.1.198 → 0.1.200

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
@@ -355,6 +357,22 @@ different submission replaces that reference; it never selects an older matching
 failure from history. Uncertain delivery still requires **Check delivery**.
 Voice sends keep their own authored capture and do not consume the typed draft.
 
+`conversation_not_steerable` is a definite pre-admission rejection: its original
+request remains failed, with the same message ID and captured steering intent.
+It does not become uncertain or silently restart as new work. Hosts should use
+this code only when the original turn is absent or finished before dispatch.
+Transport and provider failures without that proof remain uncertain and require
+receipt inspection; an HTTP 409 alone is not proof of rejection.
+
+When `draftStorage` restores a page, known failed deliveries remain failed and
+accepted receipts remain accepted. Saved uncertain, pending or unrecognised
+delivery states stay uncertain with the exact original ID, payload and draft;
+closing a page during HTTP is not proof of rejection. Only the transient
+inspection flag is reset so **Check delivery** is reachable again. A matching
+canonical row marked `receipt: false` cannot settle delivery. Unknown inspection
+never retries; an actual accepted receipt is required to acknowledge the request.
+The existing storage shape is unchanged and reads perform no historical repair.
+
 With `queueWhileSending: false`, the composer is disabled during admission and
 overlapping typed or retained voice sends return `false` before calling the
 supplied API. A runtime that supports sending while working still permits the
@@ -363,6 +381,20 @@ of the initial retained conversation composition, so use consistent options for
 mirrored readers of the same identity. The default is `clearDraftOn: "dispatch"`
 and the existing queuing behavior for a runtime that advertises steering.
 
+Applications may opt into `deferWhileWorking: true` with
+`queueWhileSending: true` for a conversation that cannot steer its active turn.
+Typed and retained voice submissions become pending in the original serial
+queue with their exact message ID, text, attachments and captured data. The
+existing subscription must report ready before each ordinary request reaches
+the API; normal server permissions still apply at dispatch. Show **Send** and
+the existing pending status, not **Steer**, when the runtime cannot steer.
+Native steering and explicit retries keep their captured intent. Stop aborts
+these local pre-dispatch followers before stopping the original turn; actor
+retirement and lost access cannot dispatch them later. This option defaults to
+false and belongs to the initial retained conversation composition. It adds no
+server queue or persisted queue recovery; genuine uncertainty still blocks new
+submissions and requires receipt inspection.
+
 Set `draftWhileLoading: true` when people should be able to type before the
 application resolves its conversation ID or while the first read is unavailable.
 This keeps one local input scoped to the real actor, endpoint, surface and
@@ -526,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. |
@@ -534,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.
@@ -547,13 +616,40 @@ control the corresponding transcript presentation. `userMessageFormat` is
 For live speech that has not been admitted, supply
 `adapter.conversation.previewMessage = { messageId, text }` (the original
 voice capture's `id` is also accepted). The element displays one pending user
-message after merging canonical and delivery turns. A matching canonical or
+message after merging canonical and delivery turns. A matching admitted canonical or
 delivery message ID suppresses that preview, so an admitted utterance appears
-once. The application owns updating or clearing its current capture. Preview
+once. An exact unadmitted canonical user (`receipt: false`) or known failed local
+delivery may retain the same bubble as an editable preview; its real status and
+error remain unchanged until the host performs an explicit action. The application owns updating or clearing its current capture. Preview
 text never enters saved history, the retained runtime's turns or receipt
 reconciliation; it cannot acknowledge a pending or uncertain send. Keep it out
 of `adapter.conversation.turns`.
 
+An optional `previewMessage.actions` supplies `discard(messageId)` and
+`edit(messageId)` with explicit `canDiscard` and `canEdit` booleans. The element
+shows X and pencil actions only on its unsent preview bubble; accepted messages
+never receive them. Add `editing`, `update(messageId, text)`, `send(messageId)`,
+`canSend` and `sending` to reuse the original review textarea inside that same
+bubble and its existing action row for Send. An empty editor remains visible.
+The host owns identity, admission and current-target guards; the typed draft need
+not change. For a known failed voice delivery, explicit Edit may cancel only that
+exact failed local entry through the original delivery owner before authoring a
+fresh request. Plain Retry preserves its original text and intent. The preview
+row replaces the generic failed-action row without concealing the real error.
+`user-message-actions` receives `{ message, turn }` inside the existing user
+bubble; the assistant's `message-actions` slot remains separate.
+
+A host with both an existing pending utterance and a newer live capture can
+project `adapter.conversation.previewMessages` as a read-only, identity-deduplicated
+list of those existing descriptors. The singular `previewMessage` contract stays
+available; a supplied list owns the displayed previews. Each row binds only its
+matching descriptor, so the retained failed bubble keeps its actual error and
+recovery controls while newer words stay visible. This list never queues,
+submits or stores transcripts. The host disables the newer capture's Edit while
+its existing pending editor is occupied, preserving its independent Discard.
+Existing runtime presentation options that forward only `previewMessage` do not
+implicitly forward this list; supply it on the host's final adapter conversation.
+
 ### Message delivery
 
 Use `createAssistantMessageDelivery` from `/client/conversation` (or the
@@ -765,8 +861,10 @@ are `focus()`, `preserveHeightForNextModelValue()` and `queueResizeTextarea()`;
 
 ### Optional avatar
 
-Supply the `avatar` slot to add artwork above the existing transcript. With no
-slot, the text-only layout has no avatar region or size control and requires no
+Supply the `avatar` slot to add artwork fixed at the chat's upper right. It stays
+outside the transcript's scroll container; chat text scrolls behind the artwork
+and controls. It creates no side gutter or text wrapping. With no
+slot, the text-only layout has no avatar region or visibility control and requires no
 voice package or speech service. The application supplies artwork and any
 animation; the element does not acquire audio or another conversation.
 
@@ -777,12 +875,30 @@ animation; the element does not acquire audio or another conversation.
 ```
 
 `avatarSize` is a controlled preference: `hidden`, `compact`, `standard`, or
-`large`, requesting 0, 64, 112, or 176 CSS pixels of artwork. Its default is
-`compact`. The Avatar size button opens the four-preset menu and emits
-`update:avatarSize`; keep that value in the application's existing preference
-owner if it should be remembered. The button uses the default composer toolbar.
-A custom or transcript-only composer uses a separate row above the transcript.
-Hidden leaves the button available so the person can show the avatar again.
+`large`, requesting 0, 96, 112, or 176 CSS pixels of artwork. Its default is
+`compact`. The anonymous avatar icon at the chat's upper right shows the avatar;
+the expanded round minus icon at the end of the avatar controls row hides it
+(accessible label **Minimise avatar**). The collapsed **Show avatar** icon remains
+at the chat's upper right and remains clickable above the transcript's reload
+control. Both controls emit
+`update:avatarSize`; keep that
+value in the application's existing preference owner if it should be remembered.
+Show restores the last visible size, or Compact if none has been selected.
+There is no size menu. Hosts can still supply any supported controlled preset.
+The overlay is transparent, so transcript text shows behind the supplied artwork
+rather than an opaque panel.
+Changing visibility does not change the input or composer button layout.
+
+The optional `avatar-tools` slot receives the same `{ size, height }` scope and
+places application-supplied controls below the artwork, outside the composer,
+immediately before the element's round minimise control in the same compact row.
+Its content stays mounted while Hidden conceals the presentation with `v-show`,
+so a local controls target can retain its identity. Keep required review,
+recovery and active-capture controls visible outside the hidden presentation.
+The always-visible `avatar-control` slot receives `{ size, height }` beside
+Show/Hide. An application can use it for a collapsed active-mic
+indicator or control without placing voice state in the conversation element.
+The element supplies no audio session or control actions.
 
 The effective artwork height uses the conversation container's actual remaining
 space after its composer, feedback, support and other controls, leaving a target
@@ -793,8 +909,8 @@ a preference change; enlarging the container restores the requested size.
 The slot receives `{ size, height }`, where `size` is the requested preset and
 `height` is the effective artwork height. Size artwork to fit that region.
 
-`AssistantConversationClientElement` accepts the same slot and
-`v-model:avatar-size`. Its slot also receives the existing retained `runtime`.
+`AssistantConversationClientElement` forwards all three avatar slots and
+`v-model:avatar-size`. Its slots also receive the existing retained `runtime`.
 Changing the preference does not acquire a new runtime, change the transcript,
 clear the draft, or deliberately move focus. The transcript retains its normal
 scroll-following behavior; application visibility and focus policies remain
@@ -1330,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
@@ -1338,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
@@ -1948,8 +2077,13 @@ 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
@@ -2137,6 +2271,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
@@ -2359,7 +2506,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
@@ -2462,6 +2611,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
@@ -2507,6 +2669,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.
@@ -2703,6 +2869,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.
@@ -2779,6 +2958,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

@@ -116,7 +116,7 @@ navigation action without replacing the retained voice session.
 
 `VoiceConversation` accepts `adapter`, `session`, `disabled`, and controlled
 `avatarSize`, and emits `update:avatarSize`. `VoiceConversationHost` forwards that
-preference and event. Supply `v-model:avatar-size` from the application's existing
+preference and event; its default is `hidden`. Supply `v-model:avatar-size` from the application's existing
 preference owner. Its avatar slot receives the original visual state plus the
 core slot's requested `size` and effective `height`; temporary clamping preserves
 the preference.
@@ -125,26 +125,81 @@ the preference.
 Set `binding.showAvatar: false` when using `VoiceConversationHost` to omit the
 portrait entirely. Caption-only views then give that space to the existing
 captions and controls; adapter-backed views omit the core avatar slot and its
-sizing control. This presentation choice does not change the retained session,
+visibility control. This presentation choice does not change the retained session,
 typed draft, capture, review or playback operations.
 
 `VoiceConversationControls` reuses the session's original Talk/Pause gesture,
-speaker, Stop speaking, error and recording review operations. `compact` places
-48px voice actions beside the ordinary composer tools and bounds the independent
-review textarea. Captured words stay explicitly Not sent until normal admission;
-review edits do not replace the typed draft. While capture, transcription or review
-needs resolving, the canonical typed composer stays editable and its Send is
-disabled. Finish the recording, then send or discard its reviewed words before
-sending the typed draft. This presentation guard keeps the original adapter's
+speaker, Stop speaking, error and recording review operations. `compact` uses
+48px voice actions. Optional `iconOnly`, default `false`, replaces the Talk label
+with its microphone icon while retaining the full state label in `aria-label`,
+the gesture hint and the original pointer/keyboard handlers. The microphone
+tooltip reads “click or long press to talk”.
+Stop speaking keeps a 48px target. Icon-only Talk, speaker and the compact
+settings cog use 32px visible circles inside transparent targets 40px wide and
+44px tall, with no gap between targets and 8px between visible circles. The
+expanded avatar's minimise button uses the same compact target; collapsed Show
+avatar keeps its 44px square target. All voice controls remain visible while idle. Stop speaking sits beside that pair without changing its position.
+The adapter-backed voice view places these icons below the fixed upper-right
+avatar, outside the composer. Hidden preserves the tools target. Its default
+collapsed presentation shows passive Listening and Speaking icons only while
+those states are active; Show avatar restores the ordinary controls. An idle or
+muted microphone has no Listening indicator. Icon-only presentation omits the
+routine Listening footer; errors, provisional words, review and sound recovery
+remain visible.
+Its `avatar-control` slot forwards the core scope for an always-visible control
+supplied by the application. Hiding is presentation only; it does not pause
+capture, cancel speech or end the session. Compact review keeps its
+independent editable textarea beside the 48px Discard and Send actions, with up
+to two rows and scrolling. Errors keep their full text in small body typography
+to preserve readable history in short containers. Compact Talk keeps one bounded track across Talk, Pause,
+Connecting and held-recording labels. In the labelled compact layout, space for Stop speaking and the normal
+status line remains allocated while idle; an unavailable Stop speaking action
+is absent from keyboard and accessibility navigation. These reservations keep
+capture and playback state changes from moving Talk. Captured words stay
+explicitly Not sent until normal admission;
+review edits do not replace the typed draft. An open hands-free microphone
+does not block typed steering. `session.composerBlocked` gates Send during startup and non-live or
+non-hands-free capture, admission or review. Live hands-free keeps typed Send
+available while spoken requests await admission;
+`session.hasUnsentSpeech` independently protects target switching. The latest
+recognized words remain observable through `binding.onTranscript`, including
+while an earlier request awaits admission. Pause remains usable during that wait
+and does not discard either recording or stop playback. This presentation guard keeps the original adapter's
 actions, attachments and questions. Send retries keep the recording's
 UUID and captured destination; Discard uses the original cleanup operation.
 
+`onTranscript(transcript, { canTake })` preserves the original `{ id, text }` or
+null projection and supplies eligibility for unsent-preview controls.
+`session.takeTranscript(messageId, transfer?)` refuses wrong, admitted,
+committing or sending messages. An optional synchronous `transfer(text)` must
+recheck the host's empty typed draft, set it through its original setter, and
+return true; false leaves speech untouched. Taking an active partial uses the
+original capture cancellation and guarded hands-free restart, preserving the
+session and playback. Taking a pending review clears only that review. Hosts
+also gate these controls while their canonical delivery has uncertain admission.
+
 For custom compositions, its optional `toolsTarget` is a DOM element belonging
-to the local composer-tools slot. One controls instance moves its buttons there
-with Vue Teleport, while review and errors remain in composer-feedback. Keep
-that target mounted with the composer; there is no global portal or second
+to the local host, such as an `avatar-tools` target. One controls instance moves
+its buttons there with Vue Teleport, while review and errors stay in the host's
+visible feedback region. Optional `feedbackTarget` moves those existing
+feedback controls into a local composer element without creating another
+controller or replacing its typed draft. Keep these targets mounted, including while the avatar
+is hidden; there is no global portal or second
 gesture/session owner. With no target, the controls render together in place.
 
+`VoiceConversationHost` accepts `presentation: 'dialog' | 'inline'`, defaulting
+to `dialog`. Inline replaces the modal wrapper with an in-flow section using
+the same settings, error, target-switch recovery and conversation slot. It omits
+the separate window title, settings and close-button header. Its settings control
+sits with the avatar tools when using the built-in conversation. It has
+no scrim, activator, focus trap, floating reopen button or modal sizing. Its body
+remains mounted for the retained session even when the controller is minimized.
+The application chooses inline only while its existing conversation host is
+present and chooses dialog for fallback; changing presentation does not end or
+replace the controller/session. The `conversation` slot still receives
+`{ binding, session, disabled }`, and the existing `settings` slot receives
+`{ voice }` in either presentation.
+
 The host's optional `conversation` slot receives `{ binding, session, disabled }`
 and replaces its primary body. Settings, target-switch guards, minimizing,
 reopening and controller lifetime stay with the same host. An application can
@@ -176,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.
@@ -193,7 +253,11 @@ Bindings may supply `defaults.mode` (`push-to-talk` or `hands-free`),
 `reviewBeforeSend`. The Talk/Pause microphone icon and speaker toggle show their states. The
 Voice settings cog loads the service's installed voices without recording.
 Pause finalizes the current utterance before muting, including buffered audio,
-and applies the recording's review preference. Resume starts a fresh recording.
+and applies the recording's review preference. If an earlier request is pending,
+Pause finishes the newer recording after that request settles. Resume keeps an
+unfinished recording open or starts a fresh recording after it ends. Talk and
+hold remain available during pending delivery, while transcribing and committing
+retain their original guards.
 The review panel stays hidden during automatic admission; failed admission keeps
 the words and message identity available for review and retry.
 The retained-adapter view scrolls the shared full history while its composer and
@@ -363,3 +427,65 @@ through an application-authorized route; credentials stay on the server. The
 result contains `voices` (IDs, labels and optional languages) and `defaultVoice`,
 matching the WebSocket greeting. Listing voices does not synthesize or load
 additional voice models.
+
+`VoiceConversationSettings` from `/client` extracts that same menu for hosts
+which supply their own conversation body. Pass the existing `voice` object and
+use its default slot for application-owned avatar and voice preferences. The
+slot receives `{ voice }`; saved identity, scope, permissions and defaults remain
+the application's responsibility. With no slot, opening connects the existing
+voice object and lists installed voices, without recording. `compact` gives the
+cog the same small visual circle and 48-pixel target as the avatar voice tools.
+Use `VoiceConversationControls`'s `settings-control` slot to put it after the
+microphone and speaker controls. A custom conversation body owns placement of
+its extracted settings menu.
+
+When Pause occurs while an earlier message is awaiting admission, the original
+recording retains its words, ID and captured destination. Pause immediately mutes
+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.198",
+  "version": "0.1.200",
   "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.226",
+    "@jskit-ai/kernel": "0.1.228",
     "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.226",
+    "@jskit-ai/kernel": "0.1.228",
     "@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.224",
+    "@jskit-ai/http-runtime": "0.1.226",
     "@fastify/fast-json-stringify-compiler": "^5.1.0",
     "@vue/devtools-api": "^8.2.1"
   },
   "devDependencies": {
-    "@jskit-ai/config-eslint": "0.1.223",
-    "@jskit-ai/jskit-catalog": "0.1.251",
+    "@jskit-ai/config-eslint": "0.1.225",
+    "@jskit-ai/jskit-catalog": "0.1.253",
     "@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.226",
+    "@jskit-ai/kernel": "0.1.228",
     "@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.224",
+    "@jskit-ai/http-runtime": "0.1.226",
     "@mdi/js": "^7.4.47",
-    "@jskit-ai/shell-web": "0.1.230",
+    "@jskit-ai/shell-web": "0.1.232",
     "@fastify/fast-json-stringify-compiler": "^5.1.0",
     "@vue/devtools-api": "^8.2.1"
   },
   "devDependencies": {
-    "@jskit-ai/config-eslint": "0.1.223",
-    "@jskit-ai/jskit-catalog": "0.1.251",
+    "@jskit-ai/config-eslint": "0.1.225",
+    "@jskit-ai/jskit-catalog": "0.1.253",
     "@playwright/test": "1.61.1",
     "@vitejs/plugin-vue": "^6.0.7",
     "eslint": "^10.8.0",