import { createHash } from 'node:crypto'; const hash = value => createHash('sha256').update(JSON.stringify(value)).digest('hex'); const validRange = read => read && typeof read.key === 'string' && /^[a-f0-9]{64}$/.test(read.sha256) && Number.isSafeInteger(read.start) && Number.isSafeInteger(read.end) && read.start >= 0 && read.end > read.start; const merge = ranges => ranges.sort((a, b) => a[0] - b[0]).reduce((result, range) => { const last = result.at(-1); if (last && range[0] <= last[1]) last[1] = Math.max(last[1], range[1]); else result.push([...range]); return result; }, []); const size = ranges => ranges.reduce((sum, [start, end]) => sum + end - start, 0); export const TURN_PROGRESS_LIMITS = Object.freeze({ sources: 32, ranges: 24, facts: 96, failures: 48, turns: 40, tools: 64 }); // External facts only. Neither message wording nor model reasoning is an input. // Every result is shadow data, never a stop/permission/budget decision. export function observeTurn(previous, facts) { const scope = { projectId: facts.projectId, sessionId: facts.sessionId, taskId: facts.taskId, runId: facts.runId }; if (previous && hash(previous.scope) !== hash(scope)) throw new Error('Turn observation belongs to another Task/Run.'); const state = previous ? structuredClone(previous) : { schemaVersion: 1, mode: 'shadow', scope, reads: [], facts: [], failures: [], turns: [], observations: 0, truncated: false }; let uncertain = false; const remember = (collection, signature, limit) => { if (collection.includes(signature)) return false; if (collection.length >= limit) { state.truncated = true; uncertain = true; return false; } collection.push(signature); return true; }; const delta = { read_characters: 0, new_sources: 0, repeated_reads: 0, changed_files: 0, check_results: 0, requirement_evidence: 0, user_boundaries: 0, new_failures: 0, repeated_failures: 0, other_observations: 0 }; const reasons = [], refs = []; const tools = facts.tools ?? []; if (tools.length > TURN_PROGRESS_LIMITS.tools) { state.truncated = true; uncertain = true; } for (const tool of tools.slice(0, TURN_PROGRESS_LIMITS.tools)) { refs.push({ id: tool.id, tool: tool.name, args_sha256: tool.argsSha256 ?? null, result_artifact_id: tool.artifactId ?? null, result_sha256: tool.resultSha256 ?? null, ...(tool.sourceEventId ? { source_event_id: tool.sourceEventId, diagnostic_sha256: tool.diagnosticSha256 } : {}) }); if (tool.failure) { const signature = hash([tool.name, tool.argsSha256, tool.failure.category, tool.failure.signature]); if (remember(state.failures, signature, TURN_PROGRESS_LIMITS.failures)) { delta.new_failures++; reasons.push('new_failure:' + tool.failure.category); } else if (!uncertain) { delta.repeated_failures++; reasons.push('repeated_failure:' + tool.failure.category); } continue; } if (validRange(tool.read)) { const read = tool.read, key = hash([read.key, read.sha256, read.unit]); let entry = state.reads.find(value => value.key === key); if (!entry) { if (state.reads.length >= TURN_PROGRESS_LIMITS.sources) { state.truncated = true; uncertain = true; continue; } entry = { key, sha256: read.sha256, unit: read.unit, ranges: [] }; state.reads.push(entry); delta.new_sources++; } const ranges = merge([...entry.ranges, [read.start, read.end]]), growth = size(ranges) - size(entry.ranges); if (ranges.length > TURN_PROGRESS_LIMITS.ranges) { state.truncated = true; uncertain = true; continue; } entry.ranges = ranges; delta.read_characters += growth; if (!growth) delta.repeated_reads++; } else if (tool.observationSignature && remember(state.facts, hash(['observation', tool.name, tool.observationSignature]), TURN_PROGRESS_LIMITS.facts)) delta.other_observations++; } const count = (rows, kind, field) => { if ((rows?.length ?? 0) > TURN_PROGRESS_LIMITS.facts) { state.truncated = true; uncertain = true; } for (const row of (rows ?? []).slice(0, TURN_PROGRESS_LIMITS.facts)) if (remember(state.facts, hash([kind, row]), TURN_PROGRESS_LIMITS.facts)) delta[field]++; }; count(facts.changes, 'changes', 'changed_files'); count(facts.checks, 'checks', 'check_results'); count(facts.requirements, 'requirements', 'requirement_evidence'); count(facts.userBoundaries, 'user', 'user_boundaries'); if (delta.read_characters) reasons.push('new_returned_file_or_artifact_range'); if (delta.repeated_reads) reasons.push('same_sha_range_already_returned'); for (const field of ['changed_files', 'check_results', 'requirement_evidence', 'user_boundaries', 'other_observations']) if (delta[field]) reasons.push(field); const waiting = (facts.waiting ?? []).slice(0, 16).map(row => ({ kind: row.kind, id: row.id })); const growth = delta.read_characters + delta.changed_files + delta.check_results + delta.requirement_evidence + delta.other_observations; const classification = facts.phase === 'baseline' ? 'baseline' : waiting.length ? 'waiting' : growth ? 'evidence_growth' : delta.new_failures ? 'new_failure_evidence' : delta.user_boundaries ? 'user_boundary' : uncertain ? 'unknown_bounded' : delta.repeated_failures ? 'repeated_failure_candidate' : delta.repeated_reads ? 'repeated_read_candidate' : 'no_observed_change'; if (facts.phase === 'baseline') { for (const key of Object.keys(delta)) delta[key] = 0; reasons.length = 0; reasons.push('existing_facts_not_run_progress'); } const observation = { schemaVersion: 1, mode: 'shadow', taskId: scope.taskId, runId: scope.runId, stepId: facts.stepId ?? null, stepIndex: facts.stepIndex ?? null, phase: facts.phase ?? 'settled', classification, delta, reasons: [...new Set(reasons)].slice(0, 16), tools: refs, waiting, truncated: state.truncated, note: '外显事实观察;不等于业务交付,不改变停止、权限或预算。' }; state.observations++; state.turns.push(observation); if (state.turns.length > TURN_PROGRESS_LIMITS.turns) { state.turns.shift(); state.truncated = true; } return { state, observation }; } export function toolProgressFacts(record, result, artifact, failureCategory = null) { const value = { id: record.id, name: record.tool, argsSha256: record.argsSha256, artifactId: artifact?.id, resultSha256: artifact?.sha256 }; const status = result.status; if (record.requiresVerification || ['unknown', 'interrupted', 'unverified'].includes(status)) { value.failure = { category: 'requires_verification', signature: hash([status, result.code, result.message]) }; } else if (['failed', 'error', 'denied'].includes(status)) { value.failure = { category: status === 'denied' ? 'permission' : failureCategory ?? 'tool_or_environment', signature: hash([status, result.code, result.message, result.exit_code]) }; } else if (['read_file', 'read_artifact', 'read_browser_result', 'read_research_evidence'].includes(record.tool) && typeof result.content === 'string') { const start = result.offset ?? 0, end = result.next_offset ?? start + result.content.length; // Offsets refer to UTF-16 characters within the original tool range. They // are deliberately not labeled file bytes or cumulative token savings. if (end - start === result.content.length) value.read = { key: hash([result.path ?? result.artifact_id ?? result.job_id, result.range_start_line ?? result.start_line ?? null, result.range_end_line ?? result.end_line ?? null, result.section ?? null]), sha256: result.sha256, start, end, unit: 'utf16_in_original_range' }; } else if (['inspect_project', 'list_files', 'search_files', 'index_project', 'query_code'].includes(record.tool)) { const { tool_invocation_id, repeated_read_count, reading_hint, ...actual } = result; // Random invocation IDs and changing timestamps are not observation growth. delete actual.inspectedAt; delete actual.createdAt; delete actual.durationMs; value.observationSignature = hash(actual); } return value; }