throughline 0.4.8 → 0.4.10

package/src/codex-handoff.mjs

@@ -6,6 +6,8 @@
  * can consume it.
  */
 
+import { groupL3ByTurn, buildPartsSummary } from './l3-summary.mjs';
+
 export const THROUGHLINE_HANDOFF_SCHEMA_VERSION = 1;
 export const DEFAULT_CODEX_HANDOFF_DETAIL_REF_LIMIT = 20;
 export const DEFAULT_CODEX_HANDOFF_RECENT_BODY_LIMIT = 8;
@@ -76,14 +78,46 @@ function truncateText(text, maxChars) {
   };
 }
 
-function uniqueDetailRefsByCommand(refs) {
-  const seen = new Set();
+/**
+ * 追加: Codex 用 inline detail suffix の組み立て補助。
+ * - L1: bodyTime (= 元ターン時刻) を行頭に出して `本文` 起点の詳細を案内
+ * - L2: ターン内の最終 role 行 (通常 user→assistant の assistant) にだけ suffix を貼る
+ *   (同じ turn_number に紐付く L3 を user / assistant 両方に貼る冗長を回避)
+ */
+function appendL1Lines(lines, l1Summaries, l3ByTurn) {
+  const l1Lines = [];
+  for (const row of l1Summaries) {
+    if (!row.summary || row.summary === '(no content)') continue;
+    const summary = singleLine(row.summary);
+    const key = `${row.originSessionId}\x00${row.turnNumber}`;
+    const displayTime = row.bodyTime ?? row.time;
+    const partCounts = l3ByTurn.get(key)?.partCounts ?? new Map();
+    // bodyTime が無い defensive ケース (元 body が消えている等) は detail 解決できないので
+    // suffix を付けない (誤誘導しない)。
+    const suffix = row.bodyTime != null
+      ? buildPartsSummary(partCounts, { includeBody: true })
+      : '';
+    l1Lines.push(`[${displayTime}] [${row.role}] ${summary}${suffix}`);
+  }
+  return l1Lines;
+}
+
+function appendL2Lines(bodies, l3ByTurn) {
+  const lastIdxPerTurn = new Map();
+  for (let i = 0; i < bodies.length; i += 1) {
+    const r = bodies[i];
+    if (!r.text) continue;
+    lastIdxPerTurn.set(`${r.originSessionId}\x00${r.turnNumber}`, i);
+  }
   const out = [];
-  for (const ref of refs) {
-    const key = ref.detailCommand;
-    if (seen.has(key)) continue;
-    seen.add(key);
-    out.push(ref);
+  for (let i = 0; i < bodies.length; i += 1) {
+    const r = bodies[i];
+    if (!r.text) continue;
+    const key = `${r.originSessionId}\x00${r.turnNumber}`;
+    const isLastOfTurn = lastIdxPerTurn.get(key) === i;
+    const partCounts = isLastOfTurn ? (l3ByTurn.get(key)?.partCounts ?? new Map()) : new Map();
+    const suffix = buildPartsSummary(partCounts);
+    out.push({ row: r, suffix });
   }
   return out;
 }
@@ -93,6 +127,8 @@ export function renderCodexActiveWorkContext(record) {
     throw new Error('renderCodexActiveWorkContext: record is required');
   }
 
+  const l3ByTurn = groupL3ByTurn(record.references.l3);
+
   const lines = [];
   lines.push('## Throughline: Active Work Context');
   lines.push('');
@@ -109,6 +145,10 @@ export function renderCodexActiveWorkContext(record) {
   lines.push(
     'Do not treat every older line as still-current truth. Prefer the latest actionable state.',
   );
+  lines.push(
+    'For each L1/L2 entry, the time prefix `[HH:MM:SS]` can be passed to ' +
+      '`throughline detail HH:MM:SS` (run via shell) to retrieve the full body and L3 detail of that turn.',
+  );
   lines.push('');
   lines.push('### Source');
   lines.push(`Throughline session: ${record.session.id}`);
@@ -130,32 +170,23 @@ export function renderCodexActiveWorkContext(record) {
   }
 
   if (record.memory.l1Summaries.length > 0) {
-    lines.push('');
-    lines.push('### L1 Summaries');
-    for (const row of record.memory.l1Summaries) {
-      if (!row.summary || row.summary === '(no content)') continue;
-      lines.push(`[${row.time}] [${row.role}] ${row.summary.replace(/\n+/g, ' ').trim()}`);
+    const l1Lines = appendL1Lines(lines, record.memory.l1Summaries, l3ByTurn);
+    if (l1Lines.length > 0) {
+      lines.push('');
+      lines.push('### L1 Summaries');
+      lines.push(...l1Lines);
     }
   }
 
   if (record.memory.recentBodies.length > 0) {
-    lines.push('');
-    lines.push('### Active Work Thread (L2)');
-    lines.push('Entries are oldest-to-newest; later entries may supersede earlier hypotheses.');
-    for (const row of record.memory.recentBodies) {
-      if (!row.text) continue;
-      lines.push(`[${row.time}] [${row.role}] ${row.text}`);
-    }
-  }
-
-  if (record.references.l3.length > 0) {
-    lines.push('');
-    lines.push('### Detail References');
-    lines.push(
-      'Use these only when L1/L2 are insufficient. Run the command locally; do not guess missing tool output.',
-    );
-    for (const ref of record.references.l3) {
-      lines.push(`- ${ref.kind}:${ref.toolName} turn ${ref.turnNumber}: ${ref.detailCommand}`);
+    const l2 = appendL2Lines(record.memory.recentBodies, l3ByTurn);
+    if (l2.length > 0) {
+      lines.push('');
+      lines.push('### Active Work Thread (L2)');
+      lines.push('Entries are oldest-to-newest; later entries may supersede earlier hypotheses.');
+      for (const { row, suffix } of l2) {
+        lines.push(`[${row.time}] [${row.role}] ${row.text}${suffix}`);
+      }
     }
   }
 
@@ -163,7 +194,7 @@ export function renderCodexActiveWorkContext(record) {
   lines.push('### Continuation Instruction');
   lines.push(
     'Continue from the latest actionable state represented above. Preserve user instructions and repository constraints. ' +
-      'If details are missing, inspect local files or Throughline detail references before acting.',
+      'If details are missing, run `throughline detail HH:MM:SS` on the relevant entry before acting.',
   );
 
   return lines.join('\n');
@@ -172,6 +203,9 @@ export function renderCodexActiveWorkContext(record) {
 export function renderCodexNewThreadHandoff(
   record,
   {
+    // 旧 Detail References セクション用の制限。L3 が各 L1/L2 行末尾の
+    // `(詳細：…)` suffix に集約された後は描画には影響しないが、CLI flags との
+    // 互換維持のためバリデーションだけ残す。
     maxDetailRefs = DEFAULT_CODEX_HANDOFF_DETAIL_REF_LIMIT,
     maxRecentBodies = DEFAULT_CODEX_HANDOFF_RECENT_BODY_LIMIT,
     maxBodyChars = DEFAULT_CODEX_HANDOFF_BODY_MAX_CHARS,
@@ -222,13 +256,15 @@ export function renderCodexNewThreadHandoff(
     }
   }
 
+  const l3ByTurn = groupL3ByTurn(record.references.l3);
+
   if (record.memory.l1Summaries.length > 0) {
-    lines.push('');
-    lines.push('### L1 Memory Summaries');
-    lines.push('Oldest-to-newest; use later entries when summaries disagree.');
-    for (const row of record.memory.l1Summaries) {
-      if (!row.summary || row.summary === '(no content)') continue;
-      lines.push(`[${row.time}] [${row.role}] ${singleLine(row.summary)}`);
+    const l1Lines = appendL1Lines(lines, record.memory.l1Summaries, l3ByTurn);
+    if (l1Lines.length > 0) {
+      lines.push('');
+      lines.push('### L1 Memory Summaries');
+      lines.push('Oldest-to-newest; use later entries when summaries disagree.');
+      lines.push(...l1Lines);
     }
   }
 
@@ -242,45 +278,33 @@ export function renderCodexNewThreadHandoff(
     lines.push(
       `Long entries are truncated for handoff; full context: throughline codex-resume --session ${record.session.id}`,
     );
+    lines.push(
+      'For each entry, the `[HH:MM:SS]` time prefix can be passed to ' +
+        '`throughline detail HH:MM:SS` (run via shell) to retrieve full body + L3 of that turn.',
+    );
     if (shownBodies.length === 0) {
       lines.push(`${bodies.length} active L2 entries available; omitted from this fresh-thread handoff.`);
     } else if (omittedBodies > 0) {
       lines.push(`Showing latest ${shownBodies.length} of ${bodies.length} active L2 entries; ${omittedBodies} older omitted.`);
     }
-    for (const row of shownBodies) {
-      if (!row.text) continue;
+    const l2 = appendL2Lines(shownBodies, l3ByTurn);
+    for (const { row, suffix } of l2) {
       const body = truncateText(row.text, maxBodyChars);
-      lines.push(`[${row.time}] [${row.role}] ${body.text}`);
+      lines.push(`[${row.time}] [${row.role}] ${body.text}${suffix}`);
       if (body.truncated) {
         lines.push(`[entry truncated to ${maxBodyChars} chars]`);
       }
     }
   }
 
-  if (record.references.l3.length > 0) {
-    const refs = uniqueDetailRefsByCommand(record.references.l3);
-    const shown = maxDetailRefs === 0 ? [] : refs.slice(-maxDetailRefs);
-    const omitted = refs.length - shown.length;
-    lines.push('');
-    lines.push('### Detail References');
-    lines.push('L3 bodies are not pasted here. Use local detail commands only when L1/L2 are insufficient.');
-    if (shown.length === 0) {
-      lines.push(`${refs.length} detail commands available; omitted from this fresh-thread handoff.`);
-    } else {
-      if (omitted > 0) {
-        lines.push(`Showing latest ${shown.length} of ${refs.length} detail commands; ${omitted} older omitted.`);
-      }
-      for (const ref of shown) {
-        lines.push(`- ${ref.kind}:${ref.toolName} turn ${ref.turnNumber}: ${ref.detailCommand}`);
-      }
-    }
-  }
+  // Detail References セクションは廃止 (各 L1/L2 行末尾の `(詳細：…)` suffix で
+  // 同じ情報が turn 単位に集約されるため重複)。
 
   lines.push('');
   lines.push('### Start Instruction');
   lines.push(
     'Continue from the latest actionable state above. Preserve user instructions and repository constraints. ' +
-      'Do not mutate the original Codex thread; inspect local files or detail references before acting when context is missing.',
+      'Do not mutate the original Codex thread; run `throughline detail HH:MM:SS` on the relevant entry before acting when context is missing.',
   );
 
   return lines.join('\n');

package/src/codex-handoff.test.mjs

@@ -28,8 +28,28 @@ function makeRecord() {
     memory: {
       inflightMemo: 'Next: implement projection',
       latestThinking: [{ time: '12:00:03', text: 'latest hidden reasoning note' }],
-      l1Summaries: [{ time: '12:00:01', role: 'assistant', summary: 'old summary' }],
-      recentBodies: [{ time: '12:00:02', role: 'assistant', text: 'recent body' }],
+      l1Summaries: [
+        {
+          time: '12:00:01',
+          role: 'assistant',
+          summary: 'old summary',
+          originSessionId: 'old',
+          turnNumber: 1,
+          // bodyTime は handoff-record が bodies テーブル MIN(created_at) から付ける。
+          // test では原ターン時刻として固定値を入れる。
+          bodyTime: '11:59:50',
+          bodyTimeMs: null,
+        },
+      ],
+      recentBodies: [
+        {
+          time: '12:00:02',
+          role: 'assistant',
+          text: 'recent body',
+          originSessionId: 'old',
+          turnNumber: 2,
+        },
+      ],
     },
     references: {
       l3: [
@@ -93,28 +113,32 @@ test('toThroughlineHandoffBlock: rejects missing record', () => {
   assert.throws(() => toThroughlineHandoffBlock(null), /record is required/);
 });
 
-test('renderCodexActiveWorkContext: renders persisted memory as active work context', () => {
+test('renderCodexActiveWorkContext: renders persisted memory with inline (詳細：…) suffix', () => {
   const text = renderCodexActiveWorkContext(makeRecord());
 
   assert.match(text, /## Throughline: Active Work Context/);
   assert.match(text, /### Reading Contract/);
   assert.match(text, /current-task context for continuation/);
+  // 詳細取得方法 (throughline detail HH:MM:SS) はヘッダーで announce 済み
+  assert.match(text, /throughline detail HH:MM:SS/);
   assert.match(text, /Throughline session: sess-1/);
   assert.match(text, /Source agent: claude/);
   assert.match(text, /### In-flight Memo\nNext: implement projection/);
   assert.match(text, /### Latest Thinking/);
   assert.match(text, /latest hidden reasoning note/);
   assert.match(text, /### L1 Summaries/);
-  assert.match(text, /old summary/);
+  // L1 行頭は body 時刻 (bodyTime)、suffix は `本文` を含む (元 body が引ける案内)
+  assert.match(text, /\[11:59:50\] \[assistant\] old summary \(詳細：本文\)/);
   assert.match(text, /### Active Work Thread \(L2\)/);
-  assert.match(text, /\[12:00:02\] \[assistant\] recent body/);
-  assert.match(text, /### Detail References/);
-  assert.match(text, /throughline detail 12:00:01/);
+  // L2 末尾には L3 集約 suffix (turn 2 の Bash 入力 1 件 → "Bash")
+  assert.match(text, /\[12:00:02\] \[assistant\] recent body \(詳細：Bash\)/);
+  // 旧 `### Detail References` セクションは廃止
+  assert.ok(!text.includes('### Detail References'));
   assert.match(text, /### Continuation Instruction/);
   assert.match(text, /Continue from the latest actionable state/);
 });
 
-test('renderCodexNewThreadHandoff: renders concise fresh-thread handoff context', () => {
+test('renderCodexNewThreadHandoff: renders concise fresh-thread handoff context with inline suffix', () => {
   const record = makeRecord();
   const text = renderCodexNewThreadHandoff(record);
 
@@ -126,11 +150,19 @@ test('renderCodexNewThreadHandoff: renders concise fresh-thread handoff context'
   assert.match(text, /### In-flight Memo\nNext: implement projection/);
   assert.match(text, /### L1 Memory Summaries/);
   assert.match(text, /### Recent Active Thread \(L2\)/);
-  assert.match(text, /throughline detail 12:00:01/);
+  // 詳細取得方法はヘッダーで announce
+  assert.match(text, /throughline detail HH:MM:SS/);
+  // L2 行に inline suffix
+  assert.match(text, /\[12:00:02\] \[assistant\] recent body \(詳細：Bash\)/);
+  // 旧 `### Detail References` セクションは廃止
+  assert.ok(!text.includes('### Detail References'));
   assert.match(text, /Do not mutate the original Codex thread/);
 });
 
-test('renderCodexNewThreadHandoff: caps detail references for pasteable new-thread prompts', () => {
+test('renderCodexNewThreadHandoff: maxDetailRefs option is accepted but no longer renders a Detail References section', () => {
+  // 旧 ### Detail References セクションは廃止された。CLI flag 互換のため
+  // maxDetailRefs はバリデーションだけ通り、描画には影響しない (per-line suffix で
+  // turn 単位に集約済みのため)。
   const record = makeRecord();
   record.references.l3 = [
     {
@@ -138,26 +170,20 @@ test('renderCodexNewThreadHandoff: caps detail references for pasteable new-thre
       toolName: 'Bash',
       sourceId: 'toolu_1',
       originSessionId: 'old',
-      turnNumber: 1,
-      createdAt: 1000,
-      detailCommand: 'throughline detail 12:00:01',
-    },
-    {
-      kind: 'tool_output',
-      toolName: 'Bash',
-      sourceId: 'toolu_2',
-      originSessionId: 'old',
       turnNumber: 2,
-      createdAt: 2000,
+      createdAt: 1000,
       detailCommand: 'throughline detail 12:00:02',
     },
   ];
 
   const text = renderCodexNewThreadHandoff(record, { maxDetailRefs: 1 });
 
-  assert.match(text, /Showing latest 1 of 2 detail commands; 1 older omitted/);
-  assert.doesNotMatch(text, /throughline detail 12:00:01/);
-  assert.match(text, /throughline detail 12:00:02/);
+  assert.ok(!text.includes('### Detail References'));
+  assert.ok(!text.includes('detail commands; '));
+  // ヘッダーの placeholder のみで、行末に固有時刻の throughline detail は出ない
+  assert.ok(!text.includes('throughline detail 12:00:02'));
+  // 代わりに inline suffix で turn 集約された情報が出る
+  assert.match(text, /\(詳細：Bash\)/);
 });
 
 test('renderCodexNewThreadHandoff: caps recent L2 entries and long bodies', () => {
@@ -180,15 +206,22 @@ test('renderCodexNewThreadHandoff: caps recent L2 entries and long bodies', () =
   assert.doesNotMatch(text, /long tail/);
 });
 
-test('renderCodexNewThreadHandoff: deduplicates repeated detail commands', () => {
+test('renderCodexNewThreadHandoff: aggregates same-turn L3 into a single (詳細：…) suffix on the assistant line', () => {
+  // 旧版は同一 detail command の dedup (uniqueDetailRefsByCommand) を独立 Detail
+  // References セクションで行っていた。新版は groupL3ByTurn が turn 単位に集約し、
+  // L2 ターンの最終 role 行 (assistant) にだけ inline suffix を付ける。
   const record = makeRecord();
+  record.memory.recentBodies = [
+    { time: '12:00:02', role: 'user', text: 'user body', originSessionId: 'old', turnNumber: 2 },
+    { time: '12:00:02', role: 'assistant', text: 'assistant body', originSessionId: 'old', turnNumber: 2 },
+  ];
   record.references.l3 = [
     {
       kind: 'tool_input',
       toolName: 'Bash',
       sourceId: 'toolu_1',
       originSessionId: 'old',
-      turnNumber: 1,
+      turnNumber: 2,
       createdAt: 1000,
       detailCommand: 'throughline detail 12:00:01',
     },
@@ -197,7 +230,7 @@ test('renderCodexNewThreadHandoff: deduplicates repeated detail commands', () =>
       toolName: 'Bash',
       sourceId: 'toolu_2',
       originSessionId: 'old',
-      turnNumber: 1,
+      turnNumber: 2,
       createdAt: 1000,
       detailCommand: 'throughline detail 12:00:01',
     },
@@ -205,8 +238,16 @@ test('renderCodexNewThreadHandoff: deduplicates repeated detail commands', () =>
 
   const text = renderCodexNewThreadHandoff(record);
 
-  assert.equal(text.match(/throughline detail 12:00:01/g)?.length, 1);
-  assert.doesNotMatch(text, /Showing latest 1 of 2/);
+  // user 行には suffix が出ない (重複排除)
+  const userLine = text.split('\n').find((l) => l.includes('user body'));
+  assert.ok(userLine);
+  assert.ok(!userLine.includes('詳細：'));
+
+  // assistant 行 (turn 内最終 role) に suffix が 1 つだけ
+  const assistantLine = text.split('\n').find((l) => l.includes('assistant body'));
+  assert.ok(assistantLine);
+  // tool_input + tool_output の 1:1 ペアは tool 名 (Bash) で 1 つに集約される
+  assert.match(assistantLine, /\(詳細：Bash\)$/);
 });
 
 test('toCodexDeveloperMessageItem: wraps active work context as a developer message item', () => {

package/src/codex-resume.test.mjs

@@ -85,7 +85,12 @@ test('codex-resume prints active-work context text for explicit Codex session',
     assert.match(result.stdout, /Source agent: codex/);
     assert.match(result.stdout, /older codex summary/);
     assert.match(result.stdout, /latest codex body/);
-    assert.match(result.stdout, /throughline detail \d\d:\d\d:\d\d/);
+    // 新仕様: 詳細取得方法は header の placeholder で announce
+    assert.match(result.stdout, /throughline detail HH:MM:SS/);
+    // 新仕様: L2 行末尾に inline `(詳細：…)` suffix (turn 2 の tool_input=exec_command 1 件)
+    assert.match(result.stdout, /latest codex body \(詳細：exec_command\)/);
+    // 旧 `### Detail References` セクションは廃止されている
+    assert.ok(!result.stdout.includes('### Detail References'));
   } finally {
     rmSync(project, { recursive: true, force: true });
     rmSync(home, { recursive: true, force: true });
@@ -142,7 +147,11 @@ test('codex-resume can print a fresh-thread handoff prompt', async () => {
     assert.match(result.stdout, /latest/);
     assert.match(result.stdout, /\[entry truncated to 6 chars\]/);
     assert.doesNotMatch(result.stdout, /codex body/);
-    assert.match(result.stdout, /1 detail commands available; omitted from this fresh-thread handoff/);
+    // 新仕様: 旧 Detail References セクションは廃止されたので「N detail commands
+    // available; omitted」メッセージは出ない。--max-detail-refs はバリデーションだけ
+    // 残る no-op フラグになっている。
+    assert.ok(!result.stdout.includes('### Detail References'));
+    assert.ok(!result.stdout.includes('detail commands available; omitted'));
     assert.doesNotMatch(result.stdout, /^\{/);
   } finally {
     rmSync(project, { recursive: true, force: true });

package/src/handoff-record.mjs

@@ -123,6 +123,41 @@ function loadL1Summaries(db, { sessionId, excludeOriginId, bodyRows }) {
   return all.filter((s) => !bodySet.has(`${s.origin_session_id}\x00${s.turn_number}`));
 }
 
+/**
+ * L1 ターンの元 body 時刻 (created_at MIN) を batch lookup する。
+ * skeletons.created_at は要約実行時刻なので `throughline detail HH:MM:SS` 解決に
+ * 使えない。元 body は trim 後も bodies テーブルに残っているのが通常で、
+ * (session_id, origin_session_id, turn_number) で MIN を引けば原ターンの時刻が得られる。
+ */
+function loadL1BodyTimes(db, sessionId, l1Rows) {
+  if (!l1Rows || l1Rows.length === 0) return new Map();
+  const tuples = l1Rows
+    .filter((r) => r.origin_session_id != null && r.turn_number != null)
+    .map((r) => [r.origin_session_id, Number(r.turn_number)]);
+  if (tuples.length === 0) return new Map();
+
+  const placeholders = tuples.map(() => '(?, ?, ?)').join(', ');
+  const params = tuples.flatMap(([origin, turn]) => [sessionId, origin, turn]);
+
+  const out = new Map();
+  try {
+    const rows = db
+      .prepare(
+        `SELECT origin_session_id, turn_number, MIN(created_at) AS created_at
+         FROM bodies
+         WHERE (session_id, origin_session_id, turn_number) IN (VALUES ${placeholders})
+         GROUP BY origin_session_id, turn_number`,
+      )
+      .all(...params);
+    for (const r of rows) {
+      out.set(`${r.origin_session_id}\x00${r.turn_number}`, r.created_at);
+    }
+  } catch {
+    // body が無い defensive ケースでは bodyTime null のまま (renderer 側で skeleton 時刻 fallback)
+  }
+  return out;
+}
+
 function loadLatestThinking(db, { sessionId, excludeOriginId }) {
   const hasExclude = Boolean(excludeOriginId);
   const latestQuery = hasExclude
@@ -234,6 +269,7 @@ export function buildHandoffRecord(
   }
 
   const l3References = loadL3References(db, { sessionId, bodyRows });
+  const l1BodyTimes = loadL1BodyTimes(db, sessionId, l1Rows);
   const originSessionIds = distinctOriginSessionIds(bodyRows, l1Rows, thinkingRows);
 
   return {
@@ -263,14 +299,21 @@ export function buildHandoffRecord(
         time: formatTime(r.created_at),
         sourceId: r.source_id ?? null,
       })),
-      l1Summaries: l1Rows.map((r) => ({
-        originSessionId: r.origin_session_id,
-        turnNumber: r.turn_number,
-        role: r.role,
-        summary: r.summary,
-        createdAt: r.created_at,
-        time: formatTime(r.created_at),
-      })),
+      l1Summaries: l1Rows.map((r) => {
+        const bodyTimeMs = l1BodyTimes.get(`${r.origin_session_id}\x00${r.turn_number}`);
+        return {
+          originSessionId: r.origin_session_id,
+          turnNumber: r.turn_number,
+          role: r.role,
+          summary: r.summary,
+          createdAt: r.created_at,
+          time: formatTime(r.created_at),
+          // 元ターンの body 時刻。`throughline detail HH:MM:SS` 解決に使える時刻。
+          // body が無い defensive ケースでは null。
+          bodyTimeMs: bodyTimeMs ?? null,
+          bodyTime: bodyTimeMs != null ? formatTime(bodyTimeMs) : null,
+        };
+      }),
       recentBodies: bodyRows.map((r) => ({
         originSessionId: r.origin_session_id,
         turnNumber: r.turn_number,

package/src/l3-summary.mjs

@@ -0,0 +1,72 @@
+/**
+ * L3 reference の表示集約ヘルパー (resume-context / codex-handoff 共通)
+ *
+ * 各 L1 / L2 行末尾に付ける `(詳細：…)` suffix の組み立てを担当する。
+ * - hook 出力 (system) は noise なので suffix から除外する
+ * - tool_input + tool_output は 1:1 なので tool 名 (例: Bash) で 1 つに集約する
+ *   (count は tool_input 側だけで数える)
+ * - mcp__ ツール名は末尾の関数名だけに短縮する (フルパスは namespace noise)
+ * - 件数は >1 のときだけ ` ×N` で表示
+ */
+
+/**
+ * MCP ツール名 (`mcp__plugin_..._playwright__browser_navigate`) を末尾の関数名
+ * (`browser_navigate`) だけに短縮する。最後の `__` 以降を返す。
+ */
+export function shortenMcpToolName(toolName) {
+  if (typeof toolName !== 'string') return toolName ?? 'tool';
+  if (!toolName.startsWith('mcp__')) return toolName;
+  const idx = toolName.lastIndexOf('__');
+  return idx >= 0 && idx + 2 < toolName.length ? toolName.slice(idx + 2) : toolName;
+}
+
+/**
+ * L3 kind + tool_name を AI が読みやすい日本語ラベルにする。
+ * null を返した kind は suffix からスキップする (noise / 二重カウント回避)。
+ */
+export function localizeL3Part(kind, toolName) {
+  if (kind === 'thinking') return '思考';
+  if (kind === 'tool_input') return shortenMcpToolName(toolName);
+  if (kind === 'tool_output') return null;
+  if (kind === 'system') return null;
+  if (kind === 'image') return '画像';
+  return kind;
+}
+
+/**
+ * L3 references を `(originSessionId, turnNumber)` でグルーピングし、
+ * 表示ラベル (Bash / 思考 / 画像 など) ごとの件数を保つ。
+ * Map の挿入順は created_at ASC のままなので、自然な発生順に並ぶ。
+ */
+export function groupL3ByTurn(l3Refs) {
+  const map = new Map();
+  for (const ref of l3Refs) {
+    if (ref.originSessionId == null || ref.turnNumber == null) continue;
+    const turnKey = `${ref.originSessionId}\x00${ref.turnNumber}`;
+    let entry = map.get(turnKey);
+    if (!entry) {
+      entry = { partCounts: new Map() };
+      map.set(turnKey, entry);
+    }
+    const label = localizeL3Part(ref.kind, ref.toolName);
+    if (label == null) continue;
+    entry.partCounts.set(label, (entry.partCounts.get(label) ?? 0) + 1);
+  }
+  return map;
+}
+
+/**
+ * 1 ターン分の `(詳細：…)` suffix 文字列を組み立てる。
+ * - L1 の場合は `本文` を先頭に置き「summary を超えた full body が引ける」ことを示す
+ * - L2 の場合は body 自体は行内にあるので L3 部品だけ列挙
+ * - 何も無いなら空文字 (suffix 自体を出さない)
+ */
+export function buildPartsSummary(partCounts, { includeBody = false } = {}) {
+  const parts = [];
+  if (includeBody) parts.push('本文');
+  for (const [label, count] of partCounts) {
+    parts.push(count > 1 ? `${label} ×${count}` : label);
+  }
+  if (parts.length === 0) return '';
+  return ` (詳細：${parts.join(', ')})`;
+}