@jskit-ai/agent-docs 0.1.217 → 0.1.219

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.
@@ -3991,6 +4014,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/guide/agent/app-setup/upgrading-jskit.md

@@ -119,6 +119,24 @@ composed application manifest and let resolution identify its actual consumers.
 The installed-graph check does not replace application-owned non-JSKIT version
 validation or the original root lockfile checks.
 
+### Explicit development sources
+
+Hosts composing selected source checkouts can pass `sourcePackages`, an explicit
+package-name-to-directory map, to both `checkProject` and `checkInstalledGraph`.
+The former exempts only these replaced names from published declaration and
+root lock/installed-version comparisons. Pass the corresponding **materialized**
+directories to the latter: it validates package identity and required dependencies,
+rejects resolution outside each selected real path, and still rejects duplicate
+singleton runtimes, including identical-version copies. Selected source versions
+and their consumer ranges need not match the published catalog.
+
+Always run both stages. Source preflight alone does not prove a usable graph.
+The host still validates external dependency compatibility and prepared exports.
+Unselected packages retain ordinary checks. This programmatic development option
+does not modify manifests or locks, change release pins, or relax CLI/update/CI
+defaults. A missing selected checkout must fail; it is not permission to choose a
+published package instead.
+
 ## Enforce the graph in CI
 
 Run this after `npm ci`, and include it in the application's normal verifier:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/agent-docs",
-  "version": "0.1.217",
+  "version": "0.1.219",
   "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.270",
+    "@jskit-ai/jskit-catalog": "0.1.272",
     "@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.270",
+    "@jskit-ai/jskit-catalog": "0.1.272",
     "@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.217`
+- Owner: `@jskit-ai/agent-docs@0.1.219`
 - 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.217`
+- Owner: `@jskit-ai/agent-docs@0.1.219`
 - 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.216`
+- Owner: `@jskit-ai/assistant-runtime@0.1.218`
 - 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.217`
+- Owner: `@jskit-ai/agent-docs@0.1.219`
 - 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
@@ -306,7 +307,7 @@ Exports
 - `deleteClaudeConversationHistory({ configRoot, workdir, conversationId })`
 - `retireClaudeConversationHistory({ configRoot, binding, beforeDelete, requireIdle, signal })`
 - `claudeHistoryPath({ configRoot, workdir, conversationId })`
-- `claudeMessageBlocks(frame, { includeNested = false } = {})`
+- `claudeMessageBlocks(frame, { includeNested = false, commentary = false } = {})`
 - `readClaudeHistory(options)`
 - `requireClaudeSessionId(id)`
 - `archivedClaudeProjectDirectory(workdir)`
@@ -837,12 +838,14 @@ Exports
 - `finishConversationOperation`
 - `conversationAgentRunRecord`
 - `conversationAgentRunEvent`
+- `prepareCopiedConversationAgentRun`
 - `createFileConversationStorage`
 - `createConversationStreams`
 - `createConversationSystemPrompt`
 - `createConversationRuntime`
 - `normalizeConversationConfiguration`
 - `upgradeConversationRuntimeState`
+- `prepareConversationRuntimeCopy`
 - `createConversationHookBridge`
 - `nativeConversationStoragePolicy`
 - `createConversationProcessIdentity`
@@ -1036,6 +1039,7 @@ Local functions
 ### `src/server/conversation/providers/scoped.js`
 Exports
 - `runScopedConversationTurn({ operations, scope = {}, input = {}, context: options = {}, executionProfile: profileSnapshot } = {})`
+- `projectStoredPersistentConversation(options)`
 - `readPersistentConversation(options)`
 - `startPersistentConversationTurn(options)`
 - `inspectPersistentConversationAdmission(options)`
@@ -1048,6 +1052,7 @@ Local functions
 - `qualifyTranscript(turns, record, response, receipts)`
 - `publishTranscript({ sessionId, store, receipts, publish }, context, record, turns, response = {})`
 - `streamMessage({ sessionId, store, projection, publish }, context, record, event)`
+- `projectPersistentConversation(options, context, record, response, turns)`
 
 ### `src/server/conversation/runtime.js`
 Exports
@@ -1068,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/reference/autogen/tooling/jskit-catalog.md

@@ -63,8 +63,8 @@ Exports
 - `CHECK_SCRIPT`
 - `DEPENDENCY_FIELDS`
 - `UPDATE_SCRIPT`
-- `checkProject({ projectRoot = process.cwd(), catalog, additionalManifests = [], checkInstalled = false } = {})`
-- `checkInstalledGraph({ catalog, manifestPaths = [] } = {})`
+- `checkProject({ projectRoot = process.cwd(), catalog, additionalManifests = [], checkInstalled = false, sourcePackages = {} } = {})`
+- `checkInstalledGraph({ catalog, manifestPaths = [], sourcePackages = {} } = {})`
 - `resolveInstalledPackage(consumerDirectory, packageId)`
 - `collectLockInstallations(packageLock = {})`
 - `discoverProjectManifests(projectRoot, additionalManifests = [])`

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.217`
+- Owner: `@jskit-ai/agent-docs@0.1.219`
 - 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.217`
+- Owner: `@jskit-ai/agent-docs@0.1.219`
 - 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.216`
+- Owner: `@jskit-ai/assistant-runtime@0.1.218`
 - 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.217`
+- Owner: `@jskit-ai/agent-docs@0.1.219`
 - 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.270",
+    "@jskit-ai/jskit-catalog": "0.1.272",
     "@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.270",
+    "@jskit-ai/jskit-catalog": "0.1.272",
     "@playwright/test": "1.61.1",
     "@vitejs/plugin-vue": "^6.0.7",
     "eslint": "^10.8.0",