feat: wire optional progress reminders to actual requests and verified readback

This commit is contained in:
Agent Workbench Dev
2026-11-06 16:05:21 +08:00
parent 7725cb2ad8
commit 01377b24c0
21 changed files with 686 additions and 22 deletions
+145
View File
@@ -0,0 +1,145 @@
import { planHash } from '../../shared/contracts/task-plans.mjs';
import { requestHistory, requestVariants } from '../../shared/contracts/model-request.mjs';
import { verifyTurnProgressReceipt } from './turn-progress-recorder.mjs';
import { observeReminders, selectReminder, recordReminderDispatch } from './reminder-queue.mjs';
const scopeOf = run => ({ projectId: run.projectId, sessionId: run.sessionId, taskId: run.taskId, runId: run.id });
const owned = (row, scope) => row && row.projectId === scope.projectId && row.sessionId === scope.sessionId && row.taskId === scope.taskId && row.runId === scope.runId;
const current = (session, run) => session.id === run.sessionId && session.projectId === run.projectId && session.taskId === run.taskId && session.runId === run.id;
export function verifyReminderMessage(store, session, plan, body) {
const ref = plan.progressReminder;
if (!ref) return null;
const scope = { projectId: plan.projectId, sessionId: plan.sessionId, taskId: plan.taskId, runId: plan.runId };
const artifact = store.owned('artifact', ref.artifactId, session.id);
if (!owned(artifact, scope) || artifact.kind !== 'progress-reminder-message' || artifact.sha256 !== ref.sha256) throw new Error('提醒原文来源不一致。');
const message = JSON.parse(store.artifactStore.read(artifact));
if (planHash(message.scope) !== planHash(scope) || message.key !== ref.key || planHash(message.content) !== message.sha256) throw new Error('提醒原文归属不一致。');
for (const variant of requestVariants(body)) {
const matches = requestHistory(variant).filter(row => ['user', 'system'].includes(row.role) && typeof row.content === 'string' && row.content.includes(message.content));
const tools = (variant.tools ?? []).map(tool => tool.function?.name ?? tool.name);
if (matches.length !== 1 || message.tools.some(name => !tools.includes(name))) throw new Error('提醒与实际请求正文或工具不一致。');
}
return message;
}
// No permissions, retries or stops are delegated to this observer. All entry
// points isolate their own failures and leave the original execution intact.
export class ReminderManager {
constructor(store) { this.store = store; }
error(session, run, phase) {
if (!current(session, run)) return;
run.progressReminderError = { kind: 'reminder_unavailable', phase };
try { this.store.save(session, { type: 'run.reminder_unavailable', detail: { runId: run.id, phase } }); } catch { /* Original execution owns persistence failures. */ }
}
verifiedState(session, run) {
if (!run.progressReminders) return null;
const artifact = this.store.owned('artifact', run.progressReminderReceiptId, session.id);
if (!owned(artifact, scopeOf(run)) || artifact.kind !== 'progress-reminder-queue') throw new Error('提醒队列收据归属不一致。');
const receipt = JSON.parse(this.store.artifactStore.read(artifact));
if (planHash(receipt.state) !== planHash(run.progressReminders) || planHash(receipt.state.scope) !== planHash(scopeOf(run))) throw new Error('提醒队列与原收据不一致。');
return run.progressReminders;
}
save(session, run, state, phase) {
if (planHash(state) === planHash(run.progressReminders ?? null)) return;
const artifact = this.store.artifactStore.write(session, run, { schemaVersion: 1, phase, state }, { kind: 'progress-reminder-queue' });
this.store.core.artifact.set(artifact.id, artifact);
run.progressReminders = state; run.progressReminderReceiptId = artifact.id;
this.store.save(session, { type: 'run.progress_reminder', detail: { runId: run.id, phase, artifactId: artifact.id } });
}
observe(session, run, { endReason = null } = {}) {
if (!current(session, run) || (!this.store.config.progressRemindersEnabled && !run.progressReminders)) return;
try {
const state = this.verifiedState(session, run), id = run.progressShadowArtifactIds?.at(-1);
let receipt = null;
if (id && !endReason && state?.lastArtifactId !== id) {
const verified = verifyTurnProgressReceipt(this.store, session, run, id);
if (planHash(verified.observation) !== planHash(run.progressShadow?.turns.at(-1))) throw new Error('提醒观察与原收据不一致。');
receipt = { ...verified, ref: { artifactId: id, sha256: verified.artifact.sha256, ordinal: run.progressShadow.observations } };
}
const task = this.store.core.task.get(run.taskId);
// Only explicit file work is eligible for read nudges. General analysis,
// research and diagnostics remain valid read-only work without prompting.
const research = run.purpose === 'diagnostic' || !!run.workerId || task?.contract?.kind !== 'file';
const next = observeReminders(state, { scope: scopeOf(run), enabled: this.store.config.progressRemindersEnabled,
at: Date.now(), receipt, research, endReason });
this.save(session, run, next, endReason ?? 'observation');
} catch { this.error(session, run, 'observation'); }
}
prepare(session, run, toolSurface) {
if (!current(session, run) || run.purpose === 'diagnostic' || run.workerId || (!this.store.config.progressRemindersEnabled && !run.progressReminders)) return null;
try {
const state = this.verifiedState(session, run);
// Check source integrity again at use, including receipts retained before
// B's display window. Never trust the mutable in-memory projection alone.
for (const item of state?.items.filter(row => ['pending', 'delivered'].includes(row.status)) ?? [])
for (const ref of item.source) this.verifySource(session, run, ref);
const selected = selectReminder(state, { scope: scopeOf(run), enabled: this.store.config.progressRemindersEnabled,
at: Date.now(), visibleTools: toolSurface.entries.filter(row => row.visible).map(row => row.name) });
this.save(session, run, selected.state, 'selection');
if (!selected.message) return null;
const artifact = this.store.artifactStore.write(session, run, selected.message, { kind: 'progress-reminder-message' });
this.store.core.artifact.set(artifact.id, artifact);
return { message: selected.message, ref: { key: selected.message.key, artifactId: artifact.id, sha256: artifact.sha256 } };
} catch { this.error(session, run, 'selection'); return null; }
}
verifySource(session, run, ref) {
const verified = verifyTurnProgressReceipt(this.store, session, run, ref.artifactId);
if (verified.artifact.sha256 !== ref.sha256) throw new Error('提醒依据SHA变化。');
return verified;
}
requestEvidence(session, run, plan) {
const scope = scopeOf(run), frozenArtifact = this.store.owned('artifact', plan.artifactId, session.id);
if (!owned(plan, scope) || !owned(frozenArtifact, scope) || frozenArtifact.kind !== 'context-plan') throw new Error('提醒请求计划归属不一致。');
const frozen = JSON.parse(this.store.artifactStore.read(frozenArtifact));
for (const key of ['id', 'projectId', 'sessionId', 'taskId', 'runId', 'requestArtifactId', 'requestSha256', 'progressReminder'])
if (planHash(frozen[key] ?? null) !== planHash(plan[key] ?? null)) throw new Error('提醒请求与发送前封存不一致。');
const artifact = this.store.owned('artifact', plan.requestArtifactId, session.id);
if (!owned(artifact, scope) || artifact.kind !== 'model-request' || artifact.sha256 !== plan.requestSha256) throw new Error('提醒请求原文变化。');
return JSON.parse(this.store.artifactStore.read(artifact));
}
dispatch(session, run, plan, submission) {
if (!plan.progressReminder || !current(session, run) || session.status === 'stopping') return;
try {
const state = this.verifiedState(session, run);
const body = this.requestEvidence(session, run, plan);
const message = verifyReminderMessage(this.store, session, plan, body);
if (!requestVariants(body).some(variant => planHash(variant) === submission.wireRequestSha256)) throw new Error('提醒实际线路请求与原计划不一致。');
const next = recordReminderDispatch(state, { scope: scopeOf(run), at: Date.now(), message, requestId: plan.id, requestSha256: plan.requestSha256,
attemptId: submission.attemptId, wireRequestSha256: submission.wireRequestSha256 });
// Provider calls this only after submitting fetch, before awaiting the
// response. A later disable/cancel cannot erase that dispatch fact.
if (next.items.find(row => row.key === message.key)?.deliveries.some(row => row.requestId === plan.id)) {
plan.progressReminderDispatches ??= [];
if (!plan.progressReminderDispatches.some(row => row.attemptId === submission.attemptId))
plan.progressReminderDispatches.push({ ...submission, recordedAt: new Date().toISOString() });
}
this.save(session, run, next, 'dispatch');
} catch { this.error(session, run, 'dispatch'); }
}
inspect(session, run) {
const view = { schemaVersion: 1, enabled: this.store.config.progressRemindersEnabled === true, recorded: !!run.progressReminders,
evidenceVerified: false, receiptArtifactId: run.progressReminderReceiptId ?? null, items: [], error: run.progressReminderError ?? null };
if (!view.recorded) { view.evidenceVerified = true; return view; }
try {
const state = this.verifiedState(session, run);
for (const item of state.items) {
for (const ref of [...item.source, ...(item.resolution ? [item.resolution.source] : [])]) this.verifySource(session, run, ref);
for (const delivered of item.deliveries) {
const plan = this.store.owned('context_plan', delivered.requestId, session.id);
if (!owned(plan, scopeOf(run)) || plan.requestSha256 !== delivered.requestSha256 || !plan.progressReminderDispatches?.length) throw new Error('提醒送达请求未核对。');
const body = this.requestEvidence(session, run, plan);
const message = verifyReminderMessage(this.store, session, plan, body);
if (message.key !== item.key || message.sha256 !== delivered.messageSha256) throw new Error('提醒送达原文变化。');
const variants = requestVariants(body).map(planHash);
if (!delivered.attempts?.length || delivered.attempts.some(attempt => !variants.includes(attempt.wireRequestSha256)
|| !plan.progressReminderDispatches.some(row => row.attemptId === attempt.attemptId && row.wireRequestSha256 === attempt.wireRequestSha256))) throw new Error('提醒实际线路送达未核对。');
}
}
view.items = structuredClone(state.items).map(item => ({ ...item, deliveries: item.deliveries.map(row => ({ ...row,
requestArtifactId: this.store.core.context_plan.get(row.requestId).requestArtifactId })) }));
view.evidenceVerified = true;
} catch { view.error = { kind: 'reminder_evidence_unverified', phase: 'readback' }; }
return view;
}
}
+11 -4
View File
@@ -1,6 +1,6 @@
import { createHash } from 'node:crypto';
const hash = value => createHash('sha256').update(JSON.stringify(value)).digest('hex');
const hash = value => createHash('sha256').update(typeof value === 'string' ? value : JSON.stringify(value)).digest('hex');
const sha = value => /^[a-f0-9]{64}$/.test(value ?? '');
const active = item => ['pending', 'delivered'].includes(item.status);
const same = (a, b) => hash(a) === hash(b);
@@ -114,14 +114,21 @@ export function selectReminder(previous, { scope, enabled = false, at, visibleTo
// Dispatch means included in a real submitted request. It does not assert that
// an upstream received it, the model adopted it, or the advice caused progress.
export function recordReminderDispatch(previous, { scope, at, message, requestId, requestSha256 }) {
export function recordReminderDispatch(previous, { scope, at, message, requestId, requestSha256, attemptId = null, wireRequestSha256 = null }) {
const state = queue(previous, scope, previous?.enabled, at), item = state.items.find(row => row.key === message?.key);
if (!same(message?.scope, state.scope) || !sha(requestSha256) || typeof requestId !== 'string' || !requestId) throw new Error('Reminder request ownership is invalid.');
if (!state.enabled || !item || !active(item)) return state;
const expected = messageFor(state, item, message.tools ?? []);
if (!expected || !same(expected, message)) throw new Error('Reminder dispatch differs from selected advice.');
if (item.deliveries.some(row => row.requestId === requestId)) return state;
item.deliveries.push({ requestId, requestSha256, messageSha256: message.sha256, ordinal: state.lastOrdinal, dispatchedAt: at });
if (attemptId !== null && (typeof attemptId !== 'string' || !attemptId || !sha(wireRequestSha256))) throw new Error('Reminder wire attempt is invalid.');
let delivery = item.deliveries.find(row => row.requestId === requestId);
if (!delivery) {
delivery = { requestId, requestSha256, messageSha256: message.sha256, ordinal: state.lastOrdinal, dispatchedAt: at };
item.deliveries.push(delivery);
}
if (attemptId && !delivery.attempts?.some(row => row.attemptId === attemptId)) {
delivery.attempts ??= []; delivery.attempts.push({ attemptId, wireRequestSha256, dispatchedAt: at });
}
item.status = 'delivered';
return state;
}
+5 -2
View File
@@ -12,6 +12,7 @@ import { prefixAudit } from './prefix-audit.mjs';
import { observeRequest, providerHistory, requestPath } from './request-observation.mjs';
import { verifyToolSurface } from './tool-surface.mjs';
import { isPassthrough } from '../../shared/contracts/model-capacity.mjs';
import { verifyReminderMessage } from './reminder-manager.mjs';
const hash = value => createHash('sha256').update(typeof value === 'string' ? value : JSON.stringify(value), 'utf8').digest('hex');
const PLACEHOLDER_ID = '00000000-0000-0000-0000-000000000000';
@@ -189,7 +190,7 @@ export class RequestPlanner {
return { artifact_id: artifact.id, sha256: artifact.sha256, group_sha256: group.sha256, bytes: Buffer.byteLength(text, 'utf8'), chunks: chunks.length };
}
prepare(session, run, config, { system, contextTail = null, tools, toolSurface = null, stepId, projectMemory = null, skillCatalog = null, mcpCatalog = null, transportReservationTokens = 0,engineStepOnly=false }) {
prepare(session, run, config, { system, contextTail = null, tools, toolSurface = null, stepId, projectMemory = null, skillCatalog = null, mcpCatalog = null, progressReminder = null, transportReservationTokens = 0,engineStepOnly=false }) {
const task = this.store.owned('task', run.taskId, session.id);
this.store.owned('run', run.id, session.id);
const history = providerHistory(session, run);
@@ -406,6 +407,7 @@ export class RequestPlanner {
requestArtifactId: requestArtifact.id,
prefixAudit: prefix,
requestObservation: observation,
...(progressReminder ? { progressReminder } : {}),
...(preserve ? { contextLayout: 'stable-prefix-1', historyPolicy: 'preserve', contextTailArtifactId: tailArtifact?.id ?? null, contextTailSha256: tailArtifact?.sha256 ?? null } : {}),
...(tokenReservation?{tokenReservation,maxBudgetAttempts:Math.min(8,Math.floor(credit/tokenReservation.reservedTokens))}:{engineStepOnly:true}),
estimateMethod: metrics.estimateMethod, beforeInputTokens: before.estimatedInputTokens, beforeBytes: before.bytes, budget,
@@ -474,9 +476,10 @@ export function verifyPlanEvidence(store, session, plan, cache = new Map()) {
historyGroups(requestHistory(body));
for (const variant of requestVariants(body)) historyGroups(requestHistory(variant));
const frozen = JSON.parse(store.artifactStore.read(get(plan.artifactId, 'context-plan')));
for (const key of ['contextLayout', 'historyPolicy', 'contextTailArtifactId', 'contextTailSha256', 'prefixAudit', 'requestObservation']) {
for (const key of ['contextLayout', 'historyPolicy', 'contextTailArtifactId', 'contextTailSha256', 'prefixAudit', 'requestObservation', 'progressReminder']) {
if (JSON.stringify(frozen[key] ?? null) !== JSON.stringify(plan[key] ?? null)) throw new Error('前缀或历史策略与发送前封存不匹配。');
}
verifyReminderMessage(store, session, plan, body);
if (plan.requestObservation) {
const run = store.owned('run', plan.runId, session.id);
const expected = observeRequest(store, session, run, providerHistory(session, run).slice(0, plan.originalMessages), plan.requestObservation.toolSurface);
+14
View File
@@ -11,6 +11,7 @@ import { currentBrowserVerification, verifyBrowserJob } from './browser/browser-
import { TaskPlanManager } from './tasks/task-plan-manager.mjs';
import { RequirementReview } from './tasks/requirement-review.mjs';
import { inspectTurnProgress } from './context/turn-progress-recorder.mjs';
import { ReminderManager } from './context/reminder-manager.mjs';
import { FileResults } from './tasks/file-results.mjs';
import { taskContract } from '../shared/contracts/task-control.mjs';
import { modelIdentityLabel } from '../shared/contracts/model-identity.mjs';
@@ -150,6 +151,8 @@ export class DeliveryReporter {
: researchScope && !check ? contract.checks === 'skip' ? 'scope_verified' : 'research_verified'
: hasFileScope && !fileDelivery.newChanges ? 'existing_verified' : hasFileScope && contract.checks === 'skip' ? 'files_delivered'
: hasCommit ? 'verified_committed' : 'verified_uncommitted';
const reminders = [...this.store.core.run.values()].filter(value => value.sessionId === session.id && value.taskId === taskId && (value.progressReminders || value.progressReminderError))
.map(value => ({ runId: value.id, ...new ReminderManager(this.store).inspect(session, value) }));
const report = {
schemaVersion: 1, kind: 'engineering-delivery', generatedAt: new Date().toISOString(), status, statusLabel: labels[status],
lifecycle: { phase: run.finishedAt ? 'final' : 'snapshot', runStatus: run.status, finishedAt: run.finishedAt ?? null },
@@ -164,6 +167,7 @@ export class DeliveryReporter {
context: inspectDiagnosticContext(this.store, session, value) })),
turnObservations: [...this.store.core.run.values()].filter(value => value.sessionId === session.id && value.taskId === taskId)
.map(value => ({ runId: value.id, ...inspectTurnProgress(this.store, session, value) })),
...(reminders.length ? { reminderObservations: reminders } : {}),
fileResults, fileDelivery,
checkPolicy: contract.checks === 'skip' ? 'not_requested' : contract.checks,
gitOutcome: { status: hasCommit ? 'committed' : terminalGit.length ? 'observed_unverified' : !fileDelivery.newChanges && hasFileScope ? 'no_new_changes' : 'uncommitted',
@@ -269,6 +273,16 @@ export function renderDeliveryMarkdown(report) {
turn.classification, turn.delta.read_characters, turn.delta.repeated_reads, turn.delta.new_failures + ' / ' + turn.delta.repeated_failures,
run.evidence_verified ? '原字节已核对' : run.error].map(escapeCell).join(' | ') + ' |');
}
if (report.reminderObservations?.length) {
lines.push('', '## 提醒与实际回读', '', '随请求发出与后续工具进展分别记录;模型收到、采纳和收益因果未证实,不作为业务交付通过依据。', '',
'| Run / 建议 | 状态 | 实际发送请求 | 回读依据 | 原收据核对 |', '| --- | --- | --- | --- | --- |');
for (const run of report.reminderObservations) {
if (run.error) lines.push('', '提醒观察部分不可用;原任务结果保留。');
for (const item of run.items) lines.push('| ' + [run.runId + ' / ' + item.category, item.status,
item.deliveries.map(row => row.requestId).join(', ') || '未发送', item.resolution?.source.artifactId ?? '尚未观察到对应结果',
run.evidenceVerified ? '原字节已核对' : '待核对'].map(escapeCell).join(' | ') + ' |');
}
}
if (report.taskPlan?.configured) {
lines.push('', '## 执行计划与实际核验', '', '计划:' + (report.taskPlan.plan_id ?? '无法核对'),
'核验:' + (report.taskPlan.verified_steps ?? 0) + '/' + (report.taskPlan.total_steps ?? 0), '',
+2
View File
@@ -8,11 +8,13 @@ export const DEFAULT_CONFIG = {
mode: 'demo', baseUrl: 'http://127.0.0.1:11434/v1', model: '', ...DEFAULT_MODEL_CAPACITY, approvalMode: 'ask', capacityMode: 'passthrough', historyPolicy: 'preserve', executionMode: 'unrestricted', maxSteps: 0,
maxRunDurationMs: 0, maxRunTokens: 0, maxTaskTokens: 0, configRevision: 1,
modelResponseTimeoutMs: 0, modelStreamIdleTimeoutMs: 0,
progressRemindersEnabled: false,
};
export function cleanConfig(value = {}) {
const result = { ...DEFAULT_CONFIG };
for (const key of Object.keys(result)) if (Object.hasOwn(value, key)) result[key] = value[key];
result.progressRemindersEnabled = result.progressRemindersEnabled === true;
if (!Object.hasOwn(value, 'executionMode') && ['contextLimit', 'maxOutputTokens', 'maxSteps', 'maxRunTokens'].some(key => Object.hasOwn(value, key))) result.executionMode = 'restricted';
// Old settings stay manual. Every saved Run keeps its original snapshot.
if (!Object.hasOwn(value, 'capacityMode') && (Object.hasOwn(value, 'contextLimit') || Object.hasOwn(value, 'maxOutputTokens'))) result.capacityMode = 'manual';