typeclaw 0.36.8 → 0.37.1

package/src/init/models-dev.ts

@@ -1,4 +1,13 @@
-import { KNOWN_PROVIDERS, type KnownModelRef, type KnownProviderId, listKnownModelRefs } from '@/config/providers'
+import type { CustomModelMeta } from '@/config'
+import {
+  KNOWN_PROVIDERS,
+  isKnownModelRef,
+  isModelRef,
+  listKnownModelRefs,
+  providerForModelRef,
+  type KnownProviderId,
+  type ModelRef,
+} from '@/config/providers'
 
 const MODELS_DEV_URL = 'https://models.dev/api.json'
 const REQUEST_TIMEOUT_MS = 10_000
@@ -23,16 +32,24 @@ const PROVIDER_TO_MODELS_DEV: Record<KnownProviderId, string> = {
   xai: 'xai',
   minimax: 'minimax',
   deepseek: 'deepseek',
+  moonshot: 'moonshot',
+  // moonshot-coding (Kimi Code subscription) is a billing surface, not a
+  // separate model catalog. models.dev tracks the underlying Kimi model
+  // metadata under `moonshot`, so we route lookups there; the curated
+  // `kimi-for-coding` alias is surfaced regardless of upstream membership.
+  'moonshot-coding': 'moonshot',
 }
 
 export type ModelOption = {
-  ref: KnownModelRef
+  ref: ModelRef | string
   providerId: KnownProviderId
   providerName: string
   modelId: string
   modelName: string
   reasoning: boolean
   contextWindow: number | null
+  maxTokens?: number | null
+  cost?: ModelOptionCost | null
   curated: boolean
   // True iff the model accepts image input. Sourced from the curated
   // `Model.input` array (which is the source of truth — pi-ai consumes it
@@ -43,6 +60,13 @@ export type ModelOption = {
   supportsVision: boolean
 }
 
+export type ModelOptionCost = {
+  input: number
+  output: number
+  cacheRead: number
+  cacheWrite: number
+}
+
 type ModelsDevModel = {
   id?: string
   name?: string
@@ -51,7 +75,15 @@ type ModelsDevModel = {
   status?: string
   release_date?: string
   modalities?: { input?: string[]; output?: string[] }
-  limit?: { context?: number }
+  limit?: { context?: number; output?: number }
+  cost?: {
+    input?: number
+    output?: number
+    cacheRead?: number
+    cacheWrite?: number
+    cache_read?: number
+    cache_write?: number
+  }
 }
 
 type ModelsDevProvider = {
@@ -99,22 +131,47 @@ export function curatedOptions(): ModelOption[] {
   return refs.map((ref) => buildOption(ref, { curated: true }))
 }
 
-// `data` is the parsed models.dev JSON. We walk only the providers we care
-// about (openai, fireworks-ai) and only emit options for models that are
-// also in our curated allowlist — anything outside the allowlist would fail
-// schema validation when written to typeclaw.json. Curated entries that
-// models.dev doesn't list (e.g. kimi-k2p6-turbo) are still surfaced so the
-// user can pick them.
+export function customModelMetaFromOption(option: ModelOption): CustomModelMeta | undefined {
+  if (isKnownModelRef(option.ref)) return undefined
+  if (!isModelRef(option.ref)) return undefined
+  return {
+    name: option.modelName,
+    reasoning: option.reasoning,
+    input: option.supportsVision ? ['text', 'image'] : ['text'],
+    ...(option.contextWindow !== null ? { contextWindow: option.contextWindow } : {}),
+    ...(option.maxTokens !== undefined && option.maxTokens !== null ? { maxTokens: option.maxTokens } : {}),
+    ...(option.cost !== undefined && option.cost !== null ? { cost: option.cost } : {}),
+  }
+}
+
+// `data` is the parsed models.dev JSON. We keep every curated entry first
+// (including provider-specific aliases models.dev does not list), then append
+// live upstream models whose refs validate against a known TypeClaw provider.
 function mergeWithCurated(data: Record<string, ModelsDevProvider>): ModelOption[] {
   const out: ModelOption[] = []
+  const seen = new Set<string>()
   for (const providerId of Object.keys(KNOWN_PROVIDERS) as KnownProviderId[]) {
     const known = KNOWN_PROVIDERS[providerId]
     const upstream = data[PROVIDER_TO_MODELS_DEV[providerId]]
     const upstreamModels = upstream?.models ?? {}
     for (const modelId of Object.keys(known.models)) {
       const upstreamModel = upstreamModels[modelId]
-      const ref = `${providerId}/${modelId}` as KnownModelRef
+      const ref = `${providerId}/${modelId}`
       out.push(buildOption(ref, { curated: true, upstream: upstreamModel }))
+      seen.add(ref)
+    }
+  }
+
+  for (const providerId of Object.keys(KNOWN_PROVIDERS) as KnownProviderId[]) {
+    const upstream = data[PROVIDER_TO_MODELS_DEV[providerId]]
+    const upstreamModels = upstream?.models ?? {}
+    for (const [fallbackModelId, upstreamModel] of Object.entries(upstreamModels)) {
+      const modelId = upstreamModel.id ?? fallbackModelId
+      if (modelId.trim().length === 0) continue
+      const ref = `${providerId}/${modelId}`
+      if (seen.has(ref) || !isModelRef(ref)) continue
+      out.push(buildOption(ref, { curated: isKnownModelRef(ref), upstream: upstreamModel }))
+      seen.add(ref)
     }
   }
   return out
@@ -125,17 +182,23 @@ type BuildOptionOpts = {
   upstream?: ModelsDevModel
 }
 
-function buildOption(ref: KnownModelRef, opts: BuildOptionOpts): ModelOption {
-  const slash = ref.indexOf('/')
-  const providerId = ref.slice(0, slash) as KnownProviderId
-  const modelId = ref.slice(slash + 1)
+function buildOption(ref: ModelRef | string, opts: BuildOptionOpts): ModelOption {
+  const providerId = providerForModelRef(ref)
+  const modelId = ref.slice(providerId.length + 1)
   const provider = KNOWN_PROVIDERS[providerId]
   const curatedModel = (
     provider.models as Record<
       string,
-      { name: string; contextWindow?: number; reasoning?: boolean; input?: ReadonlyArray<string> }
+      {
+        name: string
+        contextWindow?: number
+        maxTokens?: number
+        reasoning?: boolean
+        input?: ReadonlyArray<string>
+      }
     >
   )[modelId]
+  const input = resolveInput(curatedModel?.input, opts.upstream?.modalities?.input)
   return {
     ref,
     providerId,
@@ -144,16 +207,28 @@ function buildOption(ref: KnownModelRef, opts: BuildOptionOpts): ModelOption {
     modelName: opts.upstream?.name ?? curatedModel?.name ?? modelId,
     reasoning: opts.upstream?.reasoning ?? curatedModel?.reasoning ?? false,
     contextWindow: opts.upstream?.limit?.context ?? curatedModel?.contextWindow ?? null,
+    maxTokens: opts.upstream?.limit?.output ?? curatedModel?.maxTokens ?? null,
+    cost: resolveCost(opts.upstream?.cost),
     curated: opts.curated,
-    supportsVision: resolveSupportsVision(curatedModel?.input, opts.upstream?.modalities?.input),
+    supportsVision: input.includes('image'),
   }
 }
 
-function resolveSupportsVision(
+function resolveInput(
   curatedInput: ReadonlyArray<string> | undefined,
   upstreamInput: ReadonlyArray<string> | undefined,
-): boolean {
-  if (curatedInput !== undefined) return curatedInput.includes('image')
-  if (upstreamInput !== undefined) return upstreamInput.includes('image')
-  return false
+): string[] {
+  if (curatedInput !== undefined) return [...curatedInput]
+  if (upstreamInput !== undefined && upstreamInput.length > 0) return [...upstreamInput]
+  return ['text']
+}
+
+function resolveCost(cost: ModelsDevModel['cost']): ModelOptionCost | null {
+  if (cost === undefined) return null
+  return {
+    input: cost.input ?? 0,
+    output: cost.output ?? 0,
+    cacheRead: cost.cacheRead ?? cost.cache_read ?? 0,
+    cacheWrite: cost.cacheWrite ?? cost.cache_write ?? 0,
+  }
 }

package/src/init/oauth-login.ts

@@ -4,14 +4,14 @@ import {
   KNOWN_PROVIDERS,
   providerForModelRef,
   supportsOAuth,
-  type KnownModelRef,
   type KnownProviderId,
+  type ModelRef,
 } from '@/config/providers'
 import { createSecretsStoreForAgent } from '@/secrets'
 
 export type OAuthLoginResult = { ok: true } | { ok: false; reason: string }
 
-export type OAuthLoginRunner = (options: { cwd: string; model: KnownModelRef }) => Promise<OAuthLoginResult>
+export type OAuthLoginRunner = (options: { cwd: string; model: ModelRef | string }) => Promise<OAuthLoginResult>
 
 // Wrap pi-ai's OAuth callbacks so the CLI doesn't have to know about the
 // upstream callback shape. The CLI sees four lifecycle events:
@@ -76,7 +76,7 @@ export function makeOAuthLoginRunner(callbacks: OAuthCallbacks): OAuthLoginRunne
 // params" without spinning up a real secrets store / browser callback server.
 export type FakeOAuthLoginRunnerOptions = {
   result?: OAuthLoginResult
-  onCalled?: (options: { cwd: string; model: KnownModelRef; providerId: KnownProviderId }) => void
+  onCalled?: (options: { cwd: string; model: ModelRef | string; providerId: KnownProviderId }) => void
 }
 
 export function makeFakeOAuthLoginRunner(options: FakeOAuthLoginRunnerOptions = {}): OAuthLoginRunner {

package/src/init/progress.ts

@@ -0,0 +1,29 @@
+import type { WizardAnswerCheckpointV1, WizardCheckpointStore } from './checkpoint'
+import { isHatched } from './index'
+
+export type InitProgressStatus =
+  | { kind: 'none' }
+  | { kind: 'incomplete'; checkpoint: WizardAnswerCheckpointV1 }
+  | { kind: 'complete-stale-checkpoint'; checkpoint: WizardAnswerCheckpointV1 }
+
+export interface DetectInitProgressOptions {
+  cwd: string
+  checkpointStore: WizardCheckpointStore
+  isHatched?: (dir: string) => Promise<boolean>
+}
+
+// Single shared predicate for "is this init incomplete?", consumed by both the
+// init resume-prompt and the start/restart launchers so the two never drift.
+//
+// `isHatched` is the completion authority — NOT the presence of node_modules,
+// Dockerfile, or typeclaw.json, which are intermediate artifacts that start can
+// regenerate. A checkpoint that outlives a hatched agent (clear failed after a
+// successful run) is reported as `complete-stale-checkpoint` so callers can
+// opportunistically clean it up instead of falsely blocking a working agent.
+export async function detectInitProgress(options: DetectInitProgressOptions): Promise<InitProgressStatus> {
+  const hatchedCheck = options.isHatched ?? isHatched
+  const checkpoint = await options.checkpointStore.load(options.cwd)
+  if (checkpoint === undefined) return { kind: 'none' }
+  if (await hatchedCheck(options.cwd)) return { kind: 'complete-stale-checkpoint', checkpoint }
+  return { kind: 'incomplete', checkpoint }
+}

package/src/init/validate-api-key.ts

@@ -10,6 +10,8 @@ const PROVIDER_PROBE: Partial<Record<KnownProviderId, { url: string; authHeader:
   xai: { url: 'https://api.x.ai/v1/models', authHeader: 'bearer' },
   minimax: { url: 'https://api.minimax.io/v1/models', authHeader: 'bearer' },
   deepseek: { url: 'https://api.deepseek.com/models', authHeader: 'bearer' },
+  moonshot: { url: 'https://api.moonshot.ai/v1/models', authHeader: 'bearer' },
+  'moonshot-coding': { url: 'https://api.kimi.com/coding/v1/models', authHeader: 'bearer' },
 }
 
 // When a base-URL override (ANTHROPIC_BASE_URL / OPENAI_BASE_URL) points at a
@@ -165,6 +167,8 @@ export const API_KEY_DASHBOARD_URL: Partial<Record<KnownProviderId, string>> = {
   xai: 'https://console.x.ai',
   minimax: 'https://platform.minimax.io/user-center/basic-information/interface-key',
   deepseek: 'https://platform.deepseek.com/api_keys',
+  moonshot: 'https://platform.moonshot.ai/console/api-keys',
+  'moonshot-coding': 'https://www.kimi.com/code/console',
 }
 
 // MiniMax sells the same `minimax` provider under two billing surfaces that

package/src/inspect/index.ts

@@ -14,6 +14,8 @@ export { originLabel, shortSessionId } from './label'
 export { renderEvent } from './render'
 export { replayJsonl } from './replay'
 export { streamLive } from './live'
+export { fetchLiveSessions } from './live-list'
+export type { FetchLiveSessionsOptions } from './live-list'
 export { parseDuration, parseFilter } from './types'
 export type { InspectCategory, InspectEvent, InspectFilter } from './types'
 export { runInspectLoop, runViewerLoop } from './loop'
@@ -219,12 +221,17 @@ export async function streamSessionEvents(opts: StreamSessionEventsOptions): Pro
     opts.onEvent(event)
   }
 
-  for await (const event of replayJsonl(
-    opts.summary.sessionFile,
-    opts.onWarn !== undefined ? { onWarn: opts.onWarn } : {},
-  )) {
-    if (aborted()) return { escToPicker: true }
-    deliver(event)
+  // A live-only session (registry-derived, no .jsonl yet) has an empty
+  // sessionFile: skip replay and go straight to the live tail. Replaying ''
+  // would just emit a spurious "file does not exist" warning.
+  if (opts.summary.sessionFile !== '') {
+    for await (const event of replayJsonl(
+      opts.summary.sessionFile,
+      opts.onWarn !== undefined ? { onWarn: opts.onWarn } : {},
+    )) {
+      if (aborted()) return { escToPicker: true }
+      deliver(event)
+    }
   }
   opts.onPhase?.({ phase: 'replay-end' })
 

package/src/inspect/item-list.ts

@@ -1,5 +1,7 @@
+import type { LiveSessionPayload } from '@/shared'
+
 import type { ViewerItem } from './item'
-import { listSessions, type ListSessionsOptions, type SessionSummary } from './session-list'
+import { listSessions, type ListSessionsOptions, mergeLiveSessions, type SessionSummary } from './session-list'
 
 export type ListViewerItemsOptions = ListSessionsOptions & {
   containerRunning: boolean
@@ -9,6 +11,9 @@ export type ListViewerItemsOptions = ListSessionsOptions & {
   // (most-recent) tui transcript — and any older tui transcript the heuristic
   // would otherwise promote — must NOT be offered as a writable live row.
   allowWritable?: boolean
+  // Registry sessions not yet flushed to disk, fetched by the CLI over the
+  // /inspect WS. The lib layer stays I/O-free; the caller owns the connection.
+  liveSessions?: LiveSessionPayload[]
 }
 
 export type ViewerList = {
@@ -23,7 +28,11 @@ export type ViewerList = {
 // sessions are read-only. The `logs` row is appended last (container stdout,
 // available offline) so it sits below the divider in the picker.
 export async function listViewerItems(opts: ListViewerItemsOptions): Promise<ViewerList> {
-  const sessions = await listSessions(opts)
+  const diskSessions = await listSessions(opts)
+  const sessions =
+    opts.liveSessions !== undefined && opts.liveSessions.length > 0
+      ? mergeLiveSessions(diskSessions, opts.liveSessions)
+      : diskSessions
   const allowWritable = opts.allowWritable !== false
   const writableSessionId = opts.containerRunning && allowWritable ? pickWritableSession(sessions) : null
 

package/src/inspect/live-list.ts

@@ -0,0 +1,65 @@
+import type { InspectClientMessage, InspectServerMessage, LiveSessionPayload } from '@/shared'
+
+export type FetchLiveSessionsOptions = {
+  url: string
+  signal?: AbortSignal
+  WebSocketImpl?: typeof WebSocket
+  timeoutMs?: number
+}
+
+const DEFAULT_TIMEOUT_MS = 5_000
+
+// One-shot query of the container's in-memory session registry over the
+// /inspect WS: open, send list_live, read the single reply, close. Failure
+// (container down, timeout, abort) resolves to [] so the picker degrades to the
+// disk-only listing rather than erroring — the live overlay is best-effort.
+export async function fetchLiveSessions(opts: FetchLiveSessionsOptions): Promise<LiveSessionPayload[]> {
+  const WS = opts.WebSocketImpl ?? WebSocket
+  if (opts.signal?.aborted === true) return []
+
+  return new Promise<LiveSessionPayload[]>((resolve) => {
+    let settled = false
+    const ws = new WS(opts.url)
+
+    const finish = (result: LiveSessionPayload[]): void => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      try {
+        ws.close()
+      } catch {
+        /* ignore */
+      }
+      resolve(result)
+    }
+
+    const timer = setTimeout(() => finish([]), opts.timeoutMs ?? DEFAULT_TIMEOUT_MS)
+
+    if (opts.signal !== undefined) {
+      opts.signal.addEventListener('abort', () => finish([]), { once: true })
+    }
+
+    ws.addEventListener('open', () => {
+      const req: InspectClientMessage = { type: 'list_live' }
+      try {
+        ws.send(JSON.stringify(req))
+      } catch {
+        finish([])
+      }
+    })
+
+    ws.addEventListener('message', (e) => {
+      let msg: InspectServerMessage
+      try {
+        msg = JSON.parse(String((e as MessageEvent).data)) as InspectServerMessage
+      } catch {
+        return
+      }
+      if (msg.type === 'live_sessions') finish(msg.sessions)
+      else if (msg.type === 'error') finish([])
+    })
+
+    ws.addEventListener('error', () => finish([]))
+    ws.addEventListener('close', () => finish([]))
+  })
+}

package/src/inspect/open-item.ts

@@ -1,8 +1,11 @@
+import { join } from 'node:path'
+
 import type { LiveSourceFactory, RunInspectResult } from './index'
 import { createTranscriptView, streamInspectTarget } from './index'
 import type { ViewerItem } from './item'
 import { streamLogs } from './logs-item'
 import type { OpenItemContext, OpenItemResult, TailController } from './loop'
+import { resolveSession } from './session-list'
 import { runTuiViewer } from './tui-item'
 import type { InspectFilter } from './types'
 
@@ -28,7 +31,14 @@ export type OpenViewerDeps = {
 // would corrupt input). The line/JSON session path and logs run UNDER the tail
 // scope, which owns the raw-mode esc/q/ctrl-c handling.
 export function openViewerItem(deps: OpenViewerDeps) {
-  return async (item: ViewerItem, ctx: OpenItemContext): Promise<OpenItemResult> => {
+  return async (rawItem: ViewerItem, ctx: OpenItemContext): Promise<OpenItemResult> => {
+    // A live-only row captured `sessionFile: ''` when it was listed. By the time
+    // the user opens it the reply may have flushed to disk AND the registry
+    // entry may be gone — leaving the live tail broadcast-only and skipping the
+    // now-existing transcript. Re-resolve against the sessions dir so a
+    // flushed session opens as its real disk summary (replay + live tail).
+    const item = await reresolveLiveItem(rawItem, deps.cwd, deps.stderr)
+
     if (item.kind === 'tui') {
       const result = await runTuiViewer({
         resolveUrl: deps.resolveTuiUrl,
@@ -93,6 +103,17 @@ export function openViewerItem(deps: OpenViewerDeps) {
   }
 }
 
+export async function reresolveLiveItem(
+  item: ViewerItem,
+  cwd: string,
+  onWarn: (line: string) => void,
+): Promise<ViewerItem> {
+  if (item.kind === 'logs' || item.summary.live !== true) return item
+  const resolved = await resolveSession(join(cwd, 'sessions'), item.summary.sessionId, onWarn)
+  if (!resolved.ok) return item
+  return { kind: 'session', summary: resolved.summary, writable: false }
+}
+
 function toResult(escToPicker: boolean, scope: TailController): RunInspectResult {
   if (scope.intent() === 'exit') return { ok: true, exitCode: 0 }
   if (escToPicker) return { ok: true, exitCode: 0, escToPicker: true }

package/src/inspect/session-list.ts

@@ -2,6 +2,7 @@ import { readdir, stat } from 'node:fs/promises'
 import { join } from 'node:path'
 
 import type { MinimalSessionOrigin } from '@/agent/session-meta'
+import type { LiveSessionPayload } from '@/shared'
 
 import { previewForHint } from './preview'
 import { replayJsonl } from './replay'
@@ -13,6 +14,11 @@ export type SessionSummary = {
   mtimeMs: number
   origin: MinimalSessionOrigin | null
   firstPrompt: string | null
+  // True only for a registry-derived session with no .jsonl on disk yet (a
+  // reply is in flight). Disk sessions leave this undefined. Selecting one tails
+  // live-only: streamSessionEvents replays an empty file, then the WS delivers
+  // events as they happen.
+  live?: boolean
 }
 
 export type ListSessionsOptions = {
@@ -65,6 +71,29 @@ export async function listSessions(opts: ListSessionsOptions): Promise<SessionSu
   )
 }
 
+// Overlay container-registry sessions onto the disk listing. A live session
+// already flushed to disk (post-reply) is dropped from the overlay — the disk
+// summary wins, carrying its real mtime and prompt preview. Only sessions with
+// no .jsonl yet become synthetic live rows, sorted to the top by registration
+// time so an in-flight reply surfaces above settled history.
+export function mergeLiveSessions(disk: SessionSummary[], live: LiveSessionPayload[]): SessionSummary[] {
+  const onDisk = new Set(disk.map((s) => s.sessionId))
+  const liveOnly = live
+    .filter((l) => !onDisk.has(l.sessionId))
+    .map(
+      (l): SessionSummary => ({
+        sessionId: l.sessionId,
+        sessionFile: '',
+        basename: '',
+        mtimeMs: l.registeredAtMs,
+        origin: l.origin,
+        firstPrompt: null,
+        live: true,
+      }),
+    )
+  return [...liveOnly, ...disk].sort((a, b) => b.mtimeMs - a.mtimeMs)
+}
+
 export type ResolveResult =
   | { ok: true; summary: SessionSummary }
   | { ok: false; reason: 'not-found' | 'ambiguous'; matches: SessionSummary[] }

package/src/models/embedding-model.ts

@@ -0,0 +1,114 @@
+import { readFile, rename, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+export const EMBEDDING_MODEL_NAME = 'Xenova/multilingual-e5-base'
+export const EMBEDDING_MODEL_DTYPE = 'q8'
+export const EMBEDDING_DIMS = 768
+
+// The embedding recipe that makes two vectors comparable: E5 query/passage
+// prefixing + mean pooling + L2 normalize. Stamped in the sentinel (not folded
+// into EMBEDDING_MODEL_ID, which is a stored-row filter — changing the ID would
+// invalidate every existing vector row). A future pooling/normalize change
+// bumps this string so a stale cache fails the sentinel loudly.
+export const EMBEDDING_RECIPE = 'e5-prefix:mean-pool:l2-normalize'
+
+// Stored-row identity = name@dtype. Used by the vector store to filter rows
+// from an incompatible model/dtype variant out of cosine scans.
+export const EMBEDDING_MODEL_ID = `${EMBEDDING_MODEL_NAME}@${EMBEDDING_MODEL_DTYPE}`
+
+const SENTINEL_FILE = '.typeclaw-model.json'
+
+export type ModelSentinel = {
+  schemaVersion: 1
+  model: string
+  dtype: string
+  dims: number
+  recipe: string
+  transformers: string
+}
+
+function sentinelPath(dir: string): string {
+  return join(dir, SENTINEL_FILE)
+}
+
+function expectedSentinel(transformers: string): Omit<ModelSentinel, 'transformers'> & { transformers: string } {
+  return {
+    schemaVersion: 1,
+    model: EMBEDDING_MODEL_NAME,
+    dtype: EMBEDDING_MODEL_DTYPE,
+    dims: EMBEDDING_DIMS,
+    recipe: EMBEDDING_RECIPE,
+    transformers,
+  }
+}
+
+// Atomic write-then-rename so a container reader can never observe a partial
+// JSON file mid-write. Called host-side after a successful model download,
+// inside the proper-lockfile critical section.
+export async function writeModelSentinel(dir: string, input: { transformers: string }): Promise<void> {
+  const sentinel = expectedSentinel(input.transformers)
+  const tmp = `${sentinelPath(dir)}.${process.pid}.tmp`
+  await writeFile(tmp, `${JSON.stringify(sentinel, null, 2)}\n`, 'utf8')
+  await rename(tmp, sentinelPath(dir))
+}
+
+export async function readModelSentinel(dir: string): Promise<ModelSentinel | null> {
+  let raw: string
+  try {
+    raw = await readFile(sentinelPath(dir), 'utf8')
+  } catch {
+    return null
+  }
+  try {
+    const parsed = JSON.parse(raw) as Partial<ModelSentinel>
+    if (
+      parsed.schemaVersion !== 1 ||
+      typeof parsed.model !== 'string' ||
+      typeof parsed.dtype !== 'string' ||
+      typeof parsed.dims !== 'number' ||
+      typeof parsed.recipe !== 'string' ||
+      typeof parsed.transformers !== 'string'
+    ) {
+      return null
+    }
+    return parsed as ModelSentinel
+  } catch {
+    return null
+  }
+}
+
+// Throws a TypeClaw-authored error (naming observed vs expected identity, with
+// the fix) BEFORE the container's `local_files_only` pipeline load — so a
+// host/container drift surfaces as a clear "refresh the cache" message instead
+// of a cryptic missing-file miss, OR worse, a stale file that loads against a
+// different producer's layout and silently returns garbage vectors. Absent
+// sentinel is a hard failure: host ensureModels() writes it before `docker
+// run` in the same `typeclaw start`, so a missing one means the mount is wrong
+// or the cache was hand-copied — exactly the case we must not paper over.
+export async function assertModelCacheCompatible(dir: string, expected: { transformers: string }): Promise<void> {
+  const sentinel = await readModelSentinel(dir)
+  const want = expectedSentinel(expected.transformers)
+  if (sentinel === null) {
+    throw new Error(
+      `TypeClaw model cache at ${dir} is missing or has an unreadable ${SENTINEL_FILE}, so compatibility with ` +
+        `this container cannot be verified. Re-run \`typeclaw start\` to refresh the model cache; if it was copied ` +
+        `manually, delete it and start again.`,
+    )
+  }
+  const mismatches = describeMismatches(sentinel, want)
+  if (mismatches.length > 0) {
+    throw new Error(
+      `TypeClaw model cache at ${dir} is incompatible with this container (${mismatches.join('; ')}). ` +
+        `Re-run \`typeclaw start\` to refresh the model cache.`,
+    )
+  }
+}
+
+function describeMismatches(got: ModelSentinel, want: ModelSentinel): string[] {
+  const fields: Array<keyof ModelSentinel> = ['model', 'dtype', 'dims', 'recipe', 'transformers']
+  return fields
+    .filter((field) => got[field] !== want[field])
+    .map(
+      (field) => `${field}: cache has ${JSON.stringify(got[field])}, container expects ${JSON.stringify(want[field])}`,
+    )
+}

package/src/models/transformers-version.ts

@@ -0,0 +1,55 @@
+import { readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { dirname, join, parse as parsePath } from 'node:path'
+
+// The ACTUALLY-INSTALLED @huggingface/transformers version in the current
+// runtime, read from the resolved package's own package.json — NOT from
+// typeclaw's dependency spec (which is the intended version, not what is on
+// disk). The model-cache sentinel compares this across stages: the host
+// stamps the version that produced the download, the container checks the
+// version that will consume it. Comparing two intended constants would miss
+// exactly the drift this guards — "the installed runtime isn't what the build
+// said it should be" (e.g. a lockfile-free `bun add` resolving a newer
+// release). Resolution is isolated here so the package-internals access lives
+// in one place.
+//
+// We resolve the package's EXPORTED entry and walk up to its package.json,
+// rather than `require('@huggingface/transformers/package.json')`: that subpath
+// is not in the package's `exports` map (only `node`/`default`), so a strict
+// Node-exports resolver throws ERR_PACKAGE_PATH_NOT_EXPORTED. The main entry IS
+// exported, and its package.json is the nearest one above the resolved file.
+export function getResolvedTransformersVersion(): string {
+  const require = createRequire(import.meta.url)
+  const entry = require.resolve('@huggingface/transformers')
+  const version = readNearestPackageVersion(dirname(entry))
+  if (version === null) {
+    throw new Error('could not resolve @huggingface/transformers version from its package.json')
+  }
+  return version
+}
+
+function readNearestPackageVersion(startDir: string): string | null {
+  const root = parsePath(startDir).root
+  let dir = startDir
+  for (;;) {
+    const version = readPackageNameVersion(join(dir, 'package.json'))
+    if (version !== null) return version
+    if (dir === root) return null
+    dir = dirname(dir)
+  }
+}
+
+// Only accept the @huggingface/transformers package.json, never a nested
+// dependency's: the resolved entry can sit under dist/, and an intermediate
+// dir could in theory carry an unrelated package.json. Match on name.
+function readPackageNameVersion(pkgPath: string): string | null {
+  let parsed: { name?: unknown; version?: unknown }
+  try {
+    parsed = JSON.parse(readFileSync(pkgPath, 'utf8')) as { name?: unknown; version?: unknown }
+  } catch {
+    return null
+  }
+  if (parsed.name !== '@huggingface/transformers') return null
+  if (typeof parsed.version !== 'string' || parsed.version.length === 0) return null
+  return parsed.version
+}

package/src/plugin/types.ts

@@ -182,6 +182,9 @@ export type SessionTurnStartEvent = {
   agentDir: string
   userPrompt: string
   origin?: SessionOrigin
+  // Mutable ref: plugin writes retrieval results here; server/router reads after hook returns.
+  // Only populated when vector.enabled and injection plan is index mode.
+  retrievalContext?: { results: string }
 }
 
 export type SessionTurnEndEvent = {