@yeaft/webchat-agent 1.0.608 → 1.0.611

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yeaft/webchat-agent",
-  "version": "1.0.608",
+  "version": "1.0.611",
   "description": "Remote worker agent for Yeaft Web Code Agent — connects the native Yeaft engine, CLI providers, and workbench tools",
   "main": "index.js",
   "type": "module",

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/contracts.js

@@ -1,7 +1,10 @@
 import { createHash } from 'node:crypto';
 
 // 只允许应用层显式产物；不要求或保存 provider 的隐藏推理。
-export const LIMITS = Object.freeze({ inputBytes: 8192, outputBytes: 65536, contextBytes: 65536, calls: 16, timeoutMs: 120000, leaseMs: 15000 });
+export const LIMITS = Object.freeze({ inputBytes: 8192, outputBytes: 65536, contextBytes: 65536, calls: 16, leaseMs: 15000 });
+// Feedback cadence is not an execution deadline. Slow providers/tools remain cancellable.
+export const FEEDBACK = Object.freeze({ minMs: 30000, maxMs: 60000 });
+export const FEEDBACK_INSTRUCTIONS = "feedback describes user-visible communication, not a deadline. After about 30 seconds without a substantive reply, use reply for a concise, useful progress update at a natural execution boundary; aim for 30\u201360 seconds according to actual progress. Explain verified findings, limitations and what you are checking next, in the user's language. Do not repeat feedback.lastReply, invent progress, expose internal deliberation/decision/selfCheck, or claim an unexecuted tool succeeded. If no meaningful update exists, reply:null is appropriate; the host shows an honest waiting status around 60 seconds without interrupting the current request. With next non-null, a validated reply may be published as progress independently of cognitive state, and retained on cancellation/failure. Only next:null commits cognition and supplies the final reply. Do not call a tool or an extra model just to report progress. Each final reply should stand on its own and note unfinished work.";
 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.',

package/yeaft/person/inspection.js

