@geraldmaron/construct 1.0.3 → 1.0.5

package/lib/prompt-composer.js

@@ -8,8 +8,12 @@
  * NEW contract (no backward compat):
  *   { metadata, fragments, system, messages, staticEndIndex, totalTokens }
  *
- * Fragment order: core → role-flavor → task-context → learned-patterns → task-packet → context-digest → host-constraints
- * learned-patterns is inserted before the task packet so agents see what has been learned before reading the specific task.
+ * Fragment order: core → role-flavor → model-profile → task-context → learned-patterns → task-packet → context-digest → strategy → host-constraints
+ * strategy is injected after context-digest so agents have strategic grounding before learned-patterns affect framing.
+ *
+ * Workspace-type overlay auto-selection: when workspaceType is passed, the matching role overlay
+ * is selected automatically (e.g. workspaceType='platform' → product-manager.platform overlay)
+ * unless roleFlavors explicitly overrides it.
  */
 import crypto from 'node:crypto';
 import fs from 'node:fs';
@@ -17,29 +21,45 @@ import { homedir } from 'node:os';
 import path from 'node:path';
 
 import { buildContextDigest, readContextState } from './context-state.mjs';
-import { resolveExecutionContractModelMetadata, selectModelTierForWorkCategory } from './model-router.mjs';
+import {
+  MODEL_OPERATING_PROFILES,
+  resolveExecutionContractModelMetadata,
+  resolveModelOperatingProfile,
+  selectModelTierForWorkCategory,
+} from './model-router.mjs';
 import { searchObservations } from './observation-store.mjs';
 import { routeRequest } from './orchestration-policy.mjs';
 import { resolvePromptEntry, resolvePromptMetadata } from './prompt-metadata.mjs';
 import { readRoleFile } from './role-preload.mjs';
 import { estimateTokens, estimatePromptTokens, estimateTokensSync } from './token-engine.js';
+import { cxDir } from './paths.mjs';
+import { getStrategyDigestSync } from './strategy-store.mjs';
 
-// Token limits (replacing char limits)
-const LEARNED_PATTERNS_TOKEN_LIMIT = 200;
-const MAX_OBSERVATIONS = 3; // matched to token budget
-const MAX_CONTEXT_TOKENS = 3000; // total prompt token budget
+const MAX_OBSERVATIONS = 3;
 
 // Priority tiers (1 = never drop, 5 = drop first)
 const PRIORITY = {
   'core': 1,
   'task-packet': 1,
   'role-flavor': 2,
+  'model-profile': 2,
   'context-digest': 3,
+  'strategy': 3,
   'learned-patterns': 4,
   'host-constraints': 5,
 };
 
