@yeaft/webchat-agent 1.0.622 → 1.0.624

package/yeaft/person/sqlite-store.js

@@ -10,6 +10,7 @@ import { attachmentMetadata, attachmentRequestHash, validateFiles } from './atta
 import { capabilityExperienceView, recordCapabilityExperience } from './capability-experience.js';
 import { chronologicalCursor, conceptView, inspectionCursor, inspectionPage, inspectRequest, messageView, personName, searchRequest, settingsView, stateView } from './inspection.js';
 import { TOKEN_FIELDS, turnsPage, turnView } from './turn-diagnostics.js';
+import { personPresentation } from './presentation.js';
 import { inspectCapabilities } from './capabilities.js';
 import { OUTPUT_LIMITS, outputArgs, outputMime, outputReadRequest, outputsPage, outputUrl, outputView } from './outputs.js';
 
@@ -65,7 +66,7 @@ const objectOutput = (record, data) => {
   }
 };
 const READS = new Set(['outputs', 'outputRead', 'checkOutputPublication', 'receipt', 'turns', 'inspect', 'search', 'getPerson', 'context', 'recall', 'list', 'searchChanges', 'resolveMemories', 'createdCapabilities', 'episodeAttachments']);
-const WRITES = new Set(['saveOutput', 'open', 'recover', 'admit', 'heartbeat', 'append', 'startCall', 'finalizeCall', 'startCapability', 'finalizeCapability', 'commit', 'publishProgress', 'finish', 'cancel', 'settings', 'snapshot', 'saveCreatedCapability']);
+const WRITES = new Set(['executionControl', 'savePresentation', 'saveOutput', '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 => {
@@ -199,6 +200,7 @@ export class SqlitePersonStore {
       this.put('persons', p);
       const episode = this.one('episodes', scope, ' AND id = ?', [id]);
       if (episode?.status === 'running') {
+        delete episode.executionControl;
         Object.assign(episode, { status: 'interrupted', terminalCode: 'INTERRUPTED', endedAt: this.now });
         this.put('episodes', episode); this.abandonCall(ownerId, episode, 'INTERRUPTED');
       }
@@ -267,6 +269,14 @@ export class SqlitePersonStore {
       (!withLease || p.leaseUntil > this.now) ? p : null;
   }
   own(episode) { const p = this.fenced(episode); if (!p) fail('STALE'); return p; }
+  executionControl(episode, control) {
+    this.own(episode);
+    const record = this.one('episodes', this.episodeScope(episode), ' AND id = ?', [episode.id]);
+    if (!record || record.status !== 'running' || !['running', 'pausing', 'paused'].includes(control.status)) fail('STALE');
+    record.executionControl = { status: control.status, updatedAt: this.now.toISOString() };
+    this.put('episodes', record);
+    return { episodeId: episode.id, ...record.executionControl };
+  }
   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]);
@@ -275,7 +285,7 @@ export class SqlitePersonStore {
     // 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';
+      const phase = record.executionControl?.status === 'paused' ? 'paused' : 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);
@@ -283,7 +293,7 @@ export class SqlitePersonStore {
   }
   append(episode, kind, data) {
     // Call proof/publication events are emitted only by their transactional methods.
-    if (['call_started', 'call_output', 'call_failed', 'capability_created', 'capability_finalized', 'output_published'].includes(kind)) fail('INVALID_REQUEST');
+    if (['call_started', 'call_output', 'call_failed', 'capability_created', 'capability_finalized', 'output_published', 'presentation_published'].includes(kind)) fail('INVALID_REQUEST');
     const p = this.own(episode);
     const record = this.one('episodes', this.episodeScope(episode), ' AND id = ?', [episode.id]);
     if (!record || record.status !== 'running') fail('STALE');
@@ -301,7 +311,7 @@ export class SqlitePersonStore {
     this.put('episodes', record);
     return this.trace(episode.ownerId, episode.id, 'call_started', data);
   }
-  finalizeCall(episode, { callId, effective, output, code = null }) {
+  finalizeCall(episode, { callId, effective, output, requestElapsedMs, code = null }) {
     const scope = this.episodeScope(episode), record = this.one('episodes', scope, ' AND id = ?', [episode.id]);
     if (!record || record.workerId !== episode.workerId || record.epoch !== episode.epoch || record.openCall?.callId !== callId) return false;
     const live = record.status === 'running' && Boolean(this.fenced(episode));
@@ -315,6 +325,8 @@ export class SqlitePersonStore {
     delete record.openCall; delete record.callFinalizeUntil; this.put('episodes', record);
     this.trace(episode.ownerId, episode.id, failed ? 'call_failed' : 'call_output', {
       callId, requested: call.requested, effective: safeEffective, output: publicOutput(output, failed),
+      // Actual provider time excludes any pause between journal start and dispatch.
+      ...(Number.isSafeInteger(requestElapsedMs) && requestElapsedMs >= 0 ? { requestElapsedMs } : {}),
       ...(!failed && call.manifest ? { manifest: call.manifest } : {}), ...(failed ? { code: new PersonError(terminalCode).code } : {}),
     });
     return live;
@@ -389,6 +401,48 @@ 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()] };
   }
+  /** Atomic capability publication: exact started invocation + live lease, never
+   * publishProgress's no-open-capability path. JSON carries the canonical payload;
+   * text remains the searchable/model/legacy fallback. phase is delivery intent. */
+  savePresentation(episode, { callId, args }) {
+    identifier(callId);
+    const presentation = personPresentation(args);
+    const p = this.own(episode), scope = this.episodeScope(episode);
+    const record = this.one('episodes', scope, ' AND id = ?', [episode.id]);
+    const invocationHash = digest({ id: 'PresentResponse', args });
+    const prior = this.rows('messages', scope, " AND json_extract(record, '$.episodeId') = ? AND json_type(record, '$.presentation') = 'object'", [episode.id]);
+    const receipt = this.one('traces', scope,
+      " AND json_extract(record, '$.episodeId') = ? AND json_extract(record, '$.kind') = 'presentation_published' AND json_extract(record, '$.callId') = ?", [episode.id, callId]);
+    if (receipt) {
+      if (receipt.invocationHash !== invocationHash) fail('INVALID_REQUEST');
+      const message = prior.find(m => m.id === receipt.messageId);
+      if (!message) fail('STORAGE_UNAVAILABLE');
+      return messageView(message);
+    }
+    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]);
+    if (!record || record.status !== 'running' || record.openCall || !proof || record.openCapability?.callId !== callId ||
+        record.openCapability.invocationHash !== invocationHash) fail('STALE');
+    // Repeating an identical delivery in this episode adds no new visible answer.
+    const repeated = prior.find(m => digest(m.presentation) === digest(presentation));
+    if (repeated) {
+      this.trace(episode.ownerId, episode.id, 'presentation_published', { callId, invocationHash, messageId: repeated.id, phase: presentation.phase, duplicate: true });
+      return messageView(repeated);
+    }
+    p.messageSeq++; p.writeSerial++; this.put('persons', p);
+    const message = this.doc(scope, { id: randomUUID(), revision: 1, seq: p.messageSeq, episodeId: episode.id,
+      callId, publicationHash: invocationHash, replyKind: 'presentation', role: 'assistant',
+      text: presentation.summary, presentation, 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, 'presentation_published', { callId, invocationHash, messageId: message.id, phase: presentation.phase });
+    return messageView(message);
+  }
+  repeatsPresentation(scope, episodeId, reply) {
+    return typeof reply === 'string' && this.rows('messages', scope,
+      " AND json_extract(record, '$.episodeId') = ? AND json_type(record, '$.presentation') = 'object'", [episodeId])
+      .some(message => message.text.trim() === reply.trim());
+  }
   /** 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 }) {
@@ -406,7 +460,7 @@ export class SqlitePersonStore {
     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;
+        prior.some(m => m.text.trim() === reply.trim()) || this.repeatsPresentation(scope, episode.id, reply)) 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 });
@@ -418,7 +472,8 @@ export class SqlitePersonStore {
   commit(episode, proposal, selection, callId, reportedSources = new Map()) {
     const p = this.own(episode), scope = this.episodeScope(episode);
     if (proposal.baseStateVersion !== episode.baseStateVersion) fail('STALE');
-    p.stateVersion++; p.writeSerial++; if (proposal.reply) p.messageSeq++;
+    const publishReply = proposal.reply && !this.repeatsPresentation(scope, episode.id, proposal.reply);
+    p.stateVersion++; p.writeSerial++; if (publishReply) p.messageSeq++;
     p.activeEpisodeId = null; p.leaseOwner = null; p.leaseUntil = new Date(0);
     this.put('persons', p);
     const revisions = [];
@@ -441,12 +496,13 @@ export class SqlitePersonStore {
     this.put('states', state);
     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) {
+    if (publishReply) {
       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]);
     if (!record || record.status !== 'running') fail('STALE');
+    delete record.executionControl;
     Object.assign(record, { status: 'completed', endedAt: this.now, stateVersion: p.stateVersion }); this.put('episodes', record);
     this.trace(episode.ownerId, episode.id, 'committed', { callId, parentVersion: episode.baseStateVersion, stateVersion: p.stateVersion, conceptRevisions: revisions, decision: proposal.decision });
     return { state: stateView(state) };
@@ -457,6 +513,7 @@ export class SqlitePersonStore {
     p.writeSerial++; p.epoch++; p.activeEpisodeId = null; p.leaseOwner = null; p.leaseUntil = new Date(0); this.put('persons', p);
     const record = this.one('episodes', this.episodeScope(episode), ' AND id = ?', [episode.id]);
     if (record?.status === 'running') {
+      delete record.executionControl;
       Object.assign(record, { status, terminalCode: code, endedAt: this.now }); this.put('episodes', record); this.abandonCall(episode.ownerId, record, code);
     }
     this.trace(episode.ownerId, episode.id, status, { code, baseStateVersion: episode.baseStateVersion });
@@ -469,6 +526,7 @@ export class SqlitePersonStore {
     p.epoch++; p.controlVersion++; p.writeSerial++; p.activeEpisodeId = null; p.leaseOwner = null; p.leaseUntil = new Date(0); this.put('persons', p);
     const record = this.one('episodes', scope, ' AND id = ?', [id]);
     if (record?.status === 'running') {
+      delete record.executionControl;
       Object.assign(record, { status: 'cancelled', terminalCode: 'CANCELLED', endedAt: this.now, callFinalizeUntil: until }); this.put('episodes', record);
     }
     this.trace(ownerId, id, 'cancelled', { code: 'CANCELLED' });
@@ -511,8 +569,10 @@ export class SqlitePersonStore {
     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
+    const project = fields => `json_object(${Object.entries(fields).map(([key, path]) => `'${key}', CASE json_type(record, '$.${path}')
+      WHEN 'text' THEN substr(json_extract(record, '$.${path}'), 1, 1000)
+      WHEN 'integer' THEN json_extract(record, '$.${path}') WHEN 'true' THEN 1 WHEN 'false' THEN 0 ELSE NULL END`).join(', ')})`;
+    const episodes = this.sql(`SELECT ${project({ id: 'id', seq: 'inputWatermark', kind: 'kind', status: 'status', createdAt: 'createdAt', endedAt: 'endedAt', terminalCode: 'terminalCode', controlStatus: 'executionControl.status', 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',
@@ -529,20 +589,27 @@ export class SqlitePersonStore {
       omittedConcepts: ['manifest.contextSources.omittedConcepts', 24], recallCount: ['manifest.contextSources.recall.count', 5] })
       .map(([key, args]) => `'${key}', ${number(...args)}`).join(', ');
     const recallKind = `CASE json_extract(record, '$.manifest.contextSources.recall.kind') WHEN 'messages' THEN 'messages' WHEN 'concepts' THEN 'concepts' ELSE NULL END`;
-    const usage = `json_object(${TOKEN_FIELDS.map(key => `'${key}', json_extract(record, '$.output.usage.${key}')`).join(', ')},
-      'accountingVersion', json_extract(record, '$.output.usage.accountingVersion'),
+    const usage = `json_object(${TOKEN_FIELDS.map(key => `'${key}', ${number(`output.usage.${key}`)}`).join(', ')},
+      'accountingVersion', ${number('output.usage.accountingVersion', 1)},
       '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')),
-      ${contextMetadata}, 'recallKind', ${recallKind}, 'usage', ${usage})`;
+    const metadata = `${project(fields).slice(0, -1)}, 'capabilityId', substr(COALESCE(CASE WHEN json_type(record, '$.capability.id') = 'text' THEN json_extract(record, '$.capability.id') END, CASE WHEN json_type(record, '$.capabilityId') = 'text' THEN json_extract(record, '$.capabilityId') END), 1, 128),
+      ${contextMetadata}, 'requestElapsedMs', ${number('requestElapsedMs')}, 'recallKind', ${recallKind}, 'usage', ${usage})`;
     const items = episodes.slice(0, limit).map(episode => {
-      const events = this.sql(`SELECT ${metadata} AS metadata FROM traces WHERE ${SCOPE}
+      const starts = this.sql(`SELECT seq, ${number('callIndex')} AS callIndex FROM traces WHERE ${SCOPE} AND json_extract(record, '$.episodeId') = ?
+        AND json_extract(record, '$.kind') = 'call_started' ORDER BY seq DESC LIMIT 33`)
+        .all(...scopeValues(scope), episode.id);
+      const oldest = starts[Math.min(starts.length, 32) - 1]?.seq ?? 0;
+      const events = this.sql(`SELECT ${metadata} AS metadata FROM traces WHERE ${SCOPE} AND seq >= ?
         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 => {
+        ('call_started', 'call_output', 'call_failed', 'proposal_rejected', 'capability_started', 'capability_result', 'capability_failed', 'capability_finalized') ORDER BY seq DESC LIMIT 257`)
+        .all(...scopeValues(scope), oldest, episode.id).map(row => {
           const event = JSON.parse(row.metadata); event.effortObserved = event.effortObserved === 1; return event;
         });
-      return turnView(episode, events);
+      return { ...turnView(episode, events.slice(0, 256).reverse()),
+        loopCount: starts[0]?.callIndex != null ? starts[0].callIndex + 1 : starts.length > 32 ? null : starts.length,
+        callsTruncated: starts.length > 32 || events.length > 256, callWindowLimit: 32,
+        usageScope: starts.length > 32 || events.length > 256 ? 'latest-call-window' : 'episode' };
     });
     return { items, nextCursor: episodes.length > limit ? items.at(-1).seq : null };
   }

package/yeaft/person/task-host.js

@@ -1,4 +1,4 @@
-import { mkdirSync, realpathSync, readFileSync, writeFileSync, renameSync, readdirSync, existsSync, lstatSync } from 'node:fs';
+import { mkdirSync, realpathSync, readFileSync, writeFileSync, renameSync, readdirSync, opendirSync, existsSync, lstatSync } from 'node:fs';
 import { resolve, join, relative, isAbsolute, sep } from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { TaskManager } from '../tasks/manager.js';
@@ -96,8 +96,23 @@ function atomicJSON(path, value) {
   renameSync(temporary, path);
 }
 
-function jsonFiles(directory) {
+function jsonFiles(directory, { limit } = {}) {
   if (!existsSync(directory)) return [];
+  if (limit != null) {
+    // Main cognition reads a bounded latest window, not every durable result at once.
+    // Iterate directory entries without assembling an unbounded filename array.
+    const handle = opendirSync(directory), records = [];
+    const time = record => new Date(record.updatedAt ?? record.task?.updatedAt ?? record.createdAt ?? 0).getTime() || 0;
+    try {
+      for (let entry; (entry = handle.readSync());) {
+        if (!entry.isFile() || !entry.name.endsWith('.json')) continue;
+        try { records.push(JSON.parse(readFileSync(join(directory, entry.name), 'utf8'))); } catch { continue; }
+        records.sort((a, b) => time(b) - time(a));
+        if (records.length > limit) records.pop();
+      }
+    } finally { handle.closeSync(); }
+    return records;
+  }
   return readdirSync(directory).filter(name => name.endsWith('.json')).flatMap(name => {
     try { return [JSON.parse(readFileSync(join(directory, name), 'utf8'))]; } catch { return []; }
   });
@@ -562,9 +577,9 @@ class ScopedPersonTaskHost {
     this.#persistAgents();
     const recent = items => items.sort((a, b) => String(b.updatedAt ?? b.task?.updatedAt ?? '').localeCompare(String(a.updatedAt ?? a.task?.updatedAt ?? ''))).slice(0, limit);
     return { namespace: this.scope.key, sessionId: this.sessionId,
-      tasks: recent(jsonFiles(this.#manager.store.sessionDir(this.sessionId))),
-      agents: clone([...this.#agents.values()].slice(-limit)), completions: recent(jsonFiles(join(this.dataRoot, 'completions'))),
-      toolResults: recent(jsonFiles(join(this.dataRoot, 'tool-results'))).map(result => ({ ...result,
+      tasks: recent(jsonFiles(this.#manager.store.sessionDir(this.sessionId), { limit })),
+      agents: clone([...this.#agents.values()].slice(-limit)), completions: recent(jsonFiles(join(this.dataRoot, 'completions'), { limit })),
+      toolResults: recent(jsonFiles(join(this.dataRoot, 'tool-results'), { limit })).map(result => ({ ...result,
         output: result.output.slice(0, 8192), rawPath: join(this.dataRoot, 'tool-results', `${result.id}.json`) })) };
   }
 

package/yeaft/person/turn-diagnostics.js

@@ -51,7 +51,7 @@ export function callUsage(raw, completed) {
   return { ...usage, reportedCalls: Number(reported), missingCalls: Number(!reported), complete: completed && usage.totalTokens !== null };
 }
 
-function sumUsage(calls, terminal) {
+export 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);
@@ -84,7 +84,11 @@ export function turnView(episode, events) {
     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.endedAt = event.createdAt;
+      // Legacy call lifecycle timestamps include queue/pause time. Do not label
+      // them as provider duration when no actual dispatch measurement was stored.
+      call.elapsedMs = token(event.requestElapsedMs);
+      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') {
@@ -97,7 +101,7 @@ export function turnView(episode, events) {
     }
   }
   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,
+  return { id: episode.id, seq: episode.seq, kind: episode.kind, status: episode.status, controlStatus: episode.status === 'running' ? string(episode.controlStatus) : null, 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 };
 }

package/yeaft/response-presentation.js

@@ -0,0 +1,81 @@
+/** Shared, bounded user-visible response contract for native Sessions and Persons.
+ * Contains no executable markup, filesystem access or network requests. Runtime
+ * owns identity/phase; summary remains useful without the rich client.
+ */
+const str = (maxLength = 2000) => ({ type: 'string', maxLength });
+const arr = (items, maxItems, minItems = 1) => ({ type: 'array', items, minItems, maxItems });
+const obj = (properties, required) => ({ type: 'object', properties, required, additionalProperties: false });
+const block = (type, properties, required) => obj({ type: { type: 'string', enum: [type] }, title: str(160), ...properties }, ['type', ...required]);
+export const PRESENTATION_SCHEMA = obj({
+  title: str(160),
+  summary: str(8000),
+  phase: { type: 'string', enum: ['progress', 'final'] },
+  blocks: arr({ anyOf: [
+    block('markdown', { text: str(12000) }, ['text']),
+    block('cards', { items: arr(obj({ title: str(160), text: str(2000), label: str(80) }, ['title', 'text']), 8) }, ['items']),
+    block('metrics', { items: arr(obj({ label: str(120), value: str(120), detail: str(240) }, ['label', 'value']), 8) }, ['items']),
+    block('table', { columns: arr(str(120), 8), rows: arr(arr(str(1000), 8, 1), 50) }, ['columns', 'rows']),
+    block('chart', { style: { type: 'string', enum: ['bar', 'line'] }, unit: str(60), series: arr(obj({ label: str(120), values: arr({ type: 'number' }, 40) }, ['label', 'values']), 4), labels: arr(str(120), 40) }, ['style', 'series', 'labels']),
+    block('timeline', { items: arr(obj({ label: str(120), title: str(160), text: str(2000) }, ['label', 'title', 'text']), 16) }, ['items']),
+    block('diagram', { nodes: arr(obj({ id: str(40), label: str(160) }, ['id', 'label']), 12), edges: arr(obj({ from: str(40), to: str(40), label: str(120) }, ['from', 'to']), 24, 0) }, ['nodes', 'edges']),
+    block('image', { url: str(2000), alt: str(240), caption: str(1000) }, ['url', 'alt']),
+    block('link', { url: str(2000), text: str(1000) }, ['url', 'text']),
+    block('map', { points: arr(obj({ label: str(160), latitude: { type: 'number', minimum: -90, maximum: 90 }, longitude: { type: 'number', minimum: -180, maximum: 180 }, detail: str(1000) }, ['label', 'latitude', 'longitude']), 20) }, ['points']),
+  ] }, 12),
+}, ['summary', 'blocks']);
+
+export const PRESENT_RESPONSE_DESCRIPTION = `Publish a rich user-visible response inside this turn: cards, metrics, comparison tables, bar/line charts, timelines, relationship diagrams, images, artifact links or coordinate maps. Optional: use normal text for simple answers. Supply a self-contained summary for copying, search, model history and older clients; do not repeat the whole rich answer afterwards. Use only verified data, mark uncertainty, and never fabricate chart values or coordinates. No HTML/JavaScript, arbitrary SVG, styling or executable content. Image/link URLs must be credential-free HTTP(S); images require the reader to load external content. Maps are coordinate sketches, not navigation maps, and do not fetch tiles. phase=progress continues work; phase=final is a delivery intent, not proof of task success. Runtime still owns persistence, cancellation and turn termination. Validation failure publishes nothing; correct the payload or answer in text.`;
+
+function check(value, schema, path) {
+  if (schema.anyOf) {
+    const candidate = schema.anyOf.find(s => value?.type === s.properties.type.enum[0]);
+    if (!candidate) throw new Error(`${path}: unsupported block type`);
+    return check(value, candidate, path);
+  }
+  if (schema.type === 'object') {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error(`${path}: expected object`);
+    for (const key of Object.keys(value)) if (!Object.hasOwn(schema.properties, key)) throw new Error(`${path}.${key}: unknown field`);
+    for (const key of schema.required) if (!Object.hasOwn(value, key)) throw new Error(`${path}.${key}: required`);
+    for (const [key, item] of Object.entries(value)) check(item, schema.properties[key], `${path}.${key}`);
+  } else if (schema.type === 'array') {
+    if (!Array.isArray(value) || value.length < schema.minItems || value.length > schema.maxItems) throw new Error(`${path}: invalid item count`);
+    value.forEach((item, i) => check(item, schema.items, `${path}[${i}]`));
+  } else if (schema.type === 'string') {
+    if (typeof value !== 'string' || !value.trim() || value.length > schema.maxLength) throw new Error(`${path}: expected non-empty bounded text`);
+    if (schema.enum && !schema.enum.includes(value)) throw new Error(`${path}: unsupported value`);
+  } else if (schema.type === 'number') {
+    if (typeof value !== 'number' || !Number.isFinite(value) || Math.abs(value) > 1e12 || (schema.minimum !== undefined && value < schema.minimum) || (schema.maximum !== undefined && value > schema.maximum)) throw new Error(`${path}: invalid finite number`);
+  }
+}
+
+/** Return a canonical JSON-only snapshot; rejects rather than partially publishing. */
+export function normalizePresentation(input) {
+  check(input, PRESENTATION_SCHEMA, 'response');
+  const encoded = JSON.stringify(input);
+  if (new TextEncoder().encode(encoded).length > 49152) throw new Error('response: exceeds 48 KiB');
+  const value = JSON.parse(encoded);
+  for (const b of value.blocks) {
+    if (b.type === 'table' && b.rows.some(row => row.length !== b.columns.length)) throw new Error('table: every row must match the columns');
+    if (b.type === 'chart' && b.series.some(series => series.values.length !== b.labels.length)) throw new Error('chart: values must match labels');
+    if (b.type === 'diagram') {
+      const ids = new Set(b.nodes.map(n => n.id));
+      if (ids.size !== b.nodes.length || b.edges.some(e => !ids.has(e.from) || !ids.has(e.to))) throw new Error('diagram: unique nodes and existing edge endpoints required');
+    }
+    if (b.type === 'image' || b.type === 'link') b.url = safePresentationUrl(b.url);
+  }
+  const canonical = { version: 1, title: value.title || '', summary: value.summary, phase: value.phase || 'final', blocks: value.blocks };
+  if (new TextEncoder().encode(JSON.stringify(canonical)).length > 49152) throw new Error('response: exceeds 48 KiB');
+  return canonical;
+}
+
+/** External URLs are metadata only. Never fetch server-side or accept credentials. */
+export function safePresentationUrl(value) {
+  if (typeof value !== 'string' || /[\u0000-\u0020\u007f]/.test(value)) throw new Error('response: invalid URL');
+  let url;
+  try { url = new URL(value); } catch { throw new Error('response: invalid absolute URL'); }
+  if (!['https:', 'http:'].includes(url.protocol) || url.username || url.password) throw new Error('response: unsafe URL');
+  // Canonical URLs are encoded, so input length alone is not a safe bound.
+  // Persisted snapshots must pass exactly the same limits on replay.
+  if (url.href.length > 2000) throw new Error('response: URL exceeds 2000 characters');
+  return url.href;
+}

package/yeaft/stdio-protocol.js

@@ -319,6 +319,12 @@ export function createStreamProjector({
         state.resultText += event.text || '';
         write({ ...base, type: 'assistant', subtype: 'text_delta', delta: { type: 'text_delta', text: event.text || '' } });
         break;
+      case 'response_presentation':
+        state.resultText += event.message?.content || '';
+        write({ ...base, type: 'assistant', subtype: 'response_presentation',
+          message: event.message, content: [{ type: 'text', text: event.message?.content || '' }],
+          presentation: event.message?.presentation });
+        break;
       case 'thinking_delta':
         write({ ...base, type: 'assistant', subtype: 'thinking_delta', delta: { type: 'thinking_delta', thinking: event.text || '' } });
         break;

package/yeaft/tools/activation.js

@@ -10,6 +10,7 @@ export const ALWAYS_VISIBLE_TOOL_NAMES = Object.freeze([
   'EnterWorktree',
   'ExitWorktree',
   'AskUser',
+  'PresentResponse',
   'DiscoverTools',
   'WebSearch',
   'WebFetch',

package/yeaft/tools/index.js

@@ -25,6 +25,7 @@ import exitWorktree from './exit-worktree.js';
 
 // --- P0 Core tools ---
 import askUser from './ask-user.js';
+import presentResponse from './present-response.js';
 import webSearch from './web-search.js';
 import webFetch from './web-fetch.js';
 import historySearch from './history-search.js';
@@ -92,6 +93,7 @@ export const allTools = [
 
   // P0 Core
   askUser,
+  presentResponse,
   webSearch,
   webFetch,
   historySearch,

package/yeaft/tools/present-response.js

@@ -0,0 +1,27 @@
+import { defineTool } from './types.js';
+import { PRESENTATION_SCHEMA, normalizePresentation, PRESENT_RESPONSE_DESCRIPTION } from '../response-presentation.js';
+
+export default defineTool({
+  name: 'PresentResponse',
+  description: PRESENT_RESPONSE_DESCRIPTION,
+  parameters: PRESENTATION_SCHEMA,
+  isReadOnly: () => false,
+  isConcurrencySafe: () => false,
+  cacheWithinQuery: false,
+  duplicateCallPolicy: () => 'allow',
+  errorOutput: 'json-error-envelope',
+  async execute(input, ctx) {
+    try {
+      // Validate the entire snapshot before invoking any host-side publication.
+      const presentation = normalizePresentation(input);
+      if (ctx?.signal?.aborted) throw new Error('Response publication was cancelled.');
+      if (typeof ctx?.publishResponse !== 'function') {
+        throw new Error('Response publication is unavailable in this runtime. Use normal text.');
+      }
+      const identity = await ctx.publishResponse(presentation);
+      return JSON.stringify({ accepted: true, ...identity, message: 'Response accepted for delivery. Continue work if needed; do not repeat the summary. The normal turn boundary still applies.' });
+    } catch (error) {
+      return JSON.stringify({ error: error.message });
+    }
+  },
+});

package/yeaft/web-bridge.js

@@ -1396,6 +1396,8 @@ function projectPersistedToHistoryEntry(m, { includeReflections = false } = {})
   entry.threadId = m.threadId || m.turnId || 'main';
   if (m.turnId) entry.turnId = m.turnId;
   if (m.imageAssetAnchor) entry.imageAssetAnchor = true;
+  if (m.presentation) entry.presentation = m.presentation;
+  if (m.presentationCallId) entry.presentationCallId = m.presentationCallId;
   if (m.responseKind === 'progress' || m.responseKind === 'result') entry.responseKind = m.responseKind;
   if (Number.isInteger(m.llmCallCount) && m.llmCallCount > 0) entry.llmCallCount = m.llmCallCount;
   for (const key of ['inputTokens', 'outputTokens', 'totalTokens', 'totalMs']) {
@@ -1541,6 +1543,8 @@ function projectVisibleHistoryChunkMessages(messages = []) {
       threadId: m.threadId || m.turnId || 'main',
       ...(m.turnId ? { turnId: m.turnId } : {}),
       ...(m.imageAssetAnchor === true ? { imageAssetAnchor: true } : {}),
+      ...(m.presentation ? { presentation: m.presentation } : {}),
+      ...(m.presentationCallId ? { presentationCallId: m.presentationCallId } : {}),
       ...(Array.isArray(m.attachments) && m.attachments.length > 0 ? { attachments: hydrateHistoryAttachmentPreviews(m.attachments, m.sessionId) } : {}),
       ...(m.quote ? { quote: m.quote } : {}),
       ...(Array.isArray(m.images) && m.images.length > 0 ? { images: m.images } : {}),
@@ -1615,6 +1619,7 @@ function emitLegacyHistoryOutputFrames(replayEntries) {
         type: 'assistant',
         message: {
           id: entry.id || null,
+          ...(entry.presentation ? { presentation: entry.presentation, presentationCallId: entry.presentationCallId, responseKind: entry.responseKind } : {}),
           content: [
             ...(entry.content ? [{ type: 'text', text: entry.content }] : []),
             ...((entry.toolCalls || []).map(toolCall => ({ type: 'tool_use', ...toolCall, history: true }))),
@@ -4156,6 +4161,14 @@ function handleEngineEvent(event, hctx) {
   }
   if ((event.type === 'text_delta' || event.type === 'thinking_delta')
       && (typeof event.text !== 'string' || event.text.length === 0)) return;
+  // Reject stale publications before touching timers, queued text or history.
+  if (event.type === 'response_presentation') {
+    const message = event.message;
+    if (hctx.signal?.aborted || !message?.id || !message.presentation
+        || message.sessionId !== hctx.sessionId || message.turnId !== hctx.turnId
+        || message.speakerVpId !== hctx.vpId || message.threadId !== (hctx.threadId || 'main')
+        || hctx.presentations?.some(row => row.id === message.id)) return;
+  }
   const terminalTurnEnd = event.type === 'turn_end' && event.terminal === true;
   const managesQueryTimer = terminalTurnEnd
     || event.type === 'aborted'
@@ -4190,6 +4203,27 @@ function handleEngineEvent(event, hctx) {
       maybeTransitionVpStatus(hctx, 'streaming');
       break;
 
+    case 'response_presentation': {
+      const message = event.message;
+      if (!hctx.presentations) hctx.presentations = [];
+      hctx.presentations.push({ ...message, _textPartsCount: (hctx.assistantTextParts || []).length });
+      hctx.presentationTextPartsCount = (hctx.assistantTextParts || []).length;
+      if (!hctx.skipPartialHistory) {
+        const prompts = hctx.includeInitialPrompt ? [hctx.prompt, ...(hctx.appendedUserPrompts || [])] : (hctx.appendedUserPrompts || []);
+        appendTurnToSessionHistory(hctx.sessionId, hctx.threadId || 'main', hctx.vpId,
+          prompts, hctx.assistantTextParts || [], hctx.toolCallsAccum || [],
+          hctx.toolResultsAccum || [], hctx.thinkingBlocksAccum || [],
+          { turnId: hctx.turnId, partial: true, presentations: hctx.presentations });
+      }
+      sendSessionOutputFrame({
+        type: 'assistant',
+        message: { id: message.id, content: message.content, presentation: message.presentation,
+          presentationCallId: message.presentationCallId, responseKind: 'progress' },
+        ts: message.time || null,
+      }, envelope);
+      break;
+    }
+
     case 'thinking_delta':
       sendSessionEvent({ type: 'thinking_delta', text: event.text }, envelope);
       break;
@@ -4308,7 +4342,7 @@ function handleEngineEvent(event, hctx) {
           hctx.toolCallsAccum || [],
           hctx.toolResultsAccum || [],
           hctx.thinkingBlocksAccum || [],
-          { turnId: hctx.turnId, partial: true },
+          { turnId: hctx.turnId, partial: true, presentations: hctx.presentations },
         );
       }
       sendSessionOutputFrame({
@@ -4376,6 +4410,22 @@ function handleEngineEvent(event, hctx) {
       // stop the user-query silence watchdog before that best-effort work.
       if (event.terminal) {
         (hctx.stopQueryTimer || hctx.pauseQueryTimer)?.();
+        const publications = hctx.presentations || [];
+        for (const row of publications) {
+          row.responseKind = 'progress';
+          row.stopReason = event.stopReason;
+          if (event.stopReason !== 'end_turn') row.incomplete = true;
+        }
+        const last = publications.at(-1);
+        if (event.stopReason === 'end_turn' && last?.presentation.phase === 'final'
+            && hctx.presentationTextPartsCount === (hctx.assistantTextParts || []).length) last.responseKind = 'result';
+        if (publications.length && !hctx.skipPartialHistory) {
+          const prompts = hctx.includeInitialPrompt ? [hctx.prompt, ...(hctx.appendedUserPrompts || [])] : (hctx.appendedUserPrompts || []);
+          appendTurnToSessionHistory(hctx.sessionId, hctx.threadId || 'main', hctx.vpId,
+            prompts, hctx.assistantTextParts || [], hctx.toolCallsAccum || [],
+            hctx.toolResultsAccum || [], hctx.thinkingBlocksAccum || [],
+            { turnId: hctx.turnId, partial: true, presentations: publications });
+        }
       }
       // A normal tool_use stop means "run tools, then call the adapter again",
       // so it must NOT end the VP's visible turn. An aborted turn is terminal
@@ -5668,6 +5718,7 @@ async function runVpTurn({ prompt, promptParts = null, sessionId, vpId, threadId
         pauseQueryTimer,
         touchQueryTimer: watchdog.touch,
         stopQueryTimer: watchdog.stop,
+        signal: vpAbort.signal,
         sessionId,
         vpId,
         turnId,
@@ -5810,7 +5861,7 @@ async function runVpTurn({ prompt, promptParts = null, sessionId, vpId, threadId
       // block after the target response.
       const visiblePrompts = inboundIsInternal ? appendedUserPrompts : [prompt, ...appendedUserPrompts];
       const appendHistoryStart = perfNowMs();
-      appendTurnToSessionHistory(sessionId, threadId, vpId, visiblePrompts, assistantTextParts, toolCallsAccum, toolResultsAccum, thinkingBlocksAccum, { turnId });
+      appendTurnToSessionHistory(sessionId, threadId, vpId, visiblePrompts, assistantTextParts, toolCallsAccum, toolResultsAccum, thinkingBlocksAccum, { turnId, presentations: handlerCtx.presentations });
       if (perfTraceId) {
         recordAgentPerfTrace(ctx.CONFIG, {
           traceId: perfTraceId,
@@ -5993,7 +6044,11 @@ function buildTurnHistoryEntries(threadId, vpId, prompts, assistantTextParts, to
     }
   }
 
-  const fullText = assistantTextParts.join('');
+  const presentations = opts.presentations || [];
+  const firstPublicationOffset = presentations[0]?._textPartsCount;
+  const fullText = Number.isInteger(firstPublicationOffset)
+    ? assistantTextParts.slice(0, firstPublicationOffset).join('')
+    : assistantTextParts.join('');
   if (fullText || toolCallsAccum.length > 0) {
     // Stamp speakerVpId on assistant + tool rows so the in-memory
     // baseSnapshot filter (filterSnapshotForVp) can mirror the disk
@@ -6037,6 +6092,19 @@ function buildTurnHistoryEntries(threadId, vpId, prompts, assistantTextParts, to
       entries.push(markEntry(toolMsg));
     }
   }
+  for (let index = 0; index < presentations.length; index += 1) {
+    const record = presentations[index];
+    const entry = projectPersistedToHistoryEntry(record);
+    if (entry) entries.push(markEntry(entry));
+    // Keep later prose after its publication in the runtime cache as well as
+    // on disk. The internal offset is never projected into public history.
+    if (Number.isInteger(record._textPartsCount)) {
+      const end = presentations[index + 1]?._textPartsCount ?? assistantTextParts.length;
+      const text = assistantTextParts.slice(record._textPartsCount, end).join('');
+      if (text) entries.push(markEntry({ role: 'assistant', content: text,
+        threadId: threadId || 'main', ...(vpId ? { speakerVpId: vpId } : {}) }));
+    }
+  }
   return entries;
 }