@jskit-ai/agent-docs 0.1.218 → 0.1.220

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

@@ -17,6 +17,26 @@ Choose one transcript owner for a conversation. The [ordinary API](./assistant.m
 is the starting point; [advanced hosts](#advanced-host-facilities) and
 [testing](#testing-entrypoints) are separate reference areas.
 
+### Prepare an offline development copy
+
+Advanced hosts that copy a stopped conversation store can call
+`prepareConversationRuntimeCopy(transaction, { at })` from
+`@jskit-ai/assistant-core/server/conversation` inside the destination's ordinary
+storage write transaction. `at` is an ISO timestamp. The host must first isolate
+the destination, stop its processes and pause native provider goals through their
+owners. The helper does not establish those host conditions or invoke providers.
+
+It preserves transcript messages, configuration and native history identity,
+clears copied execution handles, interrupts running turn projections and pauses
+active goal projections. Pending requests remain available for inspection with a
+copy diagnostic; preparation does not replay them. Version 3 state is required,
+and unfinished replacements fail before writes. Upgrade the parent through its
+normal state upgrade process rather than using this helper as a migration.
+
+`prepareCopiedConversationAgentRun(run, { at })` supplies the corresponding pure
+transform for an application's separately stored legacy run projection. Neither
+operation belongs in normal startup or live recovery.
+
 ### Native delivery diagnostics
 
 `createConversationRuntime({ onDeliveryTiming(event) {} })` accepts an optional
@@ -782,6 +802,9 @@ the application may supply one in options. `false`, `{ ok: false, error }`, or
 a thrown error retain a failed entry. Exceptions are rethrown after recording
 the visible failure. Undelivered bubbles use a neutral fill, dashed outline and
 Pending label. A failed bubble has an error outline, its error and Retry action.
+Queued bubbles keep their supplied order while awaiting receipts, even when an
+earlier message receives a later native timestamp. Confirmed history retains
+its chronological ordering.
 Success removes the pending treatment but retains the bubble until authoritative
 history contains its `user.messageId`, so it cannot flicker away before history
 arrives. Older histories without IDs can match by text and timestamp.
@@ -3415,6 +3438,12 @@ native closing checks after the application's replacement and PTY guards; an
 optional application session-closing fact remains lazy. Passive retained-turn
 projection reads the same entry and saved receipt without opening a native session.
 Credential selection, storage and actual terminal access remain host facilities.
+An application-owned `preparation.account(entry)` may explicitly return
+`allowAccountChange: true` for a conversation whose authorized current account
+is controlled by that application. The original account-binding owner then
+requires verified process shutdown before saving the new identity and resuming
+the same native history. The default continues to reject a changed native account;
+this option does not authorize access to a conversation or credentials.
 The same owner reads its closing state and retained turn snapshot; application
 preparation supplies the current authorized session-closing fact, saved receipt
 and PTY state at the original read points. Configured history retirement applies
@@ -3423,8 +3452,14 @@ the application retains saved execution and terminal writer facts.
 
 The retained owner handles the extracted native goal commands and status
 interpretation using its history, activity, interrupt and ordinary Send operations. Pause interrupts the
-work and retains the goal; Cancel interrupts and sends `/goal clear`. Revision
-checks use the native conversation, creation time and objective. This native
+work and retains the goal; Cancel interrupts and sends `/goal clear`.
+Set and Resume may use the existing steering path during an active turn; Set
+still refuses to replace an unfinished goal. Neither action needs a separate
+process or a preliminary cancellation of the current work.
+When only native background tasks remain, steering retires the previous result
+before host preparation. A task completing during preparation cannot settle the
+turn before the follow-up is admitted; the new input requires its own result.
+Revision checks use the native conversation, creation time and objective. This native
 facility is shared by managed native bindings and the common runtime. The runtime
 supplies its existing serialized stop and Send operations, so clearing a goal
 cannot bypass admission, authorization, delivery inspection or cleanup proof.
@@ -3991,6 +4026,10 @@ continue to use the common runtime.
 The same subpath exposes the extracted `createOpenCodeSharedRuntime` for hosts
 whose managed service is shared by several conversation consumers. It owns server
 reuse, pending acquisition, verified final release and exact-server recovery.
+An expired health-probe deadline is reported to the caller without stopping the
+shared server or its other conversations. Retry the readiness operation after
+the server responds again. A refused connection still follows the existing
+server recovery path; a probe timeout alone is not evidence of process failure.
 Its retained Main turn and monitor maps also back the original
 `interruptTurn(key, target, { threadId, writeRun })` operation. The host selects
 the authorized target, supplies a saved identity only when no target exists, and

package/package.json

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

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

@@ -48,7 +48,7 @@
   },
   "devDependencies": {
     "@jskit-ai/config-eslint": "0.1.241",
-    "@jskit-ai/jskit-catalog": "0.1.271",
+    "@jskit-ai/jskit-catalog": "0.1.273",
     "@playwright/test": "1.61.1",
     "@vitejs/plugin-vue": "^6.0.7",
     "eslint": "^10.8.0",

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

@@ -50,7 +50,7 @@
   },
   "devDependencies": {
     "@jskit-ai/config-eslint": "0.1.241",
-    "@jskit-ai/jskit-catalog": "0.1.271",
+    "@jskit-ai/jskit-catalog": "0.1.273",
     "@playwright/test": "1.61.1",
     "@vitejs/plugin-vue": "^6.0.7",
     "eslint": "^10.8.0",

package/reference/autogen/PATTERN_INDEX.md

@@ -15,7 +15,7 @@ A concrete Fastify, Vue, and JSKIT application foundation for products that do n
 
 - Id: `app/minimal-foundation`
 - Keywords: `app`, `fastify`, `foundation`, `minimal`, `server`, `vite`, `vue`
-- Owner: `@jskit-ai/agent-docs@0.1.218`
+- Owner: `@jskit-ai/agent-docs@0.1.220`
 - Read: [PATTERN.md](../../skills/jskit/references/patterns/app/minimal-foundation/PATTERN.md)
 - Examples: [example/](../../skills/jskit/references/patterns/app/minimal-foundation/example/)
 - Requires: `@jskit-ai/http-runtime`, `@jskit-ai/kernel`
@@ -26,7 +26,7 @@ A concrete JSKIT web application foundation with responsive shell navigation, se
 
 - Id: `app/shell-foundation`
 - Keywords: `app`, `foundation`, `material`, `navigation`, `placements`, `shell`, `vite`, `vue`
-- Owner: `@jskit-ai/agent-docs@0.1.218`
+- Owner: `@jskit-ai/agent-docs@0.1.220`
 - Read: [PATTERN.md](../../skills/jskit/references/patterns/app/shell-foundation/PATTERN.md)
 - Examples: [example/](../../skills/jskit/references/patterns/app/shell-foundation/example/)
 - Requires: `@jskit-ai/http-runtime`, `@jskit-ai/kernel`, `@jskit-ai/shell-web`
@@ -37,7 +37,7 @@ Configure an assistant runtime for one application surface and expose its chat a
 
 - Id: `assistant/assistant-surface`
 - Keywords: `ai`, `assistant`, `chat`, `config`, `environment`, `page`, `placement`, `settings`, `surface`
-- Owner: `@jskit-ai/assistant-runtime@0.1.217`
+- Owner: `@jskit-ai/assistant-runtime@0.1.219`
 - Read: [PATTERN.md](../../skills/jskit/references/patterns/assistant/assistant-surface/PATTERN.md)
 - Examples: [example/](../../skills/jskit/references/patterns/assistant/assistant-surface/example/)
 - Requires: `@jskit-ai/assistant-runtime`, `@jskit-ai/connectors-catalog`, `@jskit-ai/connectors-core`, `@jskit-ai/shell-web`
@@ -323,7 +323,7 @@ Define a server feature through explicit capabilities and first-class actions, a
 
 - Id: `server/feature-package`
 - Keywords: `actions`, `feature`, `json-rest`, `knex`, `orchestration`, `package`, `provider`, `repository`, `routes`, `server`
-- Owner: `@jskit-ai/agent-docs@0.1.218`
+- Owner: `@jskit-ai/agent-docs@0.1.220`
 - Read: [PATTERN.md](../../skills/jskit/references/patterns/server/feature-package/PATTERN.md)
 - Examples: [example/](../../skills/jskit/references/patterns/server/feature-package/example/)
 - Requires: `@jskit-ai/kernel`

package/reference/autogen/packages/assistant-core.md

@@ -278,6 +278,7 @@ Exports
 Exports
 - `conversationAgentRunRecord(record, normalizedRunId, { normalizeState = normalizeRunState, isActive = runStateIsActive } = {})`
 - `conversationAgentRunEvent(previous, normalizedRunId, { event = {}, patch = {} } = {}, { now = () => new Date(), normalizeState = normalizeRunState, isTerminal = runStateIsTerminal } = {})`
+- `prepareCopiedConversationAgentRun(run, { at })`
 - `createCodexConversationRunStore({ storage, scope, segmentId, isCurrent, clock = () => new Date() } = {})`
 - `createCodexConversationStore({ storage, scope, segmentId, isCurrent, transcript, streams } = {})`
 Local functions
@@ -321,7 +322,7 @@ Exports
 - `claudeFlagSettings({ effort = "", providerEnv, hooks, commandHook } = {})`
 - `claudeCodeArguments({ sessionId, resume = false, model = "", effort = "", toolFree = false, applicationTools = false, outputSchema, terminal = false, instructionArguments = [], permissionMode, isolated = false, settings = { fallbackModel: [] } } = {})`
 - `stopClaudeCodeProcess({ process: native, executionId, stopExecution })`
-- `bindClaudeConversationAccount(entry, { identity, providerId, stop, save })`
+- `bindClaudeConversationAccount(entry, { identity, providerId, allowAccountChange = false, stop, save })`
 - `claudePlanUsage(value)`
 - `claudeCatalogueModels(initialization)`
 - `createClaudeAccountQueries({ createProcess, accountIdentity, processes = () => [], isClosing = () => false })`
@@ -837,12 +838,14 @@ Exports
 - `finishConversationOperation`
 - `conversationAgentRunRecord`
 - `conversationAgentRunEvent`
+- `prepareCopiedConversationAgentRun`
 - `createFileConversationStorage`
 - `createConversationStreams`
 - `createConversationSystemPrompt`
 - `createConversationRuntime`
 - `normalizeConversationConfiguration`
 - `upgradeConversationRuntimeState`
+- `prepareConversationRuntimeCopy`
 - `createConversationHookBridge`
 - `nativeConversationStoragePolicy`
 - `createConversationProcessIdentity`
@@ -1070,6 +1073,7 @@ Exports
 - `finishConversationRuntimeReplacement(state, { engine, selection, retireNative, pending, value })`
 - `createInertCodexConversationBinding({ workdir, configRoot })`
 - `upgradeConversationRuntimeState({ metadata, conversationLog, retirement })`
+- `prepareConversationRuntimeCopy(transaction, { at })`
 Local functions
 - `object(value)`
 - `invalid(message)`

package/skills/jskit/references/pattern-index.md

@@ -15,7 +15,7 @@ A concrete Fastify, Vue, and JSKIT application foundation for products that do n
 
 - Id: `app/minimal-foundation`
 - Keywords: `app`, `fastify`, `foundation`, `minimal`, `server`, `vite`, `vue`
-- Owner: `@jskit-ai/agent-docs@0.1.218`
+- Owner: `@jskit-ai/agent-docs@0.1.220`
 - Read: [PATTERN.md](patterns/app/minimal-foundation/PATTERN.md)
 - Examples: [example/](patterns/app/minimal-foundation/example/)
 - Requires: `@jskit-ai/http-runtime`, `@jskit-ai/kernel`
@@ -26,7 +26,7 @@ A concrete JSKIT web application foundation with responsive shell navigation, se
 
 - Id: `app/shell-foundation`
 - Keywords: `app`, `foundation`, `material`, `navigation`, `placements`, `shell`, `vite`, `vue`
-- Owner: `@jskit-ai/agent-docs@0.1.218`
+- Owner: `@jskit-ai/agent-docs@0.1.220`
 - Read: [PATTERN.md](patterns/app/shell-foundation/PATTERN.md)
 - Examples: [example/](patterns/app/shell-foundation/example/)
 - Requires: `@jskit-ai/http-runtime`, `@jskit-ai/kernel`, `@jskit-ai/shell-web`
@@ -37,7 +37,7 @@ Configure an assistant runtime for one application surface and expose its chat a
 
 - Id: `assistant/assistant-surface`
 - Keywords: `ai`, `assistant`, `chat`, `config`, `environment`, `page`, `placement`, `settings`, `surface`
-- Owner: `@jskit-ai/assistant-runtime@0.1.217`
+- Owner: `@jskit-ai/assistant-runtime@0.1.219`
 - Read: [PATTERN.md](patterns/assistant/assistant-surface/PATTERN.md)
 - Examples: [example/](patterns/assistant/assistant-surface/example/)
 - Requires: `@jskit-ai/assistant-runtime`, `@jskit-ai/connectors-catalog`, `@jskit-ai/connectors-core`, `@jskit-ai/shell-web`
@@ -323,7 +323,7 @@ Define a server feature through explicit capabilities and first-class actions, a
 
 - Id: `server/feature-package`
 - Keywords: `actions`, `feature`, `json-rest`, `knex`, `orchestration`, `package`, `provider`, `repository`, `routes`, `server`
-- Owner: `@jskit-ai/agent-docs@0.1.218`
+- Owner: `@jskit-ai/agent-docs@0.1.220`
 - Read: [PATTERN.md](patterns/server/feature-package/PATTERN.md)
 - Examples: [example/](patterns/server/feature-package/example/)
 - Requires: `@jskit-ai/kernel`

package/skills/jskit/references/patterns/app/minimal-foundation/example/package.json

@@ -48,7 +48,7 @@
   },
   "devDependencies": {
     "@jskit-ai/config-eslint": "0.1.241",
-    "@jskit-ai/jskit-catalog": "0.1.271",
+    "@jskit-ai/jskit-catalog": "0.1.273",
     "@playwright/test": "1.61.1",
     "@vitejs/plugin-vue": "^6.0.7",
     "eslint": "^10.8.0",

package/skills/jskit/references/patterns/app/shell-foundation/example/package.json

@@ -50,7 +50,7 @@
   },
   "devDependencies": {
     "@jskit-ai/config-eslint": "0.1.241",
-    "@jskit-ai/jskit-catalog": "0.1.271",
+    "@jskit-ai/jskit-catalog": "0.1.273",
     "@playwright/test": "1.61.1",
     "@vitejs/plugin-vue": "^6.0.7",
     "eslint": "^10.8.0",