+// workspaceType → roleFlavors auto-selection when caller doesn't override
+const WORKSPACE_FLAVOR_MAP = {
+  platform: { productManager: 'platform', architect: 'platform', engineer: 'platform' },
+  enterprise: { productManager: 'enterprise', architect: 'enterprise' },
+  'ai-product': { productManager: 'ai-product', architect: 'ai-systems' },
+  growth: { productManager: 'growth' },
+  product: {},
+};
+
 const AGENT_FLAVOR_MAP = {
+  engineer: { classifierKey: 'engineer', rolePrefix: 'engineer' },
   architect: { classifierKey: 'architect', rolePrefix: 'architect' },
   'product-manager': { classifierKey: 'productManager', rolePrefix: 'product-manager' },
   qa: { classifierKey: 'qa', rolePrefix: 'qa' },
@@ -48,6 +68,18 @@ const AGENT_FLAVOR_MAP = {
   'data-engineer': { classifierKey: 'dataEngineer', rolePrefix: 'data-engineer' },
 };
 
+// Merge workspaceType-derived overlays with explicit roleFlavors. Explicit always wins.
+function resolveRoleFlavors(roleFlavors, workspaceType, shortName) {
+  const workspaceDefaults = workspaceType ? (WORKSPACE_FLAVOR_MAP[workspaceType] ?? {}) : {};
+  if (!roleFlavors && !workspaceType) return null;
+  return { ...workspaceDefaults, ...(roleFlavors || {}) };
+}
+
+// Synchronous strategy digest for prompt injection — reads all scope files from the strategy directory.
+function buildStrategyBlock({ tokenLimit = 400 } = {}) {
+  return getStrategyDigestSync();
+}
+
 function compactTokens(text, tokenLimit = 300, { modelId = 'default' } = {}) {
   if (!text) return '';
   const normalized = String(text).trim();
@@ -65,7 +97,13 @@ function readPromptBody(promptFile, rootDir) {
   return fs.readFileSync(filePath, 'utf8').trim();
 }
 
-function buildLearnedPatternsBlock(agentName, { intent = null, workCategory = null, project = null, modelId = 'default' } = {}) {
+function buildLearnedPatternsBlock(agentName, {
+  intent = null,
+  workCategory = null,
+  project = null,
+  modelId = 'default',
+  tokenLimit = MODEL_OPERATING_PROFILES.balanced.learnedPatternsTokens,
+} = {}) {
   try {
     const rootDir = homedir();
     const query = [agentName, intent, workCategory].filter(Boolean).join(' ');
@@ -93,7 +131,7 @@ function buildLearnedPatternsBlock(agentName, { intent = null, workCategory = nu
       const prefix = obs.category === 'anti-pattern' ? '⚠ ' : obs.category === 'decision' ? '✓ ' : '• ';
       const line = `${prefix}${obs.summary}`;
       const lineTokens = estimateTokensSync(line + '\n', { modelId });
-      if (tokens + lineTokens > LEARNED_PATTERNS_TOKEN_LIMIT) break;
+      if (tokens + lineTokens > tokenLimit) break;
       lines.push(line);
       tokens += lineTokens + 1;
     }
@@ -144,42 +182,68 @@ export function composePrompt(agentName, {
   intent = null,
   workCategory = null,
   roleFlavors = null,
+  workspaceType = null,
   project = null,
   injectLearnedPatterns = true,
   modelId = 'default',
+  executionContractModel = null,
 } = {}) {
   const entry = resolvePromptEntry(agentName, { rootDir, registry });
   if (!entry?.promptFile) return { metadata: {}, fragments: [], system: '', messages: [], staticEndIndex: -1, totalTokens: 0 };
 
   const metadata = resolvePromptMetadata(agentName, { rootDir, registry });
   const fragments = [];
+  const selectedProfile = resolveModelOperatingProfile({
+    envValues: executionContractModel?.profile ? { CONSTRUCT_MODEL_PROFILE: executionContractModel.profile.id } : {},
+    selectedModel: executionContractModel?.selectedModel ?? modelId,
+  });
 
-  // 1. Core (priority 1 — never dropped)
   fragments.push({ type: 'core', priority: PRIORITY['core'], label: entry.name, content: readPromptBody(entry.promptFile, rootDir), tokenBudget: null });
 
-  // 2. Role flavor overlay (priority 2)
   const shortName = String(agentName).replace(/^cx-/, '');
   const flavorMapping = AGENT_FLAVOR_MAP[shortName];
-  if (flavorMapping && roleFlavors) {
-    const flavor = roleFlavors[flavorMapping.classifierKey];
+
+  // When workspaceType is provided and roleFlavors doesn't already specify this agent's flavor,
+  // auto-select the matching overlay so agents get domain guidance without requiring explicit caller config.
+  const effectiveRoleFlavors = resolveRoleFlavors(roleFlavors, workspaceType, shortName);
+
+  if (flavorMapping && effectiveRoleFlavors) {
+    const flavor = effectiveRoleFlavors[flavorMapping.classifierKey];
     if (flavor) {
       const overlayBody = readRoleFile(rootDir, `${flavorMapping.rolePrefix}.${flavor}`, {
         source: 'prompt-composer',
         callerContext: agentName,
       });
       if (overlayBody) {
+        const overlayContent = selectedProfile.preferCompressedRoleGuidance
+          ? compactTokens(overlayBody, selectedProfile.roleFlavorTokens, { modelId })
+          : overlayBody;
         fragments.push({
           type: 'role-flavor',
           priority: PRIORITY['role-flavor'],
           label: `${flavorMapping.rolePrefix}.${flavor}`,
-          content: `### ${flavor} domain guidance\n\n${overlayBody}`,
-          tokenBudget: null,
+          content: `### ${flavor} domain guidance\n\n${overlayContent}`,
+          tokenBudget: selectedProfile.roleFlavorTokens,
         });
       }
     }
   }
 
-  // 3. Task context (priority varies, part of static if present)
+  if (selectedProfile.retrievalFirst) {
+    fragments.push({
+      type: 'model-profile',
+      priority: PRIORITY['model-profile'],
+      label: `model-profile.${selectedProfile.id}`,
+      content: [
+        `## ${selectedProfile.label} operating mode`,
+        '',
+        'Prefer retrieval-first execution: gather focused evidence before broad edits.',
+        'Keep plans and summaries compact, stage work in verified steps, and avoid whole-file rewrites unless the task requires them.',
+      ].join('\n'),
+      tokenBudget: 90,
+    });
+  }
+
   if (intent || workCategory) {
     const text = `Intent: ${intent || 'unknown'}\nWork category: ${workCategory || 'unknown'}`;
     fragments.push({
@@ -191,10 +255,13 @@ export function composePrompt(agentName, {
     });
   }
 
-  // 4. Learned patterns (priority 4)
   if (injectLearnedPatterns) {
     const { text: learnedBlock, tokens: learnedTokens } = buildLearnedPatternsBlock(agentName, {
-      intent, workCategory, project, modelId,
+      intent,
+      workCategory,
+      project,
+      modelId,
+      tokenLimit: selectedProfile.learnedPatternsTokens,
     });
     if (learnedBlock) {
       fragments.push({
@@ -202,13 +269,12 @@ export function composePrompt(agentName, {
         priority: PRIORITY['learned-patterns'],
         label: 'observations',
         content: learnedBlock,
-        tokenBudget: LEARNED_PATTERNS_TOKEN_LIMIT,
+        tokenBudget: selectedProfile.learnedPatternsTokens,
         estimatedTokens: learnedTokens,
       });
     }
   }
 
-  // 5. Task packet (priority 1 — never dropped)
   if (task) {
     const taskBlock = [
       task.title ? `Task: ${task.title}` : null,
@@ -229,13 +295,12 @@ export function composePrompt(agentName, {
         type: 'task-packet',
         priority: PRIORITY['task-packet'],
         label: 'workflow-task',
-        content: compactTokens(taskBlock, 150, { modelId }),
-        tokenBudget: 150,
+        content: compactTokens(taskBlock, selectedProfile.taskPacketTokens, { modelId }),
+        tokenBudget: selectedProfile.taskPacketTokens,
       });
     }
   }
 
-  // 6. Context digest (priority 3)
   const digest = buildContextDigest(contextState);
   if (digest) {
     const digestStr = JSON.stringify(digest);
@@ -243,24 +308,34 @@ export function composePrompt(agentName, {
       type: 'context-digest',
       priority: PRIORITY['context-digest'],
       label: 'context',
-      content: compactTokens(digestStr, 200, { modelId }),
-      tokenBudget: 200,
+      content: compactTokens(digestStr, selectedProfile.contextDigestTokens, { modelId }),
+      tokenBudget: selectedProfile.contextDigestTokens,
+    });
+  }
+
+  const strategyText = buildStrategyBlock({ modelId, tokenLimit: selectedProfile.strategyTokens ?? 400 });
+  if (strategyText) {
+    fragments.push({
+      type: 'strategy',
+      priority: PRIORITY['strategy'],
+      label: 'active-strategy',
+      content: strategyText,
+      tokenBudget: selectedProfile.strategyTokens ?? 400,
     });
   }
 
-  // 7. Host constraints (priority 5 — dropped first)
   if (hostConstraints) {
     fragments.push({
       type: 'host-constraints',
       priority: PRIORITY['host-constraints'],
       label: 'host',
-      content: compactTokens(JSON.stringify(hostConstraints), 75, { modelId }),
-      tokenBudget: 75,
+      content: compactTokens(JSON.stringify(hostConstraints), selectedProfile.hostConstraintsTokens, { modelId }),
+      tokenBudget: selectedProfile.hostConstraintsTokens,
     });
   }
 
   // Priority-based pruning
-  const pruned = pruneFragments(fragments, MAX_CONTEXT_TOKENS, modelId);
+  const pruned = pruneFragments(fragments, selectedProfile.maxPromptTokens, modelId);
   const staticEndIndex = findStaticEndIndex(pruned);
 
   // Assemble outputs
@@ -366,6 +441,7 @@ export function summarizePromptComposition(agentName, options = {}) {
     roleFlavors: options.roleFlavors || route?.roleFlavors || null,
   });
   const fragmentTypes = composed.fragments.map((fragment) => fragment.type);
+  const flavorFragment = composed.fragments.find((fragment) => fragment.type === 'role-flavor');
   const composedPromptHash = composed.system
     ? crypto.createHash('sha256').update(composed.system).digest('hex')
     : null;
@@ -393,6 +469,7 @@ export function summarizePromptComposition(agentName, options = {}) {
       routeDispatchPlan: route.dispatchPlan,
       ...(route.roleFlavors ? { routeRoleFlavors: route.roleFlavors } : {}),
     } : {}),
+    ...(flavorFragment ? { promptRoleFlavor: flavorFragment.label } : {}),
     promptHasRoleFlavor: fragmentTypes.includes('role-flavor'),
     promptHasLearnedPatterns: fragmentTypes.includes('learned-patterns'),
     executionContractModel,

package/lib/read-tracker-store.mjs

@@ -0,0 +1,149 @@
+/**
+ * lib/hooks/read-tracker-store.mjs — batched persistence for read-efficiency tracking.
+ *
+ * The Read hook runs in a fresh process for every file read. Persisting the
+ * full session-efficiency store on every invocation is correct but noisy and
+ * expensive. This module appends compact JSONL deltas per read, then folds
+ * them into the durable session summary when the delta log is flushed.
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+const SESSION_IDLE_RESET_MS = 2 * 60 * 60 * 1000;
+const REPEATED_READ_WARNING_THRESHOLD = 5;
+const REPEATED_READ_TIER2_THRESHOLD = 8;
+const LARGE_READ_WARNING_THRESHOLD = 3;
+const TOTAL_BYTES_WARNING_THRESHOLD = 750_000;
+const FILES_LRU_CAP = 200;
+const EFFICIENCY_LARGE_READ_LIMIT = 400;
+
+export function readTrackerPaths(env = process.env) {
+  const home = env.CX_HOME_OVERRIDE || env.HOME || homedir();
+  const cxDir = join(home, '.cx');
+  return {
+    cxDir,
+    efficiencyStore: join(cxDir, 'session-efficiency.json'),
+    deltaLog: join(cxDir, 'session-efficiency.reads.jsonl'),
+    warnFlags: join(cxDir, 'warn-flags.txt'),
+  };
+}
+
+export function freshEfficiencyStats(nowIso) {
+  return {
+    sessionStartedAt: nowIso,
+    lastUpdatedAt: nowIso,
+    readCount: 0,
+    uniqueFileCount: 0,
+    repeatedReadCount: 0,
+    largeReadCount: 0,
+    totalBytesRead: 0,
+    warnings: {},
+    files: {},
+  };
+}
+
+export function loadEfficiencyStats(nowIso, env = process.env) {
+  const { efficiencyStore } = readTrackerPaths(env);
+  const fresh = freshEfficiencyStats(nowIso);
+  try {
+    const existing = JSON.parse(readFileSync(efficiencyStore, 'utf8'));
+    const lastUpdated = new Date(existing.lastUpdatedAt || 0).getTime();
+    if (!lastUpdated || Date.now() - lastUpdated > SESSION_IDLE_RESET_MS) return fresh;
+    return { ...fresh, ...existing, warnings: existing.warnings || {}, files: existing.files || {} };
+  } catch {
+    return fresh;
+  }
+}
+
+function appendWarning(message, env = process.env) {
+  try {
+    const { warnFlags } = readTrackerPaths(env);
+    appendFileSync(warnFlags, `${message}\n`);
+  } catch { /* best effort */ }
+}
+
+function topRepeatedPath(files) {
+  return Object.entries(files || {})
+    .map(([filePath, value]) => ({ filePath, count: Number(value?.count || 0) }))
+    .filter((entry) => entry.count > 1)
+    .sort((a, b) => b.count - a.count || a.filePath.localeCompare(b.filePath))[0];
+}
+
+export function applyReadDelta(stats, delta, env = process.env) {
+  const existingFile = stats.files[delta.path];
+  const isLargeRead = Number(delta.limit || 0) > EFFICIENCY_LARGE_READ_LIMIT;
+
+  stats.readCount += 1;
+  stats.totalBytesRead += Number(delta.size || 0);
+  if (isLargeRead) stats.largeReadCount += 1;
+  if (existingFile) stats.repeatedReadCount += 1;
+  else stats.uniqueFileCount += 1;
+
+  stats.files[delta.path] = {
+    count: Number(existingFile?.count || 0) + 1,
+    size: Number(delta.size || 0),
+    lastReadAt: delta.ts,
+    lastRequestedLimit: Number(delta.limit || 0),
+  };
+
+  const fileEntries = Object.entries(stats.files);
+  if (fileEntries.length > FILES_LRU_CAP) {
+    fileEntries.sort((a, b) => (a[1]?.lastReadAt || '').localeCompare(b[1]?.lastReadAt || ''));
+    const drop = fileEntries.length - FILES_LRU_CAP;
+    for (let i = 0; i < drop; i++) delete stats.files[fileEntries[i][0]];
+  }
+
+  if (stats.repeatedReadCount >= REPEATED_READ_WARNING_THRESHOLD && !stats.warnings.repeatedReads) {
+    const top = topRepeatedPath(stats.files);
+    const topNote = top ? ` Top repeat: ${top.filePath} (${top.count}x).` : '';
+    appendWarning(`Efficiency: ${stats.repeatedReadCount} repeated reads this session.${topNote} Use rg or construct distill before re-reading more files.`, env);
+    stats.warnings.repeatedReads = delta.ts;
+    if (stats.repeatedReadCount >= REPEATED_READ_TIER2_THRESHOLD && !stats.warnings.repeatedReadsTier2) {
+      appendWarning(`Efficiency: ${stats.repeatedReadCount} repeated reads this session — consider using construct distill or rg before re-reading entire files.`, env);
+      stats.warnings.repeatedReadsTier2 = delta.ts;
+    }
+  }
+
+  if (stats.largeReadCount >= LARGE_READ_WARNING_THRESHOLD && !stats.warnings.largeReads) {
+    appendWarning(`Efficiency: ${stats.largeReadCount} large reads this session — prefer rg/glob plus targeted reads under 400 lines.`, env);
+    stats.warnings.largeReads = delta.ts;
+  }
+
+  if (stats.totalBytesRead >= TOTAL_BYTES_WARNING_THRESHOLD && !stats.warnings.totalBytes) {
+    appendWarning(`Efficiency: ${Math.round(stats.totalBytesRead / 1024)} KB read this session — consider distill/query-focused retrieval or compact context before continuing.`, env);
+    stats.warnings.totalBytes = delta.ts;
+  }
+
+  stats.lastUpdatedAt = delta.ts;
+  return stats;
+}
+
+export function recordReadDelta(delta, env = process.env) {
+  const { cxDir, deltaLog } = readTrackerPaths(env);
+  mkdirSync(cxDir, { recursive: true });
+  appendFileSync(deltaLog, `${JSON.stringify(delta)}\n`, 'utf8');
+}
+
+export function flushReadTrackerDeltas({ nowIso = new Date().toISOString(), env = process.env } = {}) {
+  const { cxDir, deltaLog, efficiencyStore } = readTrackerPaths(env);
+  mkdirSync(cxDir, { recursive: true });
+  const stats = loadEfficiencyStats(nowIso, env);
+  if (!existsSync(deltaLog)) return stats;
+
+  const lines = readFileSync(deltaLog, 'utf8')
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean);
+
+  for (const line of lines) {
+    try {
+      const delta = JSON.parse(line);
+      applyReadDelta(stats, delta, env);
+    } catch { /* best effort */ }
+  }
+
+  writeFileSync(efficiencyStore, `${JSON.stringify(stats, null, 2)}\n`);
+  rmSync(deltaLog, { force: true });
+  return stats;
+}

package/lib/reflect/extractor.mjs

@@ -0,0 +1,193 @@
+/**
+ * lib/reflect/extractor.mjs — Deterministic transcript → observation extractor.
+ *
+ * Pure-function pass over a Claude Code transcript JSONL. Produces a compact
+ * structured summary suitable for `addObservation()` at session end. No LLM
+ * call — the transcript itself is the source of truth.
+ *
+ * Caller responsibility: read the transcript file and pass parsed lines.
+ * Output is capped at MAX_BYTES to honor the A1 hook's per-session budget.
+ */
+
+// Hard cap on the summary content so a runaway session can't blow up the
+// observation store. 5 KB matches the budget set in the A1 plan.
+const MAX_BYTES = 5 * 1024;
+const MAX_TAGS = 10;
+const MAX_TOOL_TYPES = 8;
+const MAX_FILES = 12;
+
+/**
+ * Extract a session-summary observation from a parsed transcript.
+ *
+ * @param {object} args
+ * @param {object[]} args.entries — parsed transcript JSONL lines (objects)
+ * @param {string} args.cwd — session working directory
+ * @param {string} [args.sessionId] — session identifier
+ * @param {number} [args.durationMs] — wall-clock session duration
+ * @returns {object|null} observation payload, or null if transcript is unusable
+ */
+export function extractSessionObservation({ entries, cwd, sessionId, durationMs }) {
+  if (!Array.isArray(entries) || entries.length === 0) return null;
+
+  const stats = collectStats(entries);
+  if (stats.assistantTurns === 0 && stats.userTurns === 0) return null;
+
+  const finalAssistant = stats.lastAssistantText;
+  const headline = deriveHeadline(finalAssistant, stats);
+
+  const lines = [];
+  lines.push(`Session: ${stats.userTurns} user turns, ${stats.assistantTurns} assistant turns`);
+  if (stats.toolCallCount > 0) {
+    const tools = Array.from(stats.toolTypes.entries())
+      .sort((a, b) => b[1] - a[1])
+      .slice(0, MAX_TOOL_TYPES)
+      .map(([name, n]) => `${name}×${n}`)
+      .join(', ');
+    lines.push(`Tools: ${stats.toolCallCount} calls (${tools})`);
+  }
+  if (stats.filesTouched.size > 0) {
+    const files = Array.from(stats.filesTouched).slice(0, MAX_FILES);
+    lines.push(`Files touched: ${files.join(', ')}${stats.filesTouched.size > MAX_FILES ? ', …' : ''}`);
+  }
+  if (durationMs && Number.isFinite(durationMs)) {
+    lines.push(`Duration: ${Math.round(durationMs / 1000)}s`);
+  }
+  if (finalAssistant) {
+    lines.push('', 'Final response excerpt:', clamp(finalAssistant, 800));
+  }
+
+  const content = clamp(lines.join('\n'), MAX_BYTES);
+
+  return {
+    role: stats.lastAgent || 'construct',
+    category: 'session-summary',
+    summary: headline,
+    content,
+    tags: buildTags(stats),
+    confidence: 0.7,
+    source: 'auto-reflect',
+    extras: {
+      sessionId: sessionId || null,
+      cwd,
+      durationMs: durationMs ?? null,
+      userTurns: stats.userTurns,
+      assistantTurns: stats.assistantTurns,
+      toolCallCount: stats.toolCallCount,
+      filesTouched: Array.from(stats.filesTouched).slice(0, MAX_FILES),
+    },
+  };
+}
+
+// Walk the transcript once and gather everything we need in one pass. Keeps
+// the hook well under its latency budget even on long sessions.
+
+function collectStats(entries) {
+  const toolTypes = new Map();
+  const filesTouched = new Set();
+  let assistantTurns = 0;
+  let userTurns = 0;
+  let toolCallCount = 0;
+  let lastAssistantText = '';
+  let lastAgent = null;
+
+  for (const entry of entries) {
+    if (!entry || typeof entry !== 'object') continue;
+    const type = entry.type;
+
+    if (type === 'user') {
+      userTurns += 1;
+      continue;
+    }
+
+    if (type === 'assistant') {
+      assistantTurns += 1;
+      const text = extractAssistantText(entry);
+      if (text) lastAssistantText = text;
+      const calls = extractToolCalls(entry);
+      for (const call of calls) {
+        toolCallCount += 1;
+        toolTypes.set(call.name, (toolTypes.get(call.name) || 0) + 1);
+        for (const f of call.files) filesTouched.add(f);
+      }
+      const agent = extractAgentName(entry);
+      if (agent) lastAgent = agent;
+    }
+  }
+
+  return { assistantTurns, userTurns, toolCallCount, toolTypes, filesTouched, lastAssistantText, lastAgent };
+}
+
+function extractAssistantText(entry) {
+  const message = entry.message ?? entry;
+  const content = message?.content;
+  if (typeof content === 'string') return content.trim();
+  if (Array.isArray(content)) {
+    const text = content
+      .filter((p) => p?.type === 'text' && typeof p.text === 'string')
+      .map((p) => p.text)
+      .join('\n')
+      .trim();
+    return text;
+  }
+  return '';
+}
+
+function extractToolCalls(entry) {
+  const message = entry.message ?? entry;
+  const content = message?.content;
+  if (!Array.isArray(content)) return [];
+  const calls = [];
+  for (const part of content) {
+    if (part?.type !== 'tool_use') continue;
+    const name = part.name || 'unknown';
+    const files = [];
+    const input = part.input || {};
+    if (typeof input.file_path === 'string') files.push(shortenPath(input.file_path));
+    if (typeof input.path === 'string') files.push(shortenPath(input.path));
+    calls.push({ name, files });
+  }
+  return calls;
+}
+
+function extractAgentName(entry) {
+  // Claude Code may stamp the agent name on subagent transcripts. Fall through
+  // to null if not present — caller defaults to 'construct'.
+  return entry?.agent || entry?.subagent_type || entry?.message?.agent || null;
+}
+
+function deriveHeadline(finalText, stats) {
+  // First non-empty line of the final assistant turn is usually a good lead.
+  // Fall back to a structural summary when nothing useful is available.
+  if (finalText) {
+    const firstLine = finalText.split('\n').map((l) => l.trim()).find((l) => l.length > 0);
+    if (firstLine) {
+      const clean = firstLine.replace(/^[#*\->]\s*/, '').replace(/[`*_]/g, '');
+      return `[session] ${clamp(clean, 200)}`;
+    }
+  }
+  return `[session] ${stats.assistantTurns} turn${stats.assistantTurns === 1 ? '' : 's'}, ${stats.toolCallCount} tool call${stats.toolCallCount === 1 ? '' : 's'}`;
+}
+
+function buildTags(stats) {
+  const tags = ['auto-reflect', 'session-summary'];
+  // Surface the most-used tool family so search can filter on "Bash-heavy
+  // session", etc. without parsing content.
+  const top = Array.from(stats.toolTypes.entries()).sort((a, b) => b[1] - a[1]).slice(0, 3);
+  for (const [name] of top) tags.push(`tool:${name.toLowerCase()}`);
+  if (stats.filesTouched.size > 0) tags.push('edits');
+  return tags.slice(0, MAX_TAGS);
+}
+
+function shortenPath(p) {
+  if (typeof p !== 'string') return '';
+  // Strip a repo-root prefix when present so observations stay portable.
+  const cwd = process.cwd();
+  if (p.startsWith(cwd + '/')) return p.slice(cwd.length + 1);
+  return p;
+}
+
+function clamp(str, max) {
+  if (!str) return '';
+  if (str.length <= max) return str;
+  return str.slice(0, max - 1) + '…';
+}