@jskit-ai/agent-docs 0.1.161 → 0.1.163

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

@@ -0,0 +1,277 @@
+<!-- Generated by `npm run agent-docs:build` from `packages/agent-docs/site/guide/app-extras/assistant-conversation.md`. Do not edit manually. -->
+
+# Embeddable assistant conversations
+
+`@jskit-ai/assistant-core` supplies a Vue/Vuetify conversation element, transcript
+policy, and native provider primitives. It has no dependency on an editor,
+project directory, application database, identity scheme, or avatar.
+
+Use this contract when the application already owns its conversation endpoints
+or needs custom storage and provider execution. Applications using the complete
+JSKIT assistant surface can continue to use [Assistant](./assistant.md), which
+owns its routes, database repositories, action-tool loop, and settings.
+Choose one transcript owner for a conversation.
+
+## Ownership
+
+| JSKIT owns | The application supplies |
+| --- | --- |
+| Bubbles, rich text, reasoning groups, long-message expansion, scroll following, composer, delivery controls | Conversation selection, labels, loading/errors, current draft and action implementations |
+| Turn grouping, message deduplication, final-answer replacement and history pagination | Storage adapter, authorized scope, transaction/locking implementation, retention, migrations and attachment bytes |
+| Codex JSON-RPC and notification classification, detached-turn completion/recovery, OpenCode HTTP/SSE | Provider process/connection, account credentials, execution environment, permissions, tools, model policy and reconnect ownership |
+| Display of supplied configuration and optional editing controls | Authoritative configuration, permitted changes and server validation |
+
+No global store or router is installed by the element. Multiple assistants can
+coexist with separate adapters. The application mounts it in a pane with a
+definite height and `min-height: 0`.
+
+## Client contract
+
+```js
+import { AssistantConversationElement } from "@jskit-ai/assistant-core/client/conversation";
+
+const adapter = reactive({
+  conversation: {
+    turns, visible: true, loading, error, scrollKey: conversationId,
+    assistantLabel: "Assistant", hasMoreBefore, loadingMore, loadMoreError
+  },
+  composer: {
+    draft, disabled, canSend, pending, canStop, stopDisabled, stopPending,
+    placeholder: "Ask a question…", submitLabel: "Send"
+  },
+  actions: {
+    setDraft, submit, stop, loadMore, reload, resend, cancel, edit, openLink,
+    updateConfiguration
+  }
+});
+```
+
+Use reactive values or replace the adapter when state changes. Ordinary nested
+objects containing refs must be wrapped in `reactive()` so their fields unwrap.
+Only `conversation` is required; omit `composer` for a transcript-only view.
+Missing optional actions are ignored. Supply `setDraft` and `submit` when a
+composer is present, and `stop` when `canStop` can become true.
+
+| Action | Arguments and responsibility |
+| --- | --- |
+| `setDraft(text)` | Update the application draft synchronously. |
+| `submit({ configuration })` | Send or steer through the app's normal admission, attachment and delivery path. Own pending state, accepted-draft clearing and visible failures. The element checks `canSend` before calling. |
+| `stop()` | Stop the owned provider turn. Own pending state and errors; 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. |
+| `reload()` | Refresh authoritative history. |
+| `resend(id)`, `cancel(id)`, `edit(id)` | Handle a failed optimistic turn using its stable `optimistic.id`. Retry according to server delivery evidence. |
+| `openLink({ event, href, text })` | Optionally handle app-owned links and call `event.preventDefault()`. Otherwise a validated ordinary link keeps normal browser behavior. |
+| `updateConfiguration(value)` | Accept an edited draft configuration; the server remains authoritative. |
+
+`scrollKey` changes when conversation ownership changes, resetting scroll and
+expansion state. `followLatestKey` requests following the newest message.
+`reloadable`, `reloading`, `welcomeMessage`, and `variant: "main" | "task"`
+control the corresponding transcript presentation. `userMessageFormat` is
+`"formatted"` by default; `"plain"` preserves literal user-authored text.
+
+### Turns and messages
+
+```js
+{
+  turnId: "stable-app-turn-id",
+  user: { messageId: "request-id", role: "user", text: "Hello", at: "2026-01-01T00:00:00Z", attachments: [] },
+  assistant: { messageId: "reply-id", role: "assistant", text: "Hello back", at: "2026-01-01T00:00:01Z" },
+  messages: [/* ordered user, thinking, commentary and assistant messages */],
+  pending: false,
+  metadata: { /* application data */ }
+}
+```
+
+`system` is an optional status message. Without `messages`, the transcript uses
+the turn's `thinking`, `commentary`, and `assistant` fields. Keep IDs stable across
+updates and pagination. The UI never uses provider-internal turn IDs to decide
+application ownership. An optimistic turn can carry
+`optimistic: { id, status: "failed", error }`.
+
+For an existing flat history, import `conversationTurnsFromMessages` from
+`@jskit-ai/assistant-core/shared/conversation`. It groups ordered messages,
+retains application fields, converts `progressUpdates` into reasoning, and
+recognizes `starting`, `inProgress`, `interrupted`, and `failed` statuses.
+Messages require `text`; applications map names such as `content` explicitly.
+
+### Configuration and slots
+
+```vue
+<AssistantConversationElement
+  :adapter="adapter"
+  :configuration="configuration"
+  configuration-mode="hidden"
+/>
+```
+
+`hidden` hides configuration controls while still passing the supplied object to
+`submit`. `readonly` displays disabled controls. `editable` calls
+`updateConfiguration`. `configurationFields` supplies optional select fields:
+`[{ name, label, items }]`. The `configuration` slot can replace those controls;
+it receives `{ configuration, disabled, update }`. Pending sends disable edits.
+Hiding or disabling controls does **not** authorize backend configuration. The
+server must choose or validate model, tool and permission settings itself.
+
+Other slots:
+
+| Slot | Scope / use |
+| --- | --- |
+| `attachments` | `{ items, message }`; app-owned downloads/previews and access checks |
+| `message-actions` | `{ message, turn }`; integration approvals, SQL actions or other app behavior |
+| `system-message` | `{ message }`; status/repair actions |
+| `hints` | `{ adapter }`; app progress/status/errors above the composer |
+| `composer` | `{ adapter }`; replace the composer while keeping the shared transcript |
+| `input-start`, `composer-tools` | `{ adapter }`; app-owned input adornments and tools |
+
+`AssistantTranscript`, `AssistantPromptInput`, `AssistantComposerActions`, and
+`AssistantProgress` are exported separately for compositions with retained
+drafts or app-managed uploads. `AssistantPromptInput` accepts `attachmentState`
+and an `attachments` slot; it never uploads or deletes files. Its exposed methods
+are `focus()`, `preserveHeightForNextModelValue()` and `queueResizeTextarea()`;
+`inputElement` exposes the textarea for app-owned editing operations.
+
+## Backend storage contract
+
+```js
+import {
+  createConversationTranscript, createMemoryConversationStorage
+} from "@jskit-ai/assistant-core/server/conversation";
+
+const transcript = createConversationTranscript({ storage: createMemoryConversationStorage() });
+await transcript.writeConversationUserMessage(scope, { messageId: requestId, text });
+const { conversationLog, pagination } = await transcript.readConversationLogPage(scope, { limit: 20 });
+```
+
+The memory adapter is explicitly transient. Applications may supply SQL,
+filesystem, document-store, or other storage. JSKIT neither chooses a directory
+nor creates database tables. The storage object implements:
+
+```js
+{
+  read(scope, async transaction => result),
+  write(scope, async transaction => result)
+}
+```
+
+`scope` is opaque to the transcript service. The **server application** derives
+it from the authenticated actor, workspace and conversation. Never pass a
+client-supplied scope directly into storage. Apply the same authorization to
+history, sends, stops, deletion and attachment reads. The memory reference
+adapter requires a nonempty string; other adapters may use structured scopes.
+
+Each callback receives these asynchronous operations:
+
+| Transaction operation | Contract |
+| --- | --- |
+| `listTurnIds()` | Stable IDs in oldest-to-newest order; include all stored turns. |
+| `readTurn(id)` | Detached turn snapshot in the client model above, or null if absent. |
+| `nextTurnId()` | Allocate an ID after the current tail under the write lock. |
+| `hasMessage(messageId)` | Check uniqueness across the whole scoped conversation. |
+| `appendMessage(turnId, message)` | Save `{ role, text, messageId, at }`; user messages also carry `attachments` and `turnMetadata`. |
+| `replaceAssistant(turnId, message)` | Idempotently replace the final answer for that exact turn, preserving its existing timestamp/identity. |
+
+`write` serializes mutations for the same scope, including duplicate checks and
+ID allocation. A successful return means the write is durable for that adapter.
+Database adapters should use a transaction; filesystem adapters must publish
+the message only after its attachment references and metadata are recoverable.
+Errors reject the operation and must remain visible to the caller. Do not
+acknowledge a failed save. Reads must not expose mutable backing objects.
+Use storage-level locks or transactions when several processes share storage;
+an in-process promise queue alone does not provide that guarantee.
+
+The service exposes `readConversationLog`, `readConversationLogPage`,
+`conversationMessageIdExists`, `writeConversationUserMessage`,
+`writeConversationAssistantMessage`, `writeConversationThinkingMessage`,
+`writeConversationCommentaryMessage`, `writeConversationSystemMessage`, and
+`upsertConversationAssistantMessage`. Blank messages and duplicate nonempty
+message IDs return null. A caller must not interpret a duplicate as permission
+to execute a provider turn again. Provider delivery can be uncertain even when
+storage succeeded; the app owns its durable admission/reconciliation policy.
+
+User and system messages open turns. Assistant/reasoning/commentary messages
+attach to the last unanswered user turn when one exists. Activity can specify
+`requireOpenTurn: true`. Final-answer replacement targets an explicit `turnId`.
+User metadata and attachment descriptors are supplied to storage unchanged;
+their schema, bytes, access controls, retention, cleanup, export and deletion
+belong to the app. Never put provider credentials in transcript metadata.
+
+Pagination takes `{ beforeTurnId, limit }`. `limit` is capped at 100; zero means
+all turns. An unknown cursor reads the newest page. Results contain oldest-first
+`conversationLog` and `pagination`, including `hasMoreBefore`,
+`nextBeforeTurnId`, `oldestTurnId`, `newestTurnId`, and `totalTurnCount`.
+
+Run the reusable adapter checks against an isolated fixture:
+
+```js
+import { verifyConversationStorageContract } from "@jskit-ai/assistant-core/testing/conversation-storage";
+await verifyConversationStorageContract(storage);
+```
+
+Those checks cover scoped isolation, concurrent duplicate writes, stable
+ordering, pagination, final replacement, attachments and detached reads. An
+app must additionally test its authentication, crash/reopen behavior,
+multi-process writes, failed commits and attachment cleanup.
+
+## Provider contract
+
+API-model apps can use `createAiClient` and the existing tool-catalog helpers
+from `@jskit-ai/assistant-core/server`, or the complete assistant runtime.
+Native-agent hosts can import:
+
+- `CodexAppServerJsonRpcClient` from `/server/codex-client`;
+- notification classifiers from `/server/codex-events`;
+- `createCodexAppServerDetachedTurnWatcher` from `/server/codex-turn`;
+- `createOpenCodeServerClient` from `/server/opencode-client`.
+
+These are real execution primitives, also consumed by applications with their
+own process and permission owners. They do not spawn an agent, select a user
+account, grant filesystem access or install tools.
+
+The Codex client takes `{ endpoint, maxMessageBytes, requestTimeoutMs,
+WebSocketImpl }`. It connects to a WebSocket or `unix://` endpoint, then
+`initialize({ clientInfo, capabilities })` performs the native handshake.
+`request(method, params, { signal })`, `subscribe(callback)`,
+`setRequestHandler(callback)` and `close()` expose the connection. The app must
+authorize server-initiated tool/approval requests. Missing handlers reject them.
+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 detached watcher takes `(provider, threadId, { includeThreadHistory,
+onEvent, timeoutMs })`. `provider.subscribe` delivers native notifications;
+`provider.readThread` supplies authoritative history when enabled. Call `wait()`
+**before** starting the turn, then `setTurnId()` when startup acknowledges it.
+This preserves completion/failure notifications that arrive before the start
+response. `completeNow`, `failNow`, and `failAfterDetailGrace` handle authoritative
+startup statuses. `onEvent` is a synchronous, nonthrowing observer; enqueue
+asynchronous persistence in the application. The completion result contains
+`{ status, text, threadId, turnId, usage }`. A zero timeout requires provider
+`isAvailable()` and `currentConnectionGeneration()` for connection-loss checks.
+Always await or handle the wait promise and retire it on startup failure.
+
+The OpenCode client accepts a loopback HTTP `baseUrl`, `directory`, credentials,
+and optional `fetchImpl`. It exposes native sessions, prompt, interruption,
+messages, status, events, model/agent catalogues and account operations. Response
+and event reads are bounded. `allowAttachmentDirectories` defaults to false;
+enabling it grants the native conversation access to parent directories of
+supplied attachments. Only the host can make that permission decision after
+resolving and authorizing each file descriptor.
+
+## Companions and templates
+
+A companion can receive an app-selected layer containing conversation state and
+`submitText`, rather than searching the DOM. `createAssistantTextSubmission`
+from `/client/conversation-submit` builds that action from
+`{ getState, setDraft, submit, afterDraftChange }`. State is
+`{ id, active, draft, canSend, turnActive }`. It preserves existing drafts,
+supports `{ sendImmediately: false }`, waits briefly for send readiness, and
+checks draft/ownership again before using the canonical submit action.
+Pass an `AbortSignal` and abort it when selection, visibility or ownership
+changes, including switching away and back to the same retained conversation.
+
+The published package contains `examples/conversation`, a standalone Vue app
+with a Node backend and no editor dependency. Copy it as an application template
+or use the component directly. It runs without credentials using a labelled demo
+provider; optional API credentials enable the existing JSKIT model client.
+Its backend validates configuration independently of the UI and accepts a
+replacement storage module. See its README for commands and scope limits.

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

