@jskit-ai/agent-docs 0.1.227 → 0.1.229

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

@@ -50,6 +50,14 @@ Claude and OpenCode use the same milestones: `received`, `preparation-started`,
 `receipt-persisted`, `accepted`, `first-response` and `failed` when applicable.
 `provider-started` to `runtime-ready` includes the provider's acquisition,
 startup or reuse and prompt preparation; it is not an inference timer.
+Finer milestones divide those phases when they occur: `authorized`,
+`history-read`, `state-read`, `request-saved` and `input-prepared` during
+admission; Claude's `duplicate-checked`, `native-history-read`, `process-ready`,
+`prompt-rendered`, `metadata-ready`, `receipt-written` and `state-active`; and
+`admission-authorized` and `turn-located` before `accepted`. A bound host's
+`prepareInput(input, context, { deliveryTiming })` and Claude's
+`preparation.message(..., { deliveryTiming })` receive the same observer and may
+mark `git-actor` and `genesis-rendered`. Unknown stage names are ignored.
 Native acknowledgement precedes the application's receipt write. Accepted delivery
 still waits for the existing durable receipt contract.
 
@@ -1417,6 +1425,7 @@ transcript service. All nine are mandatory for `createConversationRuntime()`:
 | `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. |
+| `findMessageTurnId(messageId)` | Optional. The turn ID holding that message, or an empty string; lets identity lookups avoid reading every turn. |
 | `appendMessage(turnId, message)` | Save `{ role, text, messageId, at }` and any supplied `attachments`, `origin` and `turnMetadata`; user or application messages may start turns. |
 | `replaceAssistant(turnId, message)` | Idempotently replace the final answer for that exact turn, preserving its existing timestamp/identity. |
 | `readMetadata()` | Detached conversation metadata object; return `{}` for an empty scope. |
@@ -2317,10 +2326,15 @@ storage transactions. Runtime state occupies `metadata.runtime` at conversation
 and turn level. Custom adapters must commit that state with accepted messages in
 the same transaction. The file adapter remains one-writer storage.
 
-`createConversationStorage({ readRecord, writeRecord, deleteRecord })` is exported
+`createConversationStorage({ readRecord, writeRecord, deleteRecord, recordVersion })` is exported
 for custom single-writer record stores. Each record contains `{ turns: Map,
 metadata: object }`; a missing record uses an empty map and metadata object. Its
-copy-on-write transaction methods match the supplied memory/file adapters. It
+copy-on-write transaction methods match the supplied memory/file adapters. Saved
+records are shared and never changed in place; a transaction copies only the turn
+map and the turns it changes. The optional `recordVersion(id)` returns a cheap
+token (the file adapter uses device, inode, size and modification time) that
+changes whenever the saved record changes; the parsed record and its message index
+are then reused until the token changes. It
 calls `writeRecord(id, draft, transaction)` to commit a successful transaction.
 Record formats that store the canonical transcript can use `transaction.readTurn()`
 while serializing, without copying the transcript's ordering and role logic.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/agent-docs",
-  "version": "0.1.227",
+  "version": "0.1.229",
   "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.280",
+    "@jskit-ai/jskit-catalog": "0.1.282",
     "@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.280",
+    "@jskit-ai/jskit-catalog": "0.1.282",
     "@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.227`
+- Owner: `@jskit-ai/agent-docs@0.1.229`
 - 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.227`
+- Owner: `@jskit-ai/agent-docs@0.1.229`
 - 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.226`
+- Owner: `@jskit-ai/assistant-runtime@0.1.228`
 - 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.227`
+- Owner: `@jskit-ai/agent-docs@0.1.229`
 - 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

@@ -312,6 +312,10 @@ Exports
 - `requireClaudeSessionId(id)`
 - `archivedClaudeProjectDirectory(workdir)`
 - `matchingClaudeProjectDirectories(names, directory)`
+Local functions
+- `retainedClaudeFrame(frame)`
+- `claudeHistoryFrames(file)`
+- `readClaudeHistoryFrames(file)`
 
 ### `src/server/conversation/claudeProcess.js`
 Exports
@@ -1091,9 +1095,10 @@ Exports
 - `beginConversationOperation(lease)`
 - `finishConversationOperation(lease, participant)`
 - `createReentrantConversationStorage(storage)`
-- `createConversationStorage({ readRecord, writeRecord, deleteRecord })`
+- `createConversationStorage({ readRecord, writeRecord, deleteRecord, recordVersion })`
 Local functions
 - `conversationMessageStorageKey({ role, at, messageId } = {})`
+- `conversationMessageIndex(record)`
 
 ### `src/server/conversation/streams.js`
 Exports

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.227`
+- Owner: `@jskit-ai/agent-docs@0.1.229`
 - 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.227`
+- Owner: `@jskit-ai/agent-docs@0.1.229`
 - 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.226`
+- Owner: `@jskit-ai/assistant-runtime@0.1.228`
 - 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.227`
+- Owner: `@jskit-ai/agent-docs@0.1.229`
 - 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.280",
+    "@jskit-ai/jskit-catalog": "0.1.282",
     "@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.280",
+    "@jskit-ai/jskit-catalog": "0.1.282",
     "@playwright/test": "1.61.1",
     "@vitejs/plugin-vue": "^6.0.7",
     "eslint": "^10.8.0",