@@ -20,7 +20,7 @@ export function personName(value) {
 const pick = (value, keys) => value == null ? null : Object.fromEntries(keys.filter(key => Object.hasOwn(value, key)).map(key => [key, value[key]]));
 export const settingsView = value => pick(value, ['autonomyEnabled', 'modelCandidates', 'defaultModel']);
 export function messageView(value) {
-  const result = pick(value, ['id', 'schemaVersion', 'revision', 'seq', 'episodeId', 'clientMessageId', 'role', 'text', 'createdAt']);
+  const result = pick(value, ['id', 'schemaVersion', 'revision', 'seq', 'episodeId', 'clientMessageId', 'callId', 'replyKind', 'role', 'text', 'createdAt']);
   if (result && Array.isArray(value.attachments)) result.attachments = value.attachments.slice(0, 4)
     .map(file => pick(file, ['id', 'name', 'mimeType', 'size', 'sha256', 'kind']));
   return result;

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

@@ -1,16 +1,17 @@
 import { createPersonToolHost, createPersonNativeRegistry, isNativeTool, projectNativeResult } from './native-tools.js';
 import { PersonTaskHost } from './task-host.js';
 import { randomUUID } from 'node:crypto';
+import { utf8PrefixWithinBytes } from '../utf8.js';
 import { CAPABILITY_MAP, CAPABILITY_LIMITS, foundationCapabilities, PersonCapabilities, catalogRevision as capabilityCatalogRevision } from './capabilities.js';
 import { attachmentMetadata } from './attachments.js';
 import { abortable, collectOutput } from './provider.js';
-import { bytes, digest, fail, LIMITS, PersonError, PROPOSAL_INSTRUCTIONS, reportedLineage, safeError, validateProposal, validateSelection } from './contracts.js';
+import { bytes, digest, fail, FEEDBACK, FEEDBACK_INSTRUCTIONS, LIMITS, PersonError, PROPOSAL_INSTRUCTIONS, reportedLineage, safeError, validateProposal, validateSelection } from './contracts.js';
 
 const messageRef = m => `message:${m.id}:${m.revision}`;
 const conceptRef = c => `concept:${c.id}:${c.revision}`;
 
 /** Assemble bounded request copies. Omitting a record never deletes or truncates its durable original. */
-export function assembleContext({ snapshot, episode, provider, selection, previous, capabilityResult, remainingCalls, taskEvidence, dependencyRefs = [], activeCapabilities = foundationCapabilities(), capabilityMap = CAPABILITY_MAP, attachments = [], environment }) {
+export function assembleContext({ snapshot, episode, provider, selection, previous, capabilityResult, remainingCalls, taskEvidence, dependencyRefs = [], activeCapabilities = foundationCapabilities(), capabilityMap = CAPABILITY_MAP, attachments = [], environment, feedback }) {
   const model = validateSelection(selection, provider.catalog);
   // UTF-8 bytes is a conservative text-token bound; reserve explicit envelope/output overhead.
   const images = attachments.filter(file => file.kind === 'image');
@@ -74,6 +75,16 @@ export function assembleContext({ snapshot, episode, provider, selection, previo
       omittedCapabilities.push({ id: contract.id, reason: 'context-budget', inspect: 'catalog.view' });
     }
   }
+  // Feedback is a request-only hint, never grounds to fail the next call.
+  // Keep durable replies intact; avoid duplicating up to 8 KiB from previousProposal.
+  if (feedback) {
+    const preview = utf8PrefixWithinBytes(feedback.lastReply ?? '', 512).text;
+    context.feedback = { ...feedback, instructions: FEEDBACK_INSTRUCTIONS, lastReply: preview || null,
+      lastReplyTruncated: bytes(feedback.lastReply ?? '') > bytes(preview) };
+    if (!fits()) { context.feedback.lastReply = null; context.feedback.lastReplyTruncated = Boolean(feedback.lastReply); }
+    if (!fits()) delete context.feedback.instructions;
+    if (!fits()) delete context.feedback;
+  }
   const add = (field, item, ref) => {
     if (renderedRefs.has(ref)) return;
     const inherited = sourceRefs.has(ref);
@@ -189,8 +200,8 @@ export class PersonRuntime {
   isOwnerRunning(ownerId) { return this.pendingCancellations.has(ownerId) || [...this.running.values()].some(job => job.episode.ownerId === ownerId); }
   async run(episode, controller) {
     const { signal } = controller;
-    const timeout = setTimeout(() => controller.abort(new PersonError('TIMEOUT')), episode.budget.timeoutMs);
-    timeout.unref?.();
+    let lastReplyAt = new Date(episode.createdAt).getTime() || Date.now();
+    let lastReply = null;
     let heartbeatRunning = false;
     const heartbeat = setInterval(async () => {
       if (heartbeatRunning || signal.aborted) return;
@@ -198,7 +209,7 @@ export class PersonRuntime {
       try { await this.repository.heartbeat(episode); }
       catch (error) { controller.abort(safeError(error)); }
       finally { heartbeatRunning = false; }
-    }, Math.max(100, Math.floor(this.repository.leaseMs / 3)));
+    }, Math.max(100, Math.min(5000, Math.floor(this.repository.leaseMs / 3))));
     heartbeat.unref?.();
     try {
       const provider = await abortable(this.getProvider(episode.modelCandidates ?? [], episode.defaultModel ?? null), signal);
@@ -232,7 +243,11 @@ export class PersonRuntime {
       for (let index = 0; index < episode.budget.calls; index++) {
         signal.throwIfAborted();
         const callId = randomUUID();
-        const context = assembleContext({ snapshot, episode, provider, selection, previous, capabilityResult, dependencyRefs, remainingCalls: episode.budget.calls - index, taskEvidence: projectTaskEvidence(this.tasks()?.snapshot(episode.ownerId)), attachments, activeCapabilities: capabilities.context(), capabilityMap: capabilities.catalog(), environment: toolHost.environment });
+        const context = assembleContext({ snapshot, episode, provider, selection, previous, capabilityResult, dependencyRefs, remainingCalls: episode.budget.calls - index, taskEvidence: projectTaskEvidence(this.tasks()?.snapshot(episode.ownerId)), attachments, activeCapabilities: capabilities.context(), capabilityMap: capabilities.catalog(), environment: toolHost.environment, feedback: {
+          minIntervalMs: FEEDBACK.minMs, maxIntervalMs: FEEDBACK.maxMs,
+          elapsedSinceReplyMs: Math.max(0, Date.now() - lastReplyAt),
+          due: Date.now() - lastReplyAt >= FEEDBACK.minMs, lastReply,
+        } });
         capabilities.activate(context.activeCapabilities);
         dependencyRefs = context.manifest.inputDependencyRefs;
         for (const [id, concept] of context.concepts) readConcepts.set(id, concept);
@@ -259,6 +274,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;
@@ -288,6 +304,11 @@ export class PersonRuntime {
           await this.repository.commit(episode, proposal, selection, callId, new Map(proposal.concepts.map(c => [c.id, c.epistemicState === 'reported' ? reportedLineage(c, readSources) : []])));
           return;
         }
+        if (proposal.reply) {
+          signal.throwIfAborted();
+          const published = await this.repository.publishProgress(episode, { callId, reply: proposal.reply });
+          if (published) { lastReply = published.text; lastReplyAt = new Date(published.createdAt).getTime(); }
+        }
         if (index + 1 >= episode.budget.calls) {
           await this.tasks()?.cancel({ ownerId: episode.ownerId, episodeId: episode.id, reason: 'CALL_BUDGET' });
           await this.repository.finish(episode, 'budget_exhausted', 'CALL_BUDGET');
@@ -344,7 +365,7 @@ export class PersonRuntime {
       // On authority failure no alternate memory store is used. Expired leases become durable interrupted records on next access.
       await this.repository.finish(episode, status, safe.code).catch(() => {});
     } finally {
-      clearTimeout(timeout); clearInterval(heartbeat);
+      clearInterval(heartbeat);
       if (!signal.aborted) controller.abort(new PersonError('INTERRUPTED'));
     }
   }

package/yeaft/person/service.js

@@ -7,6 +7,7 @@ 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';
 
 /**
@@ -21,9 +22,9 @@ export function createPersonService(options = {}) {
   identifier(namespace);
   const configured = typeof yeaftDir === 'string' && Boolean(yeaftDir.trim());
   const calls = options.maxCalls ?? LIMITS.calls;
-  const timeoutMs = options.timeoutMs ?? LIMITS.timeoutMs;
+  // Legacy timeoutMs is intentionally ignored: an episode has no wall-clock deadline.
   const leaseMs = options.leaseMs ?? LIMITS.leaseMs;
-  if (!Number.isInteger(calls) || calls < 1 || calls > 32 || !Number.isInteger(timeoutMs) || timeoutMs < 100 || timeoutMs > 300000 ||
+  if (!Number.isInteger(calls) || calls < 1 || calls > 32 ||
       !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 ? new SqlitePersonRepository({ yeaftDir, namespace, leaseMs }) : null;
@@ -42,7 +43,7 @@ export function createPersonService(options = {}) {
     ? memory.recall(ownerId, args, { signal }) : literalRecall(ownerId, args);
   // Config/adapter are loaded per explicit episode, not a permanent stale cache.
   const getProvider = (modelCandidates = [], defaultModel = null) => createPersonProvider({ yeaftDir, config, adapter, allowedModels, modelCandidates, defaultModel, effortEnabled: options.effortEnabled });
-  const runtime = new PersonRuntime({ repository, getProvider, budget: { calls, timeoutMs }, workDir, yeaftDir, config, namespace });
+  const runtime = new PersonRuntime({ repository, getProvider, budget: { calls }, workDir, yeaftDir, config, namespace });
   let closed = false;
   const requests = new Set();
   async function handle({ ownerId, op, payload = {} } = {}) {
@@ -125,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

@@ -100,11 +100,13 @@ export class SqlitePersonRepository {
   async episodeAttachments(episode) { return this.request('episodeAttachments', [episode]); }
   async context(episode) { return this.request('context', [episode]); }
   async recall(ownerId, options) { return this.request('recall', [ownerId, options]); }
+  async publishProgress(episode, data) { return this.request('publishProgress', [episode, data]); }
   async commit(episode, proposal, selection, callId, reportedSources = new Map()) { return this.request('commit', [episode, proposal, selection, callId, reportedSources]); }
   async finish(episode, status, code) { return this.request('finish', [episode, status, code]); }
   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-store.js

@@ -3,12 +3,13 @@ import { mkdirSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { isMainThread } from 'node:worker_threads';
-import { admissionReceipt, bytes, digest, fail, identifier, LIMITS, PersonError, text } from './contracts.js';
+import { admissionReceipt, bytes, digest, fail, FEEDBACK, identifier, LIMITS, PersonError, text } from './contracts.js';
 import { CREATED_CAPABILITY_LIMITS, createdCapabilityRecord, validateCreatedCapability } from './created-capability-contract.js';
 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,12 +45,15 @@ 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 WRITES = new Set(['open', 'recover', 'admit', 'heartbeat', 'append', 'startCall', 'finalizeCall', 'startCapability', 'finalizeCapability', 'commit', 'finish', 'cancel', 'settings', 'snapshot', 'saveCreatedCapability']);
+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', 'publishProgress', '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; };
 const sequence = value => {
@@ -253,6 +257,17 @@ export class SqlitePersonStore {
   own(episode) { const p = this.fenced(episode); if (!p) fail('STALE'); return p; }
   heartbeat(episode) {
     const p = this.own(episode); p.leaseUntil = new Date(this.now.getTime() + this.leaseMs); p.writeSerial++; this.put('persons', p);
+    const record = this.one('episodes', this.episodeScope(episode), ' AND id = ?', [episode.id]);
+    if (!record || record.status !== 'running') fail('STALE');
+    const lastAt = new Date(record.feedback?.at ?? record.lastReplyAt ?? record.createdAt).getTime();
+    // Heartbeats are at most 5s apart: publish the fallback between 55–60s.
+    // This updates one snapshot field, never adds messages or schedules cognition.
+    if (this.now.getTime() - lastAt >= FEEDBACK.maxMs - 5000 || record.feedback) {
+      const phase = record.openCall ? 'model' : record.openCapability ? 'capability' : 'preparing';
+      record.feedback = { at: this.now.getTime() - lastAt >= FEEDBACK.maxMs - 5000 ? this.now.toISOString() : record.feedback.at, phase };
+      if (phase === 'capability') record.feedback.capabilityId = record.openCapability.capability?.id;
+      this.put('episodes', record);
+    }
   }
   append(episode, kind, data) {
     // Call proof/publication events are emitted only by their transactional methods.
@@ -362,6 +377,32 @@ export class SqlitePersonStore {
       state: stateView(state), messages: this.rows('messages', scope, ' ORDER BY seq DESC LIMIT 12').reverse().map(messageView),
       concepts: [...new Map([...focused, ...recent].map(c => [c.id, conceptView(c)])).values()] };
   }
+  /** Publish only a validated, complete call's reply. This is communication, not
+   * a state/Concept commit. Fencing, dedupe and the memory journal share one transaction. */
+  publishProgress(episode, { callId, reply }) {
+    const p = this.own(episode), scope = this.episodeScope(episode);
+    identifier(callId); text(reply, 8192);
+    const record = this.one('episodes', scope, ' AND id = ?', [episode.id]);
+    if (!record || record.status !== 'running' || record.openCall || record.openCapability) fail('STALE');
+    const prior = this.rows('messages', scope, " AND json_extract(record, '$.episodeId') = ? AND json_extract(record, '$.replyKind') = 'progress'", [episode.id]);
+    const duplicate = prior.find(m => m.callId === callId);
+    if (duplicate) { if (duplicate.text !== reply) fail('INVALID_REQUEST'); return messageView(duplicate); }
+    const proof = this.one('traces', scope, " AND json_extract(record, '$.episodeId') = ? AND json_extract(record, '$.kind') = 'call_output' AND json_extract(record, '$.callId') = ? AND json_extract(record, '$.output.complete') = 1", [episode.id, callId]);
+    const accepted = this.one('traces', scope, " AND json_extract(record, '$.episodeId') = ? AND json_extract(record, '$.kind') = 'activity' AND json_extract(record, '$.callId') = ? AND json_extract(record, '$.disposition') = 'candidate'", [episode.id, callId]);
+    let proposal;
+    try { proposal = JSON.parse(proof?.output?.text); } catch { fail('INVALID_REQUEST'); }
+    if (!accepted || !proposal.next || proposal.reply !== reply) fail('INVALID_REQUEST');
+    // Provider latency counts too: a call started before 30s can finish after it.
+    if (this.now.getTime() - new Date(record.lastReplyAt ?? record.createdAt).getTime() < FEEDBACK.minMs ||
+        prior.some(m => m.text.trim() === reply.trim())) return null;
+    p.messageSeq++; p.writeSerial++; this.put('persons', p);
+    const message = this.doc(scope, { id: randomUUID(), revision: 1, seq: p.messageSeq, episodeId: episode.id,
+      callId, replyKind: 'progress', role: 'assistant', text: reply, createdAt: this.now });
+    this.put('messages', message, true); this.journal(scope, 'messages', message);
+    record.lastReplyAt = this.now.toISOString(); delete record.feedback; this.put('episodes', record);
+    this.trace(episode.ownerId, episode.id, 'progress_reply', { callId, messageId: message.id });
+    return messageView(message);
+  }
   commit(episode, proposal, selection, callId, reportedSources = new Map()) {
     const p = this.own(episode), scope = this.episodeScope(episode);
     if (proposal.baseStateVersion !== episode.baseStateVersion) fail('STALE');
@@ -387,7 +428,7 @@ export class SqlitePersonStore {
     this.put('state_commits', this.doc(scope, { id: randomUUID(), version: p.stateVersion, parentVersion: episode.baseStateVersion,
       episodeId: episode.id, callId, conceptRevisions: revisions, state: stateView(state), createdAt: this.now }), true);
     if (proposal.reply) {
-      const message = this.doc(scope, { id: randomUUID(), revision: 1, seq: p.messageSeq, episodeId: episode.id, role: 'assistant', text: proposal.reply, createdAt: this.now });
+      const message = this.doc(scope, { id: randomUUID(), revision: 1, seq: p.messageSeq, episodeId: episode.id, callId, replyKind: 'final', role: 'assistant', text: proposal.reply, createdAt: this.now });
       this.put('messages', message, true); this.journal(scope, 'messages', message);
     }
     const record = this.one('episodes', scope, ' AND id = ?', [episode.id]);
@@ -445,6 +486,35 @@ 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);
@@ -471,7 +541,8 @@ export class SqlitePersonStore {
     const scope = this.scope(ownerId), p = this.getPerson(ownerId), state = this.one('states', scope);
     const messages = this.rows('messages', scope, ' ORDER BY seq DESC LIMIT 21');
     const episode = this.one('episodes', scope, ' ORDER BY inputWatermark DESC');
-    const latestEpisode = episode ? { id: episode.id, status: episode.status,
+    const latestEpisode = episode ? { id: episode.id, status: episode.status, createdAt: episode.createdAt,
+      ...(episode.status === 'running' && episode.feedback ? { feedback: episode.feedback } : {}),
       ...(episode.terminalCode ? { terminalCode: episode.terminalCode } : {}), ...(episode.endedAt ? { endedAt: episode.endedAt } : {}) } : null;
     return { latestEpisode, person: this.personView(p), state: stateView(state), concepts: this.focused(scope, state.focusConceptIds).slice(0, 12).map(conceptView),
       messages: messages.slice(0, 20).reverse().map(messageView), nextMessagesCursor: messages.length > 20 ? String(messages[19].seq) : null,

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 };
+}