@@ -13,6 +13,10 @@ npm run db:migrate
 
 Use the `assistant/assistant-surface` pattern. There is no assistant generator.
 
+For an app-owned backend or custom conversation storage, use the
+[embeddable conversation element and backend contracts](./assistant-conversation.md).
+The package includes a standalone application template.
+
 ## Product decisions
 
 Choose:

package/guide/agent/app-extras/realtime.md

@@ -69,6 +69,18 @@ A status indicator is optional product UI. When wanted, register it through the
 normal component and placement APIs. Installing realtime does not append it to
 the shell.
 
+The standard status indicator is a button while disconnected. Clicking it starts
+a fresh connection attempt. The client also retries server-initiated disconnects
+and rejected handshakes, backing off from one second to at most thirty seconds.
+Those extra retries pause while the page is hidden or offline and resume when it
+becomes available. Socket.IO continues to own ordinary transport reconnection.
+Explicit client disconnection and `reconnection: false` remain respected.
+
+Every attempt goes through normal authentication. Reconnection does not restore
+revoked access; an expired login still requires signing in. Applications should
+preserve unsent input, distinguish disconnected status from running work, and
+refresh authoritative state after reconnecting without resending mutations.
+
 ## Verification
 
 Test in-process delivery, audience isolation, authenticated-handshake rejection

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/agent-docs",
-  "version": "0.1.161",
+  "version": "0.1.163",
   "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.189",
+    "@jskit-ai/kernel": "0.1.191",
     "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.189",
+    "@jskit-ai/kernel": "0.1.191",
     "@tanstack/vue-query": "^5.101.0",
     "fastify": "^5.8.5",
     "json-rest-schema": "^1.0.17",
@@ -42,12 +42,12 @@
     "vue": "^3.5.38",
     "vue-router": "^5.1.0",
     "vuetify": "^4.1.2",
-    "@jskit-ai/http-runtime": "0.1.187",
+    "@jskit-ai/http-runtime": "0.1.189",
     "@fastify/fast-json-stringify-compiler": "^5.1.0"
   },
   "devDependencies": {
-    "@jskit-ai/config-eslint": "0.1.186",
-    "@jskit-ai/jskit-catalog": "0.1.214",
+    "@jskit-ai/config-eslint": "0.1.188",
+    "@jskit-ai/jskit-catalog": "0.1.216",
     "@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.189",
+    "@jskit-ai/kernel": "0.1.191",
     "@tanstack/vue-query": "^5.101.0",
     "fastify": "^5.8.5",
     "json-rest-schema": "^1.0.17",
@@ -42,14 +42,14 @@
     "vue": "^3.5.38",
     "vue-router": "^5.1.0",
     "vuetify": "^4.1.2",
-    "@jskit-ai/http-runtime": "0.1.187",
+    "@jskit-ai/http-runtime": "0.1.189",
     "@mdi/js": "^7.4.47",
-    "@jskit-ai/shell-web": "0.1.193",
+    "@jskit-ai/shell-web": "0.1.195",
     "@fastify/fast-json-stringify-compiler": "^5.1.0"
   },
   "devDependencies": {
-    "@jskit-ai/config-eslint": "0.1.186",
-    "@jskit-ai/jskit-catalog": "0.1.214",
+    "@jskit-ai/config-eslint": "0.1.188",
+    "@jskit-ai/jskit-catalog": "0.1.216",
     "@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.189"
+    "@jskit-ai/kernel": "0.1.191"
   },
   "jskit": {
     "kind": "runtime",