You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maka.apache.org by as...@apache.org on 2026/09/07 00:26:17 UTC
(maka) 02/15: feat(runtime): convert every legacy transcript row instead of dropping some
This is an automated email from the ASF dual-hosted git repository.
Astro-Han pushed a commit to branch refactor/4791-single-transcript-authority
in repository https://gitbox.apache.org/repos/asf/maka.git
commit a1b58961190bd278a24dc8171104bd3b06208453
Author: AstroHan <le...@outlook.com>
AuthorDate: Sun Sep 6 02:27:36 2026 +0800
feat(runtime): convert every legacy transcript row instead of dropping some
The converter used to answer "this row cannot be recovered losslessly" by
writing nothing, which loses conversation the user can still read today.
Losslessness is a model-replay property, not a transcript one, so the rows
it could not replay now convert hidden: the card stays in the transcript
and no provider request is ever built from it.
A permission decision names its own tool, so it no longer needs a matching
call in the same turn; it carries the prompt's hint when nothing else
records it. A turn whose transcript never said how it ended now ends as
the failure it was, because an invocation left open is not a legal ledger
state and would strand the turn in recovery forever.
Generated-by: Claude Code
---
packages/core/src/runtime-event.ts | 11 ++-
.../src/__tests__/runtime-event-read-model.test.ts | 103 +++++++++++++++++++++
packages/runtime/src/runtime-event-backfill.ts | 98 +++++++++++---------
packages/runtime/src/runtime-event-read-model.ts | 5 +-
4 files changed, 168 insertions(+), 49 deletions(-)
diff --git a/packages/core/src/runtime-event.ts b/packages/core/src/runtime-event.ts
index e586b2df4e..3344b310e0 100644
--- a/packages/core/src/runtime-event.ts
+++ b/packages/core/src/runtime-event.ts
@@ -387,6 +387,12 @@ export interface RuntimeEventTokenUsage extends TokenUsageFields {}
*/
export interface RuntimeEventPermissionDecision extends PermissionResponse {
toolName?: string;
+ /**
+ * What the prompt told the user they were approving. Normally read off the
+ * paired request; carried here when the decision is the only surviving
+ * evidence that the prompt happened.
+ */
+ hint?: string;
}
export const TOOL_BOUNDARY_PROTOCOL_V1 = 't1_after_preflight_v1' as const;
@@ -829,7 +835,7 @@ const PERMISSION_CLOSURE_ACCEPTED_SHAPE =
defineObjectShape<RuntimeEventPermissionClosureAccepted>()(['requestId', 'reason'], []);
const RUNTIME_PERMISSION_DECISION_SHAPE = defineObjectShape<RuntimeEventPermissionDecision>()(
['requestId', 'decision'],
- ['rememberForTurn', 'reviewer', 'rationale', 'riskLevel', 'toolName'],
+ ['rememberForTurn', 'reviewer', 'rationale', 'riskLevel', 'toolName', 'hint'],
);
const UTF8 = new TextEncoder();
const RUNTIME_TOOL_DISPATCH_SHAPE = defineObjectShape<RuntimeEventToolDispatch>()(
@@ -1298,7 +1304,8 @@ function isRuntimeEventPermissionDecision(value: unknown): value is RuntimeEvent
(value.toolName === undefined ||
(typeof value.toolName === 'string' &&
value.toolName.length > 0 &&
- UTF8.encode(value.toolName).byteLength <= INTERACTION_TOOL_NAME_MAX_BYTES))
+ UTF8.encode(value.toolName).byteLength <= INTERACTION_TOOL_NAME_MAX_BYTES)) &&
+ isOptionalString(value.hint)
);
}
diff --git a/packages/runtime/src/__tests__/runtime-event-read-model.test.ts b/packages/runtime/src/__tests__/runtime-event-read-model.test.ts
index f5f9a660d4..68044efb3f 100644
--- a/packages/runtime/src/__tests__/runtime-event-read-model.test.ts
+++ b/packages/runtime/src/__tests__/runtime-event-read-model.test.ts
@@ -22,6 +22,7 @@ import { describe, test } from 'node:test';
import type { RuntimeInvocationRecord } from '@maka/core/runtime-invocation';
import type { CreateSessionInput, SessionListFilter } from '@maka/core/runtime-inputs';
import type { RuntimeEvent, RuntimeEventActions } from '@maka/core/runtime-event';
+import { runtimeEventHasModelVisibleContent } from '@maka/core/runtime-event';
import type { SessionHeader, SessionSummary, StoredMessage, TurnRecord } from '@maka/core/session';
import { deriveTurnRecords } from '@maka/core/session';
import {
@@ -2079,6 +2080,108 @@ describe('system note projection', () => {
});
});
+describe('legacy transcript conversion keeps every row', () => {
+ const convert = (messages: readonly StoredMessage[]) =>
+ backfillRuntimeEventsFromStoredMessages({
+ run: { sessionId, invocationId, runId, turnId },
+ outcome: { status: 'completed', ts },
+ messages,
+ modelHistory: 'full',
+ now: () => ts,
+ });
+
+ test('keeps a tool result whose call is not in the turn, out of model replay', () => {
+ const orphan: StoredMessage = {
+ type: 'tool_result',
+ id: 'legacy-orphan-result',
+ turnId,
+ ts,
+ toolUseId: 'tool-gone',
+ isError: false,
+ content: { kind: 'text', text: 'done' },
+ };
+
+ const converted = convert([orphan]);
+ const response = converted.events.find((event) => event.content?.kind === 'function_response');
+ assert.strictEqual(response?.modelVisibility, 'hidden');
+ assert.strictEqual(runtimeEventHasModelVisibleContent(response as RuntimeEvent), false);
+
+ const projected = projectRuntimeEventsToStoredMessages(converted.events, {
+ invocations: [invocation],
+ });
+ assert.partialDeepStrictEqual(
+ projected.messages.filter((message) => message.type === 'tool_result'),
+ [{ id: 'legacy-orphan-result', toolUseId: 'tool-gone' }],
+ );
+ });
+
+ test('keeps a provider-native call whose opaque output was not retained', () => {
+ const converted = convert([
+ {
+ type: 'tool_call',
+ id: 'tool-native',
+ turnId,
+ ts,
+ toolName: 'WebSearch',
+ args: { query: 'maka' },
+ providerExecuted: true,
+ },
+ ]);
+
+ const call = converted.events.find((event) => event.content?.kind === 'function_call');
+ assert.strictEqual(call?.modelVisibility, 'hidden');
+ assert.partialDeepStrictEqual(converted.diagnostics, [
+ { code: 'skipped_provider_native_replay_gap' },
+ ]);
+
+ const projected = projectRuntimeEventsToStoredMessages(converted.events, {
+ invocations: [invocation],
+ });
+ assert.partialDeepStrictEqual(
+ projected.messages.filter((message) => message.type === 'tool_call'),
+ [{ id: 'tool-native', toolName: 'WebSearch' }],
+ );
+ });
+
+ test('converts a permission decision on its own evidence', () => {
+ const decision: StoredMessage = {
+ type: 'permission_decision',
+ id: 'request-1',
+ turnId,
+ ts,
+ toolUseId: 'tool-1',
+ toolName: 'Bash',
+ decision: 'allow',
+ hint: 'rm -rf build',
+ };
+
+ const converted = convert([decision]);
+ assert.deepStrictEqual(converted.diagnostics, []);
+
+ const projected = projectRuntimeEventsToStoredMessages(converted.events, {
+ invocations: [invocation],
+ });
+ assert.deepStrictEqual(
+ projected.messages.filter((message) => message.type === 'permission_decision'),
+ [decision],
+ );
+ });
+
+ test('ends a turn whose transcript never said how it ended', () => {
+ const converted = backfillRuntimeEventsFromStoredMessages({
+ run: { sessionId, invocationId, runId, turnId },
+ messages: [{ type: 'user', id: 'legacy-user', turnId, ts, text: 'hello' }],
+ modelHistory: 'full',
+ now: () => ts,
+ });
+
+ const terminal = converted.events.filter((event) => event.actions?.endInvocation);
+ assert.partialDeepStrictEqual(terminal, [{ status: 'failed' }]);
+ assert.strictEqual(terminal[0]?.actions?.stateDelta?.failureClass, 'missing_terminal_event');
+ assert.partialDeepStrictEqual(converted.diagnostics, [{ code: 'synthesized_terminal_event' }]);
+ });
+});
+
describe('RuntimeEventActions projection coverage', () => {
for (const [field, sample] of Object.entries(ACTION_COVERAGE_SAMPLES)) {
test(`actions.${field} projects without an unclaimed-event diagnostic`, () => {
diff --git a/packages/runtime/src/runtime-event-backfill.ts b/packages/runtime/src/runtime-event-backfill.ts
index 9ff40070bb..a48b0c5e98 100644
--- a/packages/runtime/src/runtime-event-backfill.ts
+++ b/packages/runtime/src/runtime-event-backfill.ts
@@ -37,8 +37,7 @@ export type RuntimeEventBackfillDiagnosticCode =
| 'skipped_high_risk_message'
| 'skipped_provider_native_replay_gap'
| 'skipped_unmatched_tool_result'
- | 'skipped_unmatched_permission_decision'
- | 'skipped_unsafe_terminal_state';
+ | 'synthesized_terminal_event';
export interface RuntimeEventBackfillDiagnostic {
code: RuntimeEventBackfillDiagnosticCode;
@@ -194,14 +193,18 @@ export function backfillRuntimeEventsFromStoredMessages(
case 'tool_call': {
if (conversationTextOnly) break;
- if (message.providerExecuted === true && !replayableProviderToolUseIds.has(message.id)) {
+ // A provider-native call whose opaque output was not retained can never
+ // be replayed to a provider again, so it is converted hidden: the
+ // transcript keeps the card, and no model request is built from it.
+ const unreplayable =
+ message.providerExecuted === true && !replayableProviderToolUseIds.has(message.id);
+ if (unreplayable) {
diagnostics.push({
code: 'skipped_provider_native_replay_gap',
message:
'provider-native tool history requires the opaque provider output for lossless recovery',
detail: { messageId: message.id, toolUseId: message.id },
});
- break;
}
const stateDelta = toolCallStateDelta(message);
events.push({
@@ -210,6 +213,7 @@ export function backfillRuntimeEventsFromStoredMessages(
role: 'model',
author: 'agent',
...storedToolActivityIdentity(message),
+ ...(unreplayable ? { modelVisibility: 'hidden' as const } : {}),
content: {
kind: 'function_call',
id: message.id,
@@ -243,15 +247,18 @@ export function backfillRuntimeEventsFromStoredMessages(
case 'tool_result': {
if (conversationTextOnly) break;
- if (message.providerExecuted === true && message.providerOutput === undefined) {
- break;
- }
+ // Same rule as the call it answers: a result the provider cannot be
+ // shown again is kept as a transcript row and hidden from replay. A
+ // result whose call is not in this turn is hidden for the same reason —
+ // a lone result is not a request a provider would accept.
const call = safePriorToolCall(toolCalls, message);
+ const unreplayable =
+ !call || (message.providerExecuted === true && message.providerOutput === undefined);
if (!call) {
diagnostics.push({
code: 'skipped_unmatched_tool_result',
message:
- 'tool_result requires an earlier same-turn tool_call to recover RuntimeEvent function_response',
+ 'tool_result has no earlier same-turn tool_call, so its RuntimeEvent stays out of model replay',
detail: {
messageId: message.id,
toolUseId: message.toolUseId,
@@ -259,18 +266,18 @@ export function backfillRuntimeEventsFromStoredMessages(
turnId: input.run.turnId,
},
});
- break;
}
events.push({
...base,
id: newId(),
role: 'tool',
author: 'tool',
- ...storedToolActivityIdentity(call),
+ ...storedToolActivityIdentity(call ?? message),
+ ...(unreplayable ? { modelVisibility: 'hidden' as const } : {}),
content: {
kind: 'function_response',
id: message.toolUseId,
- name: call.toolName,
+ name: call?.toolName ?? '',
result: message.content,
isError: message.isError,
...(message.providerExecuted !== undefined
@@ -286,10 +293,10 @@ export function backfillRuntimeEventsFromStoredMessages(
refs: {
storedMessageId: message.id,
toolCallId: message.toolUseId,
- ...(call.parentToolCallId !== undefined
+ ...(call?.parentToolCallId !== undefined
? { parentToolCallId: call.parentToolCallId }
: {}),
- ...(call.parentOperationId !== undefined
+ ...(call?.parentOperationId !== undefined
? { parentOperationId: call.parentOperationId }
: {}),
},
@@ -297,23 +304,11 @@ export function backfillRuntimeEventsFromStoredMessages(
break;
}
- case 'permission_decision': {
+ // The decision names the tool it answered for, so it converts on its own
+ // evidence; a matching call in the same turn is confirmation, not a
+ // requirement.
+ case 'permission_decision':
if (conversationTextOnly) break;
- const call = safePriorToolCall(toolCalls, message);
- if (!call) {
- diagnostics.push({
- code: 'skipped_unmatched_permission_decision',
- message:
- 'permission_decision requires an earlier same-turn tool_call to recover RuntimeEvent permissionDecision',
- detail: {
- messageId: message.id,
- toolUseId: message.toolUseId,
- runId: input.run.runId,
- turnId: input.run.turnId,
- },
- });
- break;
- }
events.push({
...base,
id: newId(),
@@ -324,15 +319,19 @@ export function backfillRuntimeEventsFromStoredMessages(
permissionDecision: {
requestId: message.id,
decision: message.decision,
+ toolName: message.toolName,
...(message.rememberForTurn !== undefined
? { rememberForTurn: message.rememberForTurn }
: {}),
+ ...(message.reviewer !== undefined ? { reviewer: message.reviewer } : {}),
+ ...(message.rationale !== undefined ? { rationale: message.rationale } : {}),
+ ...(message.riskLevel !== undefined ? { riskLevel: message.riskLevel } : {}),
+ ...(message.hint !== undefined ? { hint: message.hint } : {}),
},
},
- refs: { storedMessageId: message.id, toolCallId: call.id },
+ refs: { storedMessageId: message.id, toolCallId: message.toolUseId },
});
break;
- }
case 'token_usage':
if (conversationTextOnly) break;
@@ -354,7 +353,11 @@ export function backfillRuntimeEventsFromStoredMessages(
});
break;
+ // Both are already accounted for elsewhere: the turn's ending becomes the
+ // terminal RuntimeEvent below, and a coordination record is the WorkHub's
+ // own durable proof, which no run ledger owns a copy of.
case 'turn_state':
+ case 'workhub_coordination':
break;
// A note that names a turn is that invocation's own fact, so it converts.
@@ -402,11 +405,8 @@ export function backfillRuntimeEventsFromStoredMessages(
newId,
now,
});
- if (terminal.event) {
- events.push(terminal.event);
- } else if (terminal.diagnostic) {
- diagnostics.push(terminal.diagnostic);
- }
+ if (terminal.event) events.push(terminal.event);
+ if (terminal.diagnostic) diagnostics.push(terminal.diagnostic);
return { events, diagnostics };
}
@@ -469,25 +469,30 @@ function terminalRuntimeEvent(input: {
now: () => number;
}): { event?: RuntimeEvent; diagnostic?: RuntimeEventBackfillDiagnostic } {
const turnState = latestTurnState(input.turnMessages);
- const status = terminalStatus(input.outcome, turnState);
- if (!status) {
- return {
- diagnostic: {
- code: 'skipped_unsafe_terminal_state',
+ const readStatus = terminalStatus(input.outcome, turnState);
+ // An invocation with no ending is not a legal ledger state, and leaving one
+ // open would strand the turn in recovery forever. Incomplete legacy evidence
+ // does not get to claim the turn completed, so it ends as the failure it
+ // actually was, marked so a reader can tell it apart from a recorded one.
+ const status = readStatus ?? 'failed';
+ const diagnostic: RuntimeEventBackfillDiagnostic | undefined = readStatus
+ ? undefined
+ : {
+ code: 'synthesized_terminal_event',
message:
- 'terminal RuntimeEvent was not recovered because legacy terminal evidence is incomplete',
+ 'terminal RuntimeEvent was synthesized because legacy terminal evidence is incomplete',
detail: {
runId: input.run.runId,
turnId: input.run.turnId,
declaredStatus: input.outcome?.status,
turnStatus: turnState?.status,
},
- },
- };
- }
+ };
const ts = turnState?.ts ?? input.outcome?.ts ?? input.now();
const failureClass =
- status === 'failed' ? (turnState?.errorClass ?? input.outcome?.failureClass) : undefined;
+ status === 'failed'
+ ? (turnState?.errorClass ?? input.outcome?.failureClass ?? 'missing_terminal_event')
+ : undefined;
const abortSource =
status === 'aborted'
? (turnState?.abortSource ??
@@ -516,6 +521,7 @@ function terminalRuntimeEvent(input: {
},
...(turnState ? { refs: { storedMessageId: turnState.id } } : {}),
},
+ ...(diagnostic ? { diagnostic } : {}),
};
}
diff --git a/packages/runtime/src/runtime-event-read-model.ts b/packages/runtime/src/runtime-event-read-model.ts
index 914b714ec0..4dacb25268 100644
--- a/packages/runtime/src/runtime-event-read-model.ts
+++ b/packages/runtime/src/runtime-event-read-model.ts
@@ -1019,6 +1019,9 @@ function projectPermissionDecision(
);
return false;
}
+ // The prompt's own wording when the request survived, and the decision's copy
+ // of it when the decision is all that is left.
+ const hint = request?.hint ?? decision.hint;
messages.push({
type: 'permission_decision',
id: decision.requestId,
@@ -1033,7 +1036,7 @@ function projectPermissionDecision(
...(decision.reviewer !== undefined ? { reviewer: decision.reviewer } : {}),
...(decision.rationale !== undefined ? { rationale: decision.rationale } : {}),
...(decision.riskLevel !== undefined ? { riskLevel: decision.riskLevel } : {}),
- ...(request?.hint !== undefined ? { hint: request.hint } : {}),
+ ...(hint !== undefined ? { hint } : {}),
});
return true;
}
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@maka.apache.org
For additional commands, e-mail: commits-help@maka.apache.org