@yeaft/webchat-agent 1.0.607 → 1.0.610

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yeaft/webchat-agent",
-  "version": "1.0.607",
+  "version": "1.0.610",
   "description": "Remote worker agent for Yeaft Web Code Agent — connects the native Yeaft engine, CLI providers, and workbench tools",
   "main": "index.js",
   "type": "module",
@@ -72,7 +72,6 @@
     "dotenv": "^16.3.1",
     "express": "^4.22.2",
     "jsonwebtoken": "^9.0.2",
-    "mongodb": "^6.21.0",
     "multer": "^2.2.0",
     "nodemailer": "^9.0.3",
     "puppeteer-core": "24.41.0",

package/yeaft/llm/adapter.js

@@ -46,7 +46,7 @@ import { utf8PrefixWithinBytes } from '../utf8.js';
  * @typedef {{ type: 'tool_call', id: string, name: string, input: object }} ToolCallEvent
  * @typedef {{ type: 'provider_activity' }} ProviderActivityEvent Content-free progress on a non-empty hidden delta; watchdog only, never UI/history.
  * @typedef {{ type: 'provider_state', providerState: object, providerStateBytes: number }} ProviderStateEvent Internal only; never forward to UI/search.
- * @typedef {{ type: 'usage', inputTokens: number, outputTokens: number, reasoningTokens?: number, cacheReadTokens?: number, cacheWriteTokens?: number, cacheTokensAreIncludedInInput?: boolean }} UsageEvent
+ * @typedef {{ type: 'usage', inputTokens: number, outputTokens: number, reasoningTokens?: number, cacheReadTokens?: number, cacheWriteTokens?: number, cacheTokensAreIncludedInInput?: boolean, reportedTokenFields?: string[], usageIncomplete?: boolean }} UsageEvent
  * @typedef {{ type: 'stop', stopReason: 'end_turn' | 'tool_use' | 'max_tokens' }} StopEvent
  * @typedef {{ type: 'error', error: Error, retryable: boolean }} ErrorEvent
  *

package/yeaft/llm/anthropic.js

@@ -64,7 +64,7 @@ export function applyAnthropicThinking(body, model, effort, effortContext = {})
   }
 }
 
-import { ProviderStateError, createProviderContext, createProviderState, replayProviderState, providerStateBytes, applyAnthropicCaching, reasoningUsage } from './provider-state.js';
+import { ProviderStateError, createProviderContext, createProviderState, replayProviderState, providerStateBytes, applyAnthropicCaching, reasoningUsage, reportedUsageFields, hasUsageCounts } from './provider-state.js';
 
 const DEFAULT_BASE_URL = 'https://api.anthropic.com';
 const API_VERSION = '2023-06-01';
@@ -330,7 +330,7 @@ export class AnthropicAdapter extends LLMAdapter {
       const result = await response.json();
       // Account for consumed tokens even when the completed response cannot
       // safely publish tools. Budget consumers may abort on this usage event.
-      yield { type: 'usage', inputTokens: result.usage?.input_tokens || 0, outputTokens: result.usage?.output_tokens || 0,
+      yield { type: 'usage', reportedTokenFields: reportedUsageFields(result.usage, 'anthropic'), usageIncomplete: !hasUsageCounts(result.usage), inputTokens: result.usage?.input_tokens || 0, outputTokens: result.usage?.output_tokens || 0,
         cacheReadTokens: result.usage?.cache_read_input_tokens || 0, cacheWriteTokens: result.usage?.cache_creation_input_tokens || 0,
         ...reasoningUsage(result.usage, 'anthropic') };
       if (signal?.aborted) throw new LLMAbortError();
@@ -557,11 +557,13 @@ export class AnthropicAdapter extends LLMAdapter {
               }
               yield {
                 type: 'usage',
+                reportedTokenFields: reportedUsageFields(event.usage, 'anthropic'),
+                usageIncomplete: !hasUsageCounts(event.usage, ['output_tokens']),
                 ...reasoning,
                 inputTokens: 0, // Only in message_start
                 outputTokens,
               };
-            }
+            } else yield { type: 'usage', reportedTokenFields: [], usageIncomplete: true };
             if (signal?.aborted) throw new LLMAbortError();
             const stopReason = event.delta?.stop_reason;
             if (stopReason === 'max_tokens' && hasToolBlocks()) {
@@ -598,13 +600,15 @@ export class AnthropicAdapter extends LLMAdapter {
               cumulativeReasoningTokens = reasoning.reasoningTokens || 0;
               yield {
                 type: 'usage',
+                reportedTokenFields: reportedUsageFields(event.message.usage, 'anthropic'),
+                usageIncomplete: !hasUsageCounts(event.message.usage),
                 ...reasoning,
                 inputTokens: event.message.usage.input_tokens || 0,
                 outputTokens: cumulativeOutputTokens,
                 cacheReadTokens: event.message.usage.cache_read_input_tokens || 0,
                 cacheWriteTokens: event.message.usage.cache_creation_input_tokens || 0,
               };
-            }
+            } else yield { type: 'usage', reportedTokenFields: [], usageIncomplete: true };
           } else if (type === 'error') {
             stateFailed = true;
             yield {

package/yeaft/llm/openai-responses.js

@@ -52,7 +52,7 @@ import {
   mapEffortToOpenAIReasoning,
 } from '../models.js';
 
-import { createProviderContext, createProviderState, replayProviderState, providerStateBytes, applyResponsesContinuity, reasoningUsage } from './provider-state.js';
+import { createProviderContext, createProviderState, replayProviderState, providerStateBytes, applyResponsesContinuity, reasoningUsage, reportedUsageFields, hasUsageCounts } from './provider-state.js';
 
 const DEFAULT_BASE_URL = 'https://api.openai.com/v1';
 
@@ -369,7 +369,7 @@ export class OpenAIResponsesAdapter extends LLMAdapter {
         if (state) yield { type: 'provider_state', providerState: state, providerStateBytes: providerStateBytes(state) };
       }
       const usage = result.usage || {};
-      yield { type: 'usage', inputTokens: usage.input_tokens || 0, outputTokens: usage.output_tokens || 0,
+      yield { type: 'usage', reportedTokenFields: reportedUsageFields(result.usage, 'openai-responses'), usageIncomplete: !hasUsageCounts(result.usage), inputTokens: usage.input_tokens || 0, outputTokens: usage.output_tokens || 0,
         cacheReadTokens: usage.input_tokens_details?.cached_tokens || 0, cacheWriteTokens: 0,
         cacheTokensAreIncludedInInput: true,
               ...reasoningUsage(usage, 'openai-responses') };
@@ -528,6 +528,8 @@ export class OpenAIResponsesAdapter extends LLMAdapter {
             const usage = respObj.usage || {};
             yield {
               type: 'usage',
+              reportedTokenFields: reportedUsageFields(respObj.usage, 'openai-responses'),
+              usageIncomplete: !hasUsageCounts(respObj.usage),
               inputTokens: usage.input_tokens || 0,
               outputTokens: usage.output_tokens || 0,
               cacheReadTokens: usage.input_tokens_details?.cached_tokens || 0,

package/yeaft/llm/provider-state.js

@@ -241,3 +241,16 @@ export function reasoningUsage(usage, protocol) {
   const value = protocol === 'anthropic' ? usage?.output_tokens_details?.thinking_tokens : usage?.output_tokens_details?.reasoning_tokens;
   return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? { reasoningTokens: value } : {};
 }
+
+/** Which counters the provider actually reported, before legacy zero defaults. */
+export function hasUsageCounts(usage, fields = ['input_tokens', 'output_tokens']) {
+  return fields.every(key => Number.isSafeInteger(usage?.[key]) && usage[key] >= 0);
+}
+
+export function reportedUsageFields(usage, protocol) {
+  const counts = { inputTokens: usage?.input_tokens, outputTokens: usage?.output_tokens,
+    cacheReadTokens: protocol === 'anthropic' ? usage?.cache_read_input_tokens : usage?.input_tokens_details?.cached_tokens,
+    cacheWriteTokens: protocol === 'anthropic' ? usage?.cache_creation_input_tokens : undefined,
+    reasoningTokens: protocol === 'anthropic' ? usage?.output_tokens_details?.thinking_tokens : usage?.output_tokens_details?.reasoning_tokens };
+  return Object.keys(counts).filter(key => Number.isSafeInteger(counts[key]) && counts[key] >= 0);
+}

package/yeaft/person/bridge.js

@@ -2,8 +2,8 @@ import { createHash } from 'node:crypto';
 import ctx from '../../context.js';
 import { sendToServer } from '../../connection/buffer.js';
 
-/** Lazy Person transport. Only deployment-local environment supplies database credentials.
- * Storage is lazy and instance-local by default; browser messages cannot choose a backend.
+/** Lazy Person transport. SQLite storage belongs to this Agent instance;
+ * browser messages cannot choose a storage authority or instance directory.
  */
 export function createPersonBridge({
   context = ctx, send = sendToServer, env = process.env,
@@ -32,7 +32,6 @@ export function createPersonBridge({
         await send({ ...response, ok: false, errorCode: 'invalid_request', error: 'Digital person request requires authenticated ownership' });
         return true;
       }
-      const uri = env.YEAFT_PERSON_MONGODB_URI;
       const agentId = context.agentId || context.AGENT_ID;
       if (!agentId || !context.CONFIG?.yeaftDir) throw new Error('identity');
       // Server+Agent is a storage boundary; a re-registration must not reuse the old runtime.
@@ -45,10 +44,7 @@ export function createPersonBridge({
       identity = namespace;
       if (!servicePromise) {
         servicePromise = Promise.resolve().then(() => createService({
-          uri,
-          storage: env.YEAFT_PERSON_STORAGE,
           embedding: { enabled: env.YEAFT_PERSON_EMBEDDING !== 'off', allowDownload: env.YEAFT_PERSON_EMBEDDING_DOWNLOAD !== '0' },
-          dbName: env.YEAFT_PERSON_MONGODB_DB || 'yeaft_person',
           namespace,
           yeaftDir: context.CONFIG.yeaftDir,
           workDir: context.CONFIG.workDir,
@@ -78,7 +74,7 @@ export function createPersonBridge({
         TASK_CONTROL_UNAVAILABLE: 'Task control could not be confirmed; refresh before retrying',
         STALE: 'Digital person state changed; refresh and try again',
         IDEMPOTENCY_CONFLICT: 'This message identifier already belongs to a different request',
-        STORAGE_MISMATCH: 'The configured storage differs from the existing Person authority; do not switch without a verified migration',
+        STORAGE_MISMATCH: 'Existing digital person storage is not a valid SQLite binding; check instance storage before retrying',
         UNSUPPORTED: 'This capability is not available in this digital person version',
       };
       const known = Object.hasOwn(safeErrors, error?.code);

package/yeaft/person/capabilities.js

@@ -83,7 +83,7 @@ export function inspectCapabilities(created, { cursor, limit }, nativeToolIds =
     contract.evidence = item.evidence;
     entries.push(item);
   }
-  // IDs are ASCII identifiers. Binary ordering matches SQLite and Mongo simple collation.
+  // IDs are ASCII identifiers. Binary ordering matches SQLite.
   const matches = entries.filter(entry => cursor === null || entry.id > cursor)
     .sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
   return inspectionPage(matches, limit, 'id');

package/yeaft/person/contracts.js

@@ -5,7 +5,7 @@ export const LIMITS = Object.freeze({ inputBytes: 8192, outputBytes: 65536, cont
 const ERRORS = {
   INVALID_REQUEST: 'Invalid digital person request.', NOT_CONFIGURED: 'Digital person storage configuration is missing.',
   STORAGE_UNAVAILABLE: 'Digital person storage is unavailable. Check instance storage and database configuration.',
-  STORAGE_MISMATCH: 'Person storage is already bound to another backend; a verified migration is required.',
+  STORAGE_MISMATCH: 'Existing digital person storage is not a valid SQLite binding.',
   NOT_OPEN: 'Open your digital person first.', BUSY: 'The digital person is already active.',
   IDEMPOTENCY_CONFLICT: 'This clientMessageId was already used for a different request.',
   STALE: 'The activity no longer owns the current person revision.', INVALID_PROPOSAL: 'The model returned an invalid cognitive proposal.',

package/yeaft/person/provider.js

@@ -6,6 +6,7 @@ import { normalizeKnownProviderForRuntime } from '../llm/known-providers.js';
 import { normalizeEffort, resolveContextWindow, resolveMaxOutputTokens } from '../models.js';
 import { utf8PrefixWithinBytes } from '../utf8.js';
 import { bytes, digest, fail, LIMITS, PersonError } from './contracts.js';
+import { addUsage } from './turn-diagnostics.js';
 
 export const MODEL_LIMITS = Object.freeze({ candidates: 8, available: 100 });
 export function validateModelCandidates(refs) {
@@ -92,7 +93,7 @@ export async function createPersonProvider({ yeaftDir, config: suppliedConfig, a
     const explicitImages = m.supportsImages ?? rawModel?.supportsImages ?? rawProvider?.supportsImages;
     const protocol = routedModel?.protocol || routedProvider?.protocol || inferProtocolFromModelId(m.id) || 'openai-responses';
     const imageBudget = !routedProvider || explicitImages === false ? null : imageInputBudget(m.id, protocol);
-    return { id: m.ref || m.id, efforts, maxOutput, supportsImages: imageBudget !== null, imageBudget,
+    return { id: m.ref || m.id, efforts, maxOutput, usageCacheIncluded: protocol === 'anthropic' ? false : undefined, supportsImages: imageBudget !== null, imageBudget,
       contextWindow: Math.floor(resolveContextWindow(m.id, { ...config, modelInfo: m })) };
   }).filter(m => typeof m.id === 'string' && m.id.length <= 256 && m.contextWindow > m.maxOutput + 1024 && m.maxOutput >= 256);
   safeModels.sort((a, b) => Number(b.id === agentDefaultModel) - Number(a.id === agentDefaultModel));
@@ -147,8 +148,7 @@ export async function collectOutput(adapter, params, onEffort) {
       else if (event.type === 'error') fail('PROVIDER_FAILED');
       else if (event.type === 'tool_call') fail('INVALID_PROPOSAL');
       else if (event.type === 'usage') {
-        usage = {};
-        for (const key of ['inputTokens', 'outputTokens', 'reasoningTokens', 'cacheReadTokens', 'cacheWriteTokens']) if (Number.isFinite(event[key]) && event[key] >= 0) usage[key] = event[key];
+        usage = addUsage(usage, event, params.usageCacheIncluded);
       }
       // Hidden thinking, signatures, opaque provider state and raw HTTP exchanges are deliberately not archived.
     }

package/yeaft/person/runtime.js

@@ -147,8 +147,8 @@ export class PersonRuntime {
     this.running = new Map(); this.pendingCancellations = new Map(); this.workerId = randomUUID(); this.closed = false;
   }
   tasks() {
-    // Construction/status/open do not touch task storage. Legacy direct Mongo
-    // embeddings without an instance root retain foreground-only host support.
+    // Construction/status/open do not touch task storage. An instance root is
+    // required before creating the durable task host.
     if (!this.toolOptions.yeaftDir) return null;
     return this.taskHost ??= new PersonTaskHost({ ...this.toolOptions, namespace: this.namespace });
   }
@@ -259,6 +259,7 @@ export class PersonRuntime {
           }) };
           output = await collectOutput(observingAdapter, {
             model: selection.model, effort: selection.effort ?? undefined, effortSource: 'auto',
+            usageCacheIncluded: provider.catalog.find(model => model.id === selection.model)?.usageCacheIncluded,
             system: context.system, messages: context.messages, maxTokens: context.maxTokens, signal,
           }, decision => {
             effective.effort = decision.effective; effective.effortObserved = true;

package/yeaft/person/service.js

@@ -1,46 +1,42 @@
-import { MongoPersonRepository } from './repository.js';
 import { SqlitePersonRepository } from './sqlite-repository.js';
 import { LocalPersonMemory } from './local-memory.js';
-import { selectPersonStorage, bindPersonStorage } from './storage.js';
+import { ensurePersonStorage } from './sqlite-storage.js';
 import { PersonRuntime } from './runtime.js';
 import { allowedNativeToolIds } from './native-tools.js';
 import { loadConfig } from '../config.js';
 import { validateFiles } from './attachments.js';
 import { createPersonProvider, resolveAgentDefaultModel, selectPersonModels, validateDefaultModel, validateModelCandidates } from './provider.js';
 import { fail, identifier, LIMITS, object, page, personTaskRequest, safeError, text } from './contracts.js';
+import { turnsPage } from './turn-diagnostics.js';
 import { inspectRequest, personName, searchRequest } from './inspection.js';
 
 /**
  * One durable Person per (namespace, authenticated ownerId). The transport MUST
- * supply authenticated ownerId, never accept it from a browser payload. URI/provider
+ * supply authenticated ownerId, never accept it from a browser payload. Provider
  * secrets stay inside this Agent. Constructor and status never initiate model calls.
- * Native provider configuration is read from yeaftDir only (no Session initialization).
- * SQLite is the local default; an existing Mongo URI retains Mongo. No authority fallback.
+ * SQLite storage and native provider configuration belong to yeaftDir only
+ * (no Session initialization or alternate storage authority).
  */
 export function createPersonService(options = {}) {
-  const { uri, dbName = 'yeaft_person', namespace = 'default', yeaftDir, workDir, MongoClient, config, adapter, allowedModels } = options;
+  const { namespace = 'default', yeaftDir, workDir, config, adapter, allowedModels } = options;
   identifier(namespace);
-  if (typeof dbName !== 'string' || !/^[a-zA-Z0-9_-]{1,63}$/.test(dbName)) fail('INVALID_REQUEST');
-  if (uri != null && typeof uri !== 'string') fail('INVALID_REQUEST');
-  const { storage, configured } = selectPersonStorage({ ...options, yeaftDir });
+  const configured = typeof yeaftDir === 'string' && Boolean(yeaftDir.trim());
   const calls = options.maxCalls ?? LIMITS.calls;
   const timeoutMs = options.timeoutMs ?? LIMITS.timeoutMs;
   const leaseMs = options.leaseMs ?? LIMITS.leaseMs;
   if (!Number.isInteger(calls) || calls < 1 || calls > 32 || !Number.isInteger(timeoutMs) || timeoutMs < 100 || timeoutMs > 300000 ||
       !Number.isInteger(leaseMs) || leaseMs < 300 || leaseMs > 60000) fail('INVALID_REQUEST');
   if (allowedModels != null && (!Array.isArray(allowedModels) || !allowedModels.length || allowedModels.some(m => typeof m !== 'string'))) fail('INVALID_REQUEST');
-  const repository = !configured ? null : storage === 'mongodb'
-    ? new MongoPersonRepository({ uri, dbName, namespace, MongoClient, leaseMs })
-    : new SqlitePersonRepository({ yeaftDir, namespace, leaseMs });
+  const repository = configured ? new SqlitePersonRepository({ yeaftDir, namespace, leaseMs }) : null;
   const initialize = repository?.init.bind(repository);
   let binding;
   if (repository) repository.init = async () => {
-    if (!binding) binding = bindPersonStorage(yeaftDir, namespace, storage).catch(error => { binding = null; throw error; });
+    if (!binding) binding = ensurePersonStorage(yeaftDir, namespace).catch(error => { binding = null; throw error; });
     await binding;
     return initialize();
   };
   const literalRecall = repository?.recall.bind(repository);
-  const memory = repository && storage === 'sqlite' ? new LocalPersonMemory({
+  const memory = repository ? new LocalPersonMemory({
     repository, literalRecall, yeaftDir, namespace, embedding: options.embedding,
   }) : null;
   if (memory) repository.recall = (ownerId, args = {}, { signal } = {}) => args.query?.trim()
@@ -58,7 +54,7 @@ export function createPersonService(options = {}) {
       object(payload, []);
       let agentDefaultModel = null;
       try { agentDefaultModel = resolveAgentDefaultModel(config ?? loadConfig({ dir: yeaftDir })); } catch { /* Invalid/missing native config. */ }
-      const status = { renameSupported: true, defaultModelSupported: true, configured, storage, modelReady: false,
+      const status = { renameSupported: true, defaultModelSupported: true, configured, storage: 'sqlite', modelReady: false,
         defaultModel: null, agentDefaultModel, modelCandidates: [], effectiveModelCandidates: [], effectiveDefaultModel: null };
       if (!configured) return { ...status, reason: 'Digital person storage configuration is missing.', storageReady: false };
       try { await repository.init(); }
@@ -130,6 +126,7 @@ export function createPersonService(options = {}) {
       }
       case 'traces': await repository.recover(ownerId); return repository.list(ownerId, 'traces', page(payload));
       case 'messages': return repository.list(ownerId, 'messages', page(payload));
+      case 'turns': return repository.turns(ownerId, turnsPage(payload));
       // These reads deliberately bypass recover(), Recall and the runtime/provider.
       case 'inspect': {
         const request = inspectRequest(payload);

package/yeaft/person/sqlite-repository.js

@@ -105,6 +105,7 @@ export class SqlitePersonRepository {
   async cancel(ownerId, episodeId) { return this.request('cancel', [ownerId, episodeId]); }
   async settings(ownerId, settings, expectedControlVersion) { return this.request('settings', [ownerId, settings, expectedControlVersion]); }
   async list(ownerId, collection, options, filter) { return this.request('list', [ownerId, collection, options, filter]); }
+  async turns(ownerId, options) { return this.request('turns', [ownerId, options]); }
   async snapshot(ownerId) { return this.request('snapshot', [ownerId]); }
   async inspect(ownerId, options, nativeToolIds) { return this.request('inspect', [ownerId, options, nativeToolIds]); }
   async search(ownerId, options) { return this.request('search', [ownerId, options]); }

package/yeaft/person/sqlite-schema.js

@@ -75,6 +75,8 @@ CREATE TABLE IF NOT EXISTS traces (
   PRIMARY KEY(namespace, ownerId, personId, id), UNIQUE(namespace, ownerId, personId, seq),
   FOREIGN KEY(namespace, ownerId, personId) REFERENCES persons(namespace, ownerId, personId)
 ) STRICT;
+CREATE INDEX IF NOT EXISTS traces_turn_metadata ON traces(namespace, ownerId, personId,
+  json_extract(record, '$.episodeId'), seq);
 CREATE INDEX IF NOT EXISTS traces_call_output ON traces(namespace, ownerId, personId,
   json_extract(record, '$.episodeId'), json_extract(record, '$.callId'))
   WHERE json_extract(record, '$.kind') = 'call_output';

package/yeaft/person/sqlite-storage.js

@@ -0,0 +1,24 @@
+import { mkdir, readFile, writeFile, link, unlink } from 'node:fs/promises';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { digest, fail } from './contracts.js';
+
+/** Preserve existing instance bindings without silently creating a new authority.
+ * SQLite is the only supported storage; this marker is not a backend selector.
+ */
+export async function ensurePersonStorage(yeaftDir, namespace) {
+  const directory = join(yeaftDir, 'person');
+  await mkdir(directory, { recursive: true, mode: 0o700 });
+  const path = join(directory, `storage-${digest(namespace)}.json`);
+  const temporary = `${path}.${randomUUID()}.tmp`;
+  await writeFile(temporary, JSON.stringify({ version: 1, storage: 'sqlite' }), { flag: 'wx', mode: 0o600 });
+  try {
+    // A fully written inode is linked atomically; competing openers never read partial JSON.
+    await link(temporary, path);
+  } catch (error) {
+    if (error.code !== 'EEXIST') throw error;
+    let binding;
+    try { binding = JSON.parse(await readFile(path, 'utf8')); } catch { fail('STORAGE_MISMATCH'); }
+    if (!binding || binding.version !== 1 || binding.storage !== 'sqlite') fail('STORAGE_MISMATCH');
+  } finally { await unlink(temporary).catch(() => {}); }
+}

package/yeaft/person/sqlite-store.js

@@ -9,6 +9,7 @@ import { SCHEMA, TABLES } from './sqlite-schema.js';
 import { attachmentMetadata, attachmentRequestHash, validateFiles } from './attachments.js';
 import { capabilityExperienceView, recordCapabilityExperience } from './capability-experience.js';
 import { conceptView, inspectionPage, inspectRequest, messageView, personName, searchRequest, settingsView, stateView } from './inspection.js';
+import { TOKEN_FIELDS, turnsPage, turnView } from './turn-diagnostics.js';
 import { inspectCapabilities } from './capabilities.js';
 
 const SCOPE = 'namespace = ? AND ownerId = ? AND personId = ?';
@@ -44,11 +45,14 @@ const publicOutput = (output, failed) => {
   if (usage) for (const key of ['inputTokens', 'outputTokens', 'reasoningTokens', 'cacheReadTokens', 'cacheWriteTokens']) {
     if (Number.isFinite(output.usage[key]) && output.usage[key] >= 0) usage[key] = output.usage[key];
   }
+  if (usage && output.usage.accountingVersion === 1) usage.accountingVersion = 1;
+  if (usage && output.usage.accountingIncomplete === true) usage.accountingIncomplete = true;
+  if (usage && typeof output.usage.cacheTokensAreIncludedInInput === 'boolean') usage.cacheTokensAreIncludedInInput = output.usage.cacheTokensAreIncludedInInput;
   const stopReason = typeof output.stopReason === 'string' && bytes(output.stopReason) <= 128 ? output.stopReason : null;
   return failed ? { text: output.text, retainedBytes, observedBytes, complete: false, accepted: false, availability: 'captured', usage, stopReason }
     : { text: output.text, bytes: retainedBytes, complete: true, usage, stopReason };
 };
-const READS = new Set(['receipt', 'inspect', 'search', 'getPerson', 'context', 'recall', 'list', 'searchChanges', 'resolveMemories', 'createdCapabilities', 'episodeAttachments']);
+const READS = new Set(['receipt', 'turns', 'inspect', 'search', 'getPerson', 'context', 'recall', 'list', 'searchChanges', 'resolveMemories', 'createdCapabilities', 'episodeAttachments']);
 const WRITES = new Set(['open', 'recover', 'admit', 'heartbeat', 'append', 'startCall', 'finalizeCall', 'startCapability', 'finalizeCapability', 'commit', 'finish', 'cancel', 'settings', 'snapshot', 'saveCreatedCapability']);
 const memoryKind = kind => { if (!['messages', 'concepts'].includes(kind)) fail('INVALID_REQUEST'); return kind; };
 const boundedLimit = (limit, max = 100) => { if (!Number.isSafeInteger(limit) || limit < 1 || limit > max) fail('INVALID_REQUEST'); return limit; };
@@ -445,12 +449,41 @@ export class SqlitePersonStore {
       ' AND (? IS NULL OR seq < ?) AND instr(text, ?) > 0 ORDER BY seq DESC LIMIT ?', [cursor, cursor, query.toLowerCase(), limit + 1]);
     return inspectionPage(records, limit, 'seq', messageView);
   }
+  turns(ownerId, options = {}) {
+    const { cursor, limit } = turnsPage(options);
+    const scope = this.scope(ownerId);
+    if (!this.sql(`SELECT 1 FROM persons WHERE ${SCOPE}`).get(...scopeValues(scope))) fail('NOT_OPEN');
+    const project = fields => `json_object(${Object.entries(fields).map(([key, path]) => `'${key}', json_extract(record, '$.${path}')`).join(', ')})`;
+    const episodes = this.sql(`SELECT ${project({ id: 'id', seq: 'inputWatermark', kind: 'kind', status: 'status', createdAt: 'createdAt', endedAt: 'endedAt', terminalCode: 'terminalCode', calls: 'budget.calls', timeoutMs: 'budget.timeoutMs' })} AS metadata
+      FROM episodes WHERE ${SCOPE} AND (? IS NULL OR inputWatermark < ?) ORDER BY inputWatermark DESC LIMIT ?`)
+      .all(...scopeValues(scope), cursor, cursor, limit + 1).map(row => JSON.parse(row.metadata));
+    const fields = { kind: 'kind', callId: 'callId', callIndex: 'callIndex', createdAt: 'createdAt',
+      requestedModel: 'requested.model', requestedEffort: 'requested.effort', effectiveEffort: 'effective.effort', effortObserved: 'effective.effortObserved',
+      selectionOrigin: 'selectionOrigin', reason: 'reason', code: 'code', terminalCode: 'terminalCode', outcome: 'outcome',
+      contextBytes: 'manifest.contextBytes', contextBudgetBytes: 'manifest.contextBudgetBytes', outputTokensReserved: 'manifest.outputTokensReserved' };
+    const usage = `json_object(${TOKEN_FIELDS.map(key => `'${key}', json_extract(record, '$.output.usage.${key}')`).join(', ')},
+      'accountingVersion', json_extract(record, '$.output.usage.accountingVersion'),
+      'accountingIncomplete', json(CASE json_extract(record, '$.output.usage.accountingIncomplete') WHEN 1 THEN 'true' ELSE 'false' END),
+      'cacheTokensAreIncludedInInput', json(CASE json_extract(record, '$.output.usage.cacheTokensAreIncludedInInput') WHEN 1 THEN 'true' WHEN 0 THEN 'false' ELSE 'null' END))`;
+    const metadata = `${project(fields).slice(0, -1)}, 'capabilityId', COALESCE(json_extract(record, '$.capability.id'), json_extract(record, '$.capabilityId')),
+      'usage', ${usage})`;
+    const items = episodes.slice(0, limit).map(episode => {
+      const events = this.sql(`SELECT ${metadata} AS metadata FROM traces WHERE ${SCOPE}
+        AND json_extract(record, '$.episodeId') = ? AND json_extract(record, '$.kind') IN
+        ('call_started', 'call_output', 'call_failed', 'proposal_rejected', 'capability_started', 'capability_result', 'capability_failed', 'capability_finalized') ORDER BY seq ASC`)
+        .all(...scopeValues(scope), episode.id).map(row => {
+          const event = JSON.parse(row.metadata); event.effortObserved = event.effortObserved === 1; return event;
+        });
+      return turnView(episode, events);
+    });
+    return { items, nextCursor: episodes.length > limit ? items.at(-1).seq : null };
+  }
   list(ownerId, collection, { cursor = null, limit = 20 } = {}, filter = {}) {
     if (!['messages', 'traces'].includes(collection)) fail('INVALID_REQUEST');
     this.getPerson(ownerId); boundedLimit(limit);
-    if (Object.keys(filter).some(k => k !== 'text') || (filter.text && (typeof filter.text.$regex !== 'string' || filter.text.$options !== 'i'))) fail('INVALID_REQUEST');
-    // Compatibility for Mongo's literal recall filter only; arbitrary selectors are forbidden.
-    const query = filter.text?.$regex?.replace(/\\([.*+?^${}()|[\]\\])/g, '$1') ?? '';
+    if (Object.keys(filter).some(k => k !== 'query')) fail('INVALID_REQUEST');
+    const query = filter.query ?? '';
+    text(query, LIMITS.inputBytes, true);
     if (query && collection !== 'messages') fail('INVALID_REQUEST');
     let clause = '', params = [];
     if (cursor != null) { clause += ' AND seq < ?'; params.push(sequence(cursor)); }
@@ -460,7 +493,7 @@ export class SqlitePersonStore {
   }
   recall(ownerId, { kind = 'messages', query = '', cursor = null, limit = 5 } = {}) {
     memoryKind(kind); text(query, LIMITS.inputBytes, true); boundedLimit(limit);
-    if (kind === 'messages') return this.list(ownerId, kind, { cursor, limit }, query ? { text: { $regex: query.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), $options: 'i' } } : {});
+    if (kind === 'messages') return this.list(ownerId, kind, { cursor, limit }, { query });
     this.getPerson(ownerId);
     if (cursor != null) text(cursor, 128);
     const docs = this.rows('concepts', this.scope(ownerId), ' AND (? IS NULL OR id > ?) AND instr(statement, ?) > 0 ORDER BY id ASC LIMIT ?', [cursor, cursor, query.toLowerCase(), limit + 1]);

package/yeaft/person/task-host.js

@@ -61,7 +61,7 @@ function privatePath(root, path) {
 // expose native command fallbacks; redact common sensitive forms before capping.
 function summary(value, maxBytes = 512) {
   const clean = String(value ?? '')
-    .replace(/https?:\/\/\S+|mongodb(?:\+srv)?:\/\/\S+/gi, '[url]')
+    .replace(/\b[a-z][a-z\d+.-]*:\/\/\S+/gi, '[url]')
     .replace(/(?:bearer\s+|(?:api[_-]?key|password|secret|token)\s*[:=]\s*)\S+/gi, '[redacted]')
     .replace(/\b(?:sk-[\w-]+|gh[pousr]_[\w]+|github_pat_[\w]+)\b/g, '[redacted]')
     .replace(/(?:\/[\w.@~+-]+)+(?:\/[^\s]*)?|(?:~|\.\.?|[A-Za-z]:)[\\/][^\s]+/g, '[path]')

package/yeaft/person/turn-diagnostics.js

@@ -0,0 +1,89 @@
+import { fail, object } from './contracts.js';
+
+export const TOKEN_FIELDS = Object.freeze(['inputTokens', 'outputTokens', 'reasoningTokens', 'cacheReadTokens', 'cacheWriteTokens']);
+const numeric = value => Number.isSafeInteger(value) && value >= 0;
+const token = value => numeric(value) ? value : null;
+const string = value => typeof value === 'string' ? value : null;
+
+/** Turn cursor is an exclusive numeric episode watermark, never a trace offset. */
+export function turnsPage(payload = {}) {
+  object(payload, ['cursor', 'limit'], []);
+  const { cursor = null, limit = 20 } = payload;
+  if (!Number.isInteger(limit) || limit < 1 || limit > 20 ||
+      (cursor !== null && (!Number.isSafeInteger(cursor) || cursor < 1))) fail('INVALID_REQUEST');
+  return { cursor, limit };
+}
+
+/** Adapter usage events are additive. Keep unknown fields unknown, including cache semantics. */
+export function addUsage(usage, event, inclusion) {
+  const result = { ...usage, accountingVersion: 1 };
+  if (event.usageIncomplete === true) result.accountingIncomplete = true;
+  for (const key of TOKEN_FIELDS) if ((!Array.isArray(event.reportedTokenFields) || event.reportedTokenFields.includes(key)) && numeric(event[key])) result[key] = (result[key] ?? 0) + event[key];
+  const flag = typeof event.cacheTokensAreIncludedInInput === 'boolean' ? event.cacheTokensAreIncludedInInput : inclusion;
+  if (typeof flag === 'boolean') {
+    if (typeof result.cacheTokensAreIncludedInInput === 'boolean' && result.cacheTokensAreIncludedInInput !== flag) result.cacheTokensAreIncludedInInput = null;
+    else if (result.cacheTokensAreIncludedInInput !== null) result.cacheTokensAreIncludedInInput = flag;
+  }
+  return result;
+}
+
+export function callUsage(raw, completed) {
+  const usage = Object.fromEntries(TOKEN_FIELDS.map(key => [key, token(raw?.[key])]));
+  const reported = TOKEN_FIELDS.some(key => usage[key] !== null);
+  const caches = (usage.cacheReadTokens ?? 0) + (usage.cacheWriteTokens ?? 0);
+  // Historical traces dropped the flag. Nonzero cache counts without it are ambiguous.
+  usage.inputTotalTokens = raw?.accountingVersion !== 1 || raw.accountingIncomplete === true || usage.inputTokens === null || (caches > 0 && typeof raw?.cacheTokensAreIncludedInInput !== 'boolean') ? null
+    : usage.inputTokens + (raw?.cacheTokensAreIncludedInInput === false ? caches : 0);
+  usage.totalTokens = usage.inputTotalTokens === null || usage.outputTokens === null ? null : usage.inputTotalTokens + usage.outputTokens;
+  // Reasoning is a subset of output, not an additional billable output quantity.
+  return { ...usage, reportedCalls: Number(reported), missingCalls: Number(!reported), complete: completed && usage.totalTokens !== null };
+}
+
+function sumUsage(calls, terminal) {
+  const fields = [...TOKEN_FIELDS, 'inputTotalTokens', 'totalTokens'];
+  const usage = Object.fromEntries(fields.map(key => {
+    const known = calls.map(call => call.usage[key]).filter(value => value !== null);
+    // Raw metrics sum reported values even for partial calls. Exact totals require every call.
+    return [key, !calls.length ? 0 : (key.endsWith('TotalTokens') || key === 'totalTokens') && known.length !== calls.length ? null
+      : known.length ? known.reduce((sum, value) => sum + value, 0) : null];
+  }));
+  return { ...usage, reportedCalls: calls.reduce((sum, call) => sum + call.usage.reportedCalls, 0),
+    missingCalls: calls.reduce((sum, call) => sum + call.usage.missingCalls, 0), complete: terminal && calls.every(call => call.usage.complete) };
+}
+
+/** Only metadata supplied by SQLite's explicit projection enters this view. */
+export function turnView(episode, events) {
+  const calls = new Map();
+  for (const event of events) {
+    if (event.kind === 'call_started') {
+      calls.set(event.callId, { callId: event.callId, index: numeric(event.callIndex) ? event.callIndex + 1 : calls.size + 1,
+        status: 'running', requested: { model: string(event.requestedModel), effort: string(event.requestedEffort) },
+        // Native router dispatches the configured ref (only credential refresh can retry).
+        // It does not expose the response model: do not label configured intent as observed reality.
+        dispatched: { model: string(event.requestedModel) }, effective: { model: null, effort: null },
+        selectionOrigin: string(event.selectionOrigin), reason: string(event.reason), createdAt: event.createdAt, endedAt: null, code: null,
+        contextBytes: token(event.contextBytes), contextBudgetBytes: token(event.contextBudgetBytes), outputTokensReserved: token(event.outputTokensReserved),
+        usage: callUsage(null, false) });
+      continue;
+    }
+    const call = calls.get(event.callId);
+    if (!call) continue;
+    if (event.kind === 'call_output' || event.kind === 'call_failed') {
+      call.status = event.kind === 'call_output' ? 'completed' : ['CANCELLED', 'INTERRUPTED'].includes(event.code) ? event.code.toLowerCase() : 'failed';
+      call.endedAt = event.createdAt; call.code = string(event.code);
+      call.effective.effort = event.effortObserved === true ? string(event.effectiveEffort) : null;
+      call.usage = callUsage(event.usage, event.kind === 'call_output');
+    } else if (event.kind === 'proposal_rejected') {
+      call.status = 'rejected'; call.code = string(event.code);
+    } else if (event.kind === 'capability_started') {
+      call.capability = { id: string(event.capabilityId), status: 'running', code: null };
+    } else if (['capability_result', 'capability_failed', 'capability_finalized'].includes(event.kind)) {
+      call.capability = { id: string(event.capabilityId) ?? call.capability?.id ?? null,
+        status: (event.outcome ?? event.kind) === 'capability_failed' ? 'failed' : 'completed', code: string(event.code) ?? string(event.terminalCode) };
+    }
+  }
+  const items = [...calls.values()].sort((a, b) => a.index - b.index);
+  return { id: episode.id, seq: episode.seq, kind: episode.kind, status: episode.status, createdAt: episode.createdAt,
+    endedAt: episode.endedAt, terminalCode: episode.terminalCode, budget: { calls: token(episode.calls), timeoutMs: token(episode.timeoutMs) },
+    models: [...new Set(items.map(call => call.dispatched.model).filter(Boolean))], usage: sumUsage(items, episode.status !== 'running'), calls: items };
+}