@jskit-ai/agent-docs 0.1.165 → 0.1.167

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

@@ -16,7 +16,7 @@ Both integrations render the same `AssistantConversationElement`. Choose one tra
 
 | 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 |
+| Bubbles, rich text, reasoning groups, long-message expansion, scroll following, composer, delivery controls, working status, suggestions, model and goal controls, file and question UI | 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 |
@@ -33,7 +33,7 @@ import { AssistantConversationElement } from "@jskit-ai/assistant-core/client/co
 
 const adapter = reactive({
   conversation: {
-    turns, visible: true, loading, error, scrollKey: conversationId,
+    turns, working, visible: true, loading, error, scrollKey: conversationId,
     assistantLabel: "Assistant", hasMoreBefore, loadingMore, loadMoreError
   },
   composer: {
@@ -56,7 +56,7 @@ 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. |
+| `submit({ configuration, attachments })` | 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()` | 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. |
 | `reload()` | Refresh authoritative history. |
@@ -89,6 +89,18 @@ 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 }`.
 
+Reasoning is grouped by adjacency in the displayed message sequence, across
+storage rows. A user message, commentary, answer or system message separates
+groups. Provider turn and conversation IDs do not define progress groups.
+This also groups older saved history without rewriting it.
+
+Supply `conversation.working` from the application's current execution state,
+including assistant-only continuation. While working, the trailing reasoning
+group previews its latest two summaries (`progressPreviewLimit` changes this).
+Other groups start collapsed. Explicit expansion survives new summaries and
+history loading; changing `scrollKey` resets it. When `working` is omitted, the
+element uses `composer.canStop` or a turn's `pending` for existing adapters.
+
 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
@@ -121,7 +133,8 @@ Other slots:
 | `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 |
+| `activity` | `{ activity }`; replace the working indicator; accessible status text stays available |
+| `hints` | `{ adapter }`; replace the entire support row, including default working status and suggestions |
 | `composer` | `{ adapter }`; replace the composer while keeping the shared transcript |
 | `input-start`, `composer-tools` | `{ adapter }`; app-owned input adornments and tools |
 | `composer-feedback` | `{ adapter }`; action feedback after Send/Stop, wrapping below the controls in a narrow pane |
@@ -147,6 +160,163 @@ and an `attachments` slot; it never uploads or deletes files. Its exposed method
 are `focus()`, `preserveHeightForNextModelValue()` and `queueResizeTextarea()`;
 `inputElement` exposes the textarea for app-owned editing operations.
 
+## Optional shared capabilities
+
+All capabilities below are optional. Omit their adapter field to leave them off.
+They work in the aggregate element and as separately exported components; Vibe64
+uses the same components with its native transport and project policy.
+Configuration UI never grants backend permissions.
+
+### Working status and suggestions
+
+The default support row immediately shows “Assistant is working…” when
+`conversation.working` is true (or the fallback above), “Sending to assistant…” during
+admission, and “Stopping…” while `stopPending`. Supply
+`adapter.activity = { label, animated: true }` to choose the text, or use the
+`activity` slot to replace its visual content. An empty label suppresses it.
+`AssistantComposerSupport` is the standalone presentation component. It keeps
+its status row stable and honors reduced-motion preferences.
+
+```js
+import { useAssistantSuggestions } from "@jskit-ai/assistant-core/client/conversation-suggestions";
+const suggestions = reactive(useAssistantSuggestions({
+  active: () => !busy.value,
+  requestKey: () => conversationId.value,
+  draft,
+  configuration: () => ({ integrationId: "suggestions", style: suggestionStyle.value }),
+  generate: ({ draft, configuration, signal }) => app.suggest({ draft, configuration, signal }),
+  onSelect: prompt => { draft.value = prompt; },
+  debounceMs: 750
+}));
+adapter.suggestions = suggestions;
+```
+
+`generate` returns `[{ label, prompt }]`; count is application-defined. It may
+use a different agent, model, prompt and tools from chat. Configuration must be
+JSON-compatible and contain no secrets. The server authorizes and validates it.
+Changing scope, draft, configuration or eligibility aborts and invalidates old
+requests. Disposal cancels requests; late results are ignored. `items`, `loading`,
+`preview`, `visible`, `error`, and `composerFocused` are reactive. `focus`, `blur`,
+`previewSuggestion`, `select`, and `dismiss` drive the shared interaction.
+Selection edits the draft; submission remains explicit. The standalone example
+includes a separate suggestion integration and server prompt.
+
+### Models and application configuration
+
+Use `adapter.models` for `AssistantModelControl`:
+
+```js
+{
+  enabled: true,
+  providerRows: [{ id: "application", label: "Application AI" }],
+  modelProviderId: "application",
+  modelRows: [{ id: "quick", label: "Quick answers" }], modelId: "quick",
+  variantRows: [], variantId: "", // optional thinking/effort choices
+  selectionSummary: "Quick answers", buttonTitle: "Choose AI",
+  changesDisabled: false, saving: false, canSave: true,
+  catalogLoading: false, catalogError: "",
+  selectProvider(id), selectModel(id), selectVariant(id), apply(), reload()
+}
+```
+
+Selections edit application draft configuration. `apply()` saves it and closes
+the chooser unless it resolves `false`. The app handles errors and sets `saving`
+and `changesDisabled`. More than six model choices get searchable selection.
+The standalone component additionally provides `before-choices`, `model-note`,
+`provider-controls`, and `footer` slots for account-specific controls. The
+aggregate's `configurationMode` applies to its separate custom configuration
+fields; disable or omit `models` independently when supplying fixed agent settings.
+
+### Goals
+
+`adapter.goal` uses this contract:
+
+```js
+{
+  enabled: true, pending: false, error: "",
+  goal: { objective: "Finish the report", status: "active",
+    elapsedSeconds: 120, sampledAt: Date.now() },
+  set({ objective, tokenBudget }), pause(), resume()
+}
+```
+
+`goal` is null before creation. `set` receives an optional positive integer token
+budget only when supplied by the user. Callbacks update authoritative state and
+surface failures in `error`; return `false` on unsuccessful creation. The shared
+`AssistantGoalControl` owns the form and presentation, not a scheduler or goal
+storage. Supported statuses are `active`, `paused`, `blocked`, `usageLimited`,
+`budgetLimited`, and `complete`. The UI offers creation only without an unfinished
+goal and offers Pause/Resume only for their applicable statuses.
+
+An active goal flashes red; a paused goal stays orange. `elapsedSeconds` is the
+accumulated **active running time**, and `sampledAt` is its sample time in epoch
+**milliseconds**. The UI adds time only while active. Omit elapsed time if the
+backend cannot supply it truthfully. The clock hides in a narrow conversation
+pane; the light stays visible and details retain the time. Reduced motion uses
+a steady red light. Pausing prevents future automatic turns and does not interrupt
+the current turn; Stop is separate. Omit `goal` or use `enabled: false` for agents
+without goals, including OpenCode.
+
+### Files
+
+```js
+import { useAssistantAttachments } from "@jskit-ai/assistant-core/client/conversation-attachments";
+adapter.attachments = reactive(useAssistantAttachments({
+  sessionId: () => uploadScope.value,
+  maxBytes: 100_000_000, maxItems: 10, uploadConcurrency: 2,
+  uploadAttachment: (scope, file, { signal, onProgress }) => app.upload(scope, file, { signal, onProgress }),
+  deleteAttachment: (scope, attachmentId) => app.deleteUpload(scope, attachmentId)
+}));
+```
+
+`sessionId` is an opaque application upload scope, such as a conversation or
+session identifier. It does not require Vibe64. The application owns routes,
+authentication, storage, limits, inspection, retention and provider file access.
+An upload returns `{ attachmentId, fileName, size }` with optional `reference` and
+application fields. Progress reports use `{ loaded, total }`. The controller
+owns queueing, concurrent uploads, cancellation, retries, stale-response cleanup,
+drag/drop/paste and scope disposal. `queueItems`, `attachments`, `canSubmit`,
+`canAddFiles`, `dragActive`, and `status` feed the aggregate. Uploads block Send
+until resolved; typing stays available. The UI defaults to ten files and 100 MB
+per file; the server must enforce its own limits.
+
+After acknowledged delivery, call
+`clearAttachments({ accepted: true, attachmentIds })` with that submission's
+IDs. It removes only those queue entries and preserves accepted files. To abandon
+uploads, use `accepted: false`. Scope changes/disposal abandon unsent uploads;
+the app's deletion endpoint must preserve files already accepted by a message,
+including when a browser loses the acknowledgement. Never infer acceptance from
+an HTTP request merely starting.
+
+The shared `AssistantAttachmentQueue`, `AssistantMessageAttachments` and
+`AssistantAttachmentPreview` provide queue, sent-file list and preview UI.
+Set `adapter.attachments.open(receipt)` for queue preview. Sent-file rendering
+is available by default; use the `attachments` slot with
+`AssistantMessageAttachments :preview-enabled="true" @preview="openFile"`
+to enable your authorized download flow. `AssistantAttachmentPreview` receives
+`attachment`, an authorized `downloadUrl`, optional image `previewUrl`, and emits
+`close`. It never invents URLs or grants access to a path. A favourite-files
+picker, screenshot producer or project file browser remains an application tool.
+
+### Questions
+
+`AssistantQuestionInputs` renders numbered question fields and suggested-answer
+chips. Pass `questions`, optional `selectItems` keyed by question name, `choices`,
+`v-model:answers`, and `v-model:choice`; handle `dismiss`. Questions contain
+`{ name, number, label, choices }`; choices use `{ value, label, selectLabel }`.
+The aggregate accepts the same fields under `adapter.questions`, with
+`setAnswers`, `setChoice`, and `dismiss` callbacks. Existing question parsers and
+submission formatters are exported from `/shared/conversation`. The app decides
+which message is awaiting a reply and submits answers through its normal action.
+
+### Incremental answers
+
+Replace the same message's `text` as chunks arrive, keeping its identity stable
+and the turn pending until completion. The shared renderer follows new output
+only when the user is already following the latest message; it preserves typing,
+selection and a reader's position in older history. Final text replaces the
+provisional answer. The ready-made runtime performs this mapping automatically.
+
 ## Backend storage contract
 
 ```js
@@ -231,7 +401,7 @@ multi-process writes, failed commits and attachment cleanup.
 
 ## Provider contract
 
-API-model apps can use `createAiClient` and the existing tool-catalog helpers
+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.
 Native-agent hosts can import:
 
@@ -289,7 +459,7 @@ 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.
+provider; an explicit integration configuration enables real AI inference.
 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

@@ -27,8 +27,9 @@ Choose:
 - provider and model policy;
 - whether the assistant begins disabled until credentials exist.
 
-The application records an environment prefix, never an API key, in source.
-Secrets arrive through the normal deployment or development environment.
+The application selects an AI integration ID in server configuration. Credentials
+come from that integration's authorized shared or per-user account. Existing
+environment-prefix configurations remain supported.
 
 ## Composition
 
@@ -41,6 +42,85 @@ Workspace scope is valid only when both the runtime and its settings surface
 are workspace-aware. Requests must retain the selected workspace through the
 server action boundary.
 
+## AI integration: the short setup path
+
+1. Configure an `ai` integration using JSKIT's existing integration editor or
+   portable `integrations.json`. Its provider/model, account mode and credential
+   reference have one owner: the AI integration.
+2. Publish a server capability named `integrations.ai` whose value is
+   `createAiConnectionResolver({ configuration, authorize, resolveReference })`
+   from `@jskit-ai/connectors-catalog/server/ai`. `authorize` derives the trusted
+   `{ applicationId, subjectId }` from the authenticated request. Use the normal
+   environment reference resolver for shared keys and your account resolver for
+   per-user keys. Never return credentials to the browser.
+3. Select it in server config:
+
+```js
+assistantServer: {
+  admin: { aiIntegrationId: "assistant", aiIntegrationIds: ["quick", "detailed"] }
+}
+```
+
+`aiIntegrationId` is the default. `aiIntegrationIds` is an optional allowlist for
+user selection. For a fixed agent, omit that list and hide its model control.
+For selection, pass allowed `{ id, label }` choices to the client. Client values
+never extend the server allowlist. Resolution runs for each request, so account
+isolation, key rotation and disconnect remain the existing resolver's job.
+
+The runtime uses `createAiConnectionClient` from `@jskit-ai/assistant-core/server`
+with the authorized resolver result. JSKIT installs the direct-provider SDK
+adapters and preserves their actual protocols, including Responses, Messages,
+Chat Completions and generateContent. It does not run an OpenCode/Codex coding
+subscription, dynamically install packages, or fall back to a paid model.
+The ordinary action-tool loop stays the runtime's owner; the SDK does not execute
+application tools. Provider availability and account entitlement still come from
+the provider. Existing `aiConfigPrefix` environment configuration is supported
+when no integration is selected; that path rejects client integration overrides.
+
+The `assistant/assistant-surface` pattern includes a concrete AI capability and
+integration file. The published `assistant-core/examples/conversation` template
+also uses this connection path, with an offline demo mode for local exploration.
+
+### Optional files, suggestions and goals
+
+The surface accepts `attachments`, `suggestions`, `goal` and `activity` using the
+[shared capability contracts](./assistant-conversation.md#optional-shared-capabilities).
+The `activity` slot replaces the working visual. Goals are off by default: API
+model providers have no native goal scheduler. Supply one only when your backend
+actually supports it. Suggestions use an independent app-authorized generator;
+selecting a chat model does not silently change the suggestion agent.
+
+For files, supply the shared upload controller to `attachments` and a server
+capability named `assistant.attachments`:
+
+```js
+{
+  async resolve({ attachmentIds, context, workspace, conversation }) {
+    // Authenticate every ID for this actor and conversation, then read bytes.
+    return {
+      attachments: [{ attachmentId, fileName, size }], // safe transcript receipts
+      content: [{ type: "text", text: extractedText }]
+    };
+  }
+}
+```
+
+`content` contains AI SDK user-content parts: text, image bytes with `mediaType`,
+or file bytes with `mediaType` and optional `filename`. The selected model must
+support those inputs. Use authorized bytes rather than user-supplied remote
+URLs. This feature requires the AI integration client; legacy environment model
+clients reject attachments explicitly. Up to ten IDs are accepted per message.
+Current and historical attachment IDs are resolved again on each request.
+Access denial prevents model invocation. The runtime stores only safe receipts
+in message metadata and restores them with history. Upload/download/delete routes,
+bytes, ownership and retention belong to the app. Preserve accepted files when
+an upload-cleanup request arrives after a lost acknowledgement.
+
+The client clears only acknowledged attachment IDs, after the server's `meta`
+event. It retains failed uploads and permits typing while uploads are pending.
+Supply the controller with an upload scope that changes with user, workspace and
+conversation ownership. The server must enforce those boundaries independently.
+
 ## Action tools
 
 The assistant reads automation-capable actions from `runtime.actions`. It keeps
@@ -196,10 +276,12 @@ lookup before discovery-mode execution.
 
 ## Conversation lifecycle
 
-Tool selection, execution, correction, and recovery run silently. The client
-receives tool timeline events, but assistant prose is emitted only when the
-answer is complete. Progress-only responses such as “Let me query…” are
-retried internally and are not stored or replayed as chat history.
+The client receives answer text incrementally and shows working status before
+text arrives. Tool calls produce timeline events. Internal reasoning tags and raw
+tool arguments do not become visible answer text. A tool/recovery round replaces
+its provisional answer; only the completed answer is persisted. Progress-only
+responses such as “Let me query…” may appear provisionally while streaming but
+are retried internally and never stored or replayed as final chat history.
 
 The runtime permits up to 16 bounded tool rounds so catalog search, contract
 lookup, and execution can complete in one turn. If ordinary tool-failure
@@ -291,9 +373,11 @@ Typing during a restore is retained.
 
 `surfaceId` selects an existing configured assistant surface. The presentation
 props are `layout` (`page` or `compact`), `assistantLabel`, `welcomeMessage`,
-`placeholder`, and `showToolActivity`. Configuration controls stay on the
-application's existing assistant-settings route; these presentation props do
-not change provider settings or permissions.
+`placeholder`, and `showToolActivity`. System-prompt settings remain on the
+application's settings route. Optional `connections` and `v-model:integration-id`
+show the shared model chooser; `configuration-mode` is `editable`, `readonly`,
+or `hidden`. Each connection is a safe `{ id, label }` entry, never credentials.
+The server independently validates each selected integration ID.
 
 Conversation selection, Refresh, Start new conversation and loading older
 conversations are available through the Conversations dialog at every width.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/agent-docs",
-  "version": "0.1.165",
+  "version": "0.1.167",
   "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.193",
+    "@jskit-ai/kernel": "0.1.195",
     "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.193",
+    "@jskit-ai/kernel": "0.1.195",
     "@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.191",
+    "@jskit-ai/http-runtime": "0.1.193",
     "@fastify/fast-json-stringify-compiler": "^5.1.0"
   },
   "devDependencies": {
-    "@jskit-ai/config-eslint": "0.1.190",
-    "@jskit-ai/jskit-catalog": "0.1.218",
+    "@jskit-ai/config-eslint": "0.1.192",
+    "@jskit-ai/jskit-catalog": "0.1.220",
     "@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.193",
+    "@jskit-ai/kernel": "0.1.195",
     "@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.191",
+    "@jskit-ai/http-runtime": "0.1.193",
     "@mdi/js": "^7.4.47",
-    "@jskit-ai/shell-web": "0.1.197",
+    "@jskit-ai/shell-web": "0.1.199",
     "@fastify/fast-json-stringify-compiler": "^5.1.0"
   },
   "devDependencies": {
-    "@jskit-ai/config-eslint": "0.1.190",
-    "@jskit-ai/jskit-catalog": "0.1.218",
+    "@jskit-ai/config-eslint": "0.1.192",
+    "@jskit-ai/jskit-catalog": "0.1.220",
     "@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.193"
+    "@jskit-ai/kernel": "0.1.195"
   },
   "jskit": {
     "kind": "runtime",