shraga 0.1.111 → 0.1.112

package/dist/client/index.html

@@ -13,7 +13,7 @@
     <link rel="preconnect" href="https://fonts.googleapis.com" />
     <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
     <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&display=swap" rel="stylesheet" />
-    <script type="module" crossorigin src="/assets/index-BNAh4GUs.js"></script>
+    <script type="module" crossorigin src="/assets/index-Dc1ljSt3.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-DIMte_k6.css">
   </head>
   <body>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shraga",
-  "version": "0.1.111",
+  "version": "0.1.112",
   "description": "The teammate you delegate coding to — a self-hostable, multi-user AI coding agent web UI (Claude Code, with a pluggable engine seam).",
   "type": "module",
   "main": "./src/index.ts",

package/src/server/claude.ts

@@ -3,7 +3,7 @@ import { summarizeText } from './summarize.ts';
 import { dataSync } from './data-sync.ts';
 import type { McpConfig } from './mcp.ts';
 import type { ClaudeAccountRef } from './claude-account.ts';
-import { loadConversation, saveConversation, appendMessage, getSession, setSessionDirectives, addTriggeredSkills, upsertSession, type ConvMessage, type ConvBlock } from './sessions.ts';
+import { loadConversation, saveConversation, appendMessage, getSession, setSessionDirectives, addTriggeredSkills, upsertSession, setClaudeResume, type ConvMessage, type ConvBlock } from './sessions.ts';
 import { createTurnAccumulator, type TurnStreamHooks } from './turn-stream.ts';
 import {
   resolveDefaultSkillsContent,
@@ -324,7 +324,10 @@ export async function* streamChat(opts: {
   const stickyNames = opts.sessionId ? getSession(opts.sessionId)?.triggeredSkills ?? [] : [];
   const newTriggerNames = discoveryEnabled ? matchTriggeredSkillNames(effectivePrompt, opts.context) : [];
   const triggeredNames = [...new Set([...stickyNames, ...newTriggerNames])];
-  const triggeredSkills = skillInjectionBlocks(triggeredNames);
+  // Per-name blocks so an engine that resumes across turns can send only newly triggered ones. Joined
+  // exactly as skillInjectionBlocks(triggeredNames) joins them, so contextBlock is byte-identical.
+  const triggeredSkillBlocks = triggeredNames.map((n) => [n, skillInjectionBlocks([n])] as const).filter(([, b]) => b);
+  const triggeredSkills = triggeredSkillBlocks.map(([, b]) => b).join('\n');
 
   // Per-skill turn budget. Resolved HERE, once every invoked skill is known (the slash command and
   // the triggered/sticky set), and GAP-FILLING only: an inline `[turns:N]` or a session-pinned
@@ -347,6 +350,11 @@ export async function* streamChat(opts: {
   const teamRoster = contacts.formatRoster();
   const userContextBlock = getUserContextBlock(contact);
   const contextBlock = [userBlock, userContextBlock, teamRoster, defaultSkills, triggeredSkills, skillIndex, mcpSkills, workspaceTree].filter(Boolean).join('\n');
+  const contextSections: Record<string, string> = Object.fromEntries(Object.entries({
+    user: userBlock, userContext: userContextBlock, roster: teamRoster, defaultSkills,
+    ...Object.fromEntries(triggeredSkillBlocks.map(([n, b]) => [`skill:${n}`, b])),
+    skillIndex, mcpSkills, workspace: workspaceTree,
+  }).filter(([, v]) => v));
 
   // Load conversation for the engine
   const sessionId = opts.sessionId ?? crypto.randomUUID();
@@ -388,11 +396,16 @@ export async function* streamChat(opts: {
     return;
   }
   console.log(`[stream] engine=${engine.name} user=${opts.uid} session=${sessionId}`);
+  // Another engine's turn never reaches the claude-code transcript, so a stored SDK-resume mapping is
+  // stale from here on — mark it; the claude-code engine then falls back to a fresh query (engine-switch).
+  const resumeState = getSession(sessionId)?.claudeResume;
+  if (engine.name !== 'claude-code' && resumeState && !resumeState.interruptedBy) setClaudeResume(sessionId, undefined, { interruptedBy: engine.name });
 
   yield* engine.stream({
     prompt: turnPrompt,
     conversation,
     contextBlock,
+    contextSections,
     attachments: opts.attachments,
     images: opts.images,
     sessionId,

package/src/server/directives.ts

@@ -4,6 +4,8 @@ export interface Directives {
   thinking?: 'adaptive' | 'enabled' | 'disabled';
   effort?: 'low' | 'medium' | 'high' | 'max';
   engine?: string;
+  /** claude-code SDK session resume for this conversation (overrides agent-config `sdkResume`). */
+  resume?: boolean;
 }
 
 export interface ParsedPrompt {
@@ -28,7 +30,7 @@ import { MODEL_ALIASES } from './model-aliases.ts';
 
 const DIRECTIVE_RE = /^\s*\[([^\]]*)\]\s*([\s\S]*)/;
 
-const DIRECTIVE_KEYS = ['model', 'turns', 'thinking', 'think', 'effort', 'engine'];
+const DIRECTIVE_KEYS = ['model', 'turns', 'thinking', 'think', 'effort', 'engine', 'resume'];
 
 /** MODEL_ALIASES only covers the bare Anthropic shorthands. A `provider/model` id
  *  (`cursor/composer-2.5`, `openai/gpt-5.6`) is already concrete — gating it on the alias table
@@ -179,6 +181,11 @@ function applyDirective(d: Directives, key: string, val: string): string | undef
     case 'engine':
       d.engine = val;
       break;
+    case 'resume':
+      if (['on', 'true', '1'].includes(val)) d.resume = true;
+      else if (['off', 'false', '0'].includes(val)) d.resume = false;
+      else console.warn(`[directives] Invalid resume value: "${val}"`);
+      break;
     default:
       console.warn(`[directives] Unknown directive key: "${key}"`);
   }

package/src/server/engine/claude-code.ts

@@ -8,7 +8,12 @@ import { listSkills } from '../skills.ts';
 import { loadAgents } from '../agents.ts';
 import { registerProactiveMessage } from '../slack/sessions.ts';
 import { registerPoll } from '../polls.ts';
-import { getSession, setSessionModel, getSessionModel, type ConvMessage } from '../sessions.ts';
+import { getSession, setSessionModel, getSessionModel, setClaudeResume, type ConvMessage } from '../sessions.ts';
+import {
+  isResumeEnabled, decideClaudeTurn, claudeConfigDir, findClaudeTranscript, shortHash, sectionHashes, speakerKey,
+  sectionsAfterSubmit, isResumeFailure, conversationSummaryKey, buildContextDelta, buildResumePrompt, renderConvMessage,
+  type TurnPath, type ClaudeResumeState,
+} from './claude-resume.ts';
 import { DEFAULT_MODEL } from '../directives.ts';
 import { resolveModelSwitch, MODEL_ALIASES } from '../model-aliases.ts';
 import type { WsEvent, AskQuestion, QuestionAnswers, QuestionHandler } from '../claude.ts';
@@ -95,15 +100,8 @@ function buildHistoryPrompt(conv: ConvMessage[], contextBlock: string, userPromp
   const parts: string[] = [];
   if (summary) parts.push(`<conversation_summary>\n${summary}\n</conversation_summary>`);
   for (const m of recent) {
-    const role = m.role === 'user' ? 'User' : 'Assistant';
-    const texts = m.blocks
-      .filter((b) => b.type === 'text' || b.type === 'context')
-      .map((b) => {
-        if (b.type === 'context') return `[${(b as any).label}]: ${(b as any).text}`;
-        return (b as { type: 'text'; text: string }).text;
-      })
-      .filter(Boolean);
-    if (texts.length) parts.push(`${role}: ${texts.join('\n')}`);
+    const line = renderConvMessage(m);
+    if (line) parts.push(line);
   }
 
   if (parts.length) {
@@ -117,10 +115,11 @@ function buildHistoryPrompt(conv: ConvMessage[], contextBlock: string, userPromp
  * Log prompt-cache effectiveness from the SDK result `usage`. The hit rate is
  * cache_read / (cache_read + cache_creation + uncached input) — a low rate over
  * many turns points to a silent prefix invalidator or sessions spread past the
- * 5-min cache TTL. Note: cross-turn history is re-sent uncached (single-shot
- * prompt per query, no SDK resume) — so hit rate tracks tool density per turn.
+ * 5-min cache TTL. `path` says how the prompt was built — `fresh` (history re-sent in one message),
+ * `resume` (SDK session resumed, only the new message sent) or `fallback:<reason>` (resume enabled but a
+ * fresh query ran) — so journal lines can be A/B-compared per path.
  */
-function logCacheUsage(usage: any, model: string): void {
+function logCacheUsage(usage: any, model: string, path: TurnPath): void {
   if (!usage) return;
   const read = usage.cache_read_input_tokens ?? 0;
   const created = usage.cache_creation_input_tokens ?? 0;
@@ -128,9 +127,47 @@ function logCacheUsage(usage: any, model: string): void {
   const totalIn = read + created + fresh;
   if (totalIn === 0) return;
   const hitRate = ((read / totalIn) * 100).toFixed(1);
-  console.log(`[claude] Cache: hit=${hitRate}% read=${read} write=${created} uncached=${fresh} out=${usage.output_tokens ?? 0} model=${model}`);
+  console.log(`[claude] Cache: hit=${hitRate}% read=${read} write=${created} uncached=${fresh} out=${usage.output_tokens ?? 0} model=${model} path=${path}`);
 }
 
+/** How one query attempt is built. `persist` is set when resume is enabled: after a query that produced
+ *  output, the CC session id + these facts are saved so the next turn can resume. */
+interface RunPlan {
+  path: TurnPath;
+  prompt: string;
+  accountDir: string | null;
+  resumeId?: string;
+  persist?: Omit<ClaudeResumeState, 'claudeSessionId' | 'model' | 'interruptedBy'>;
+  /** Resume only: section hashes to store once the prompt is submitted (see sectionsAfterSubmit). */
+  submitSections?: Record<string, string>;
+}
+
+/** Exit promises of CLI processes still running, per shraga session. A turn that took over a session (external
+ *  steer) can start while the aborted run's CLI is still exiting; resuming then would put two writers on one
+ *  transcript. */
+const liveCli = new Map<string, Set<Promise<void>>>();
+
+function trackCliExit(sessionId: string | undefined, child: { once: (event: string, fn: () => void) => unknown }): void {
+  if (!sessionId) return;
+  const set = liveCli.get(sessionId) ?? new Set();
+  liveCli.set(sessionId, set);
+  const exited = new Promise<void>((resolve) => { child.once('exit', resolve); child.once('error', resolve); });
+  set.add(exited);
+  void exited.then(() => { set.delete(exited); if (!set.size && liveCli.get(sessionId) === set) liveCli.delete(sessionId); });
+}
+
+/** true once every CLI process of the session has exited, false if one is still alive after `ms`. */
+async function cliExited(sessionId: string, ms: number): Promise<boolean> {
+  const set = liveCli.get(sessionId);
+  if (!set?.size) return true;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timeout = new Promise<false>((r) => { timer = setTimeout(() => r(false), ms); });
+  try { return await Promise.race([Promise.all(set).then(() => true), timeout]); } finally { clearTimeout(timer); }
+}
+
+/** Events that prove a resumed query actually runs; until one arrives the attempt can still be retried fresh unseen. */
+const LIVE_EVENTS = new Set<WsEvent['type']>(['text_delta', 'thinking_delta', 'tool_use', 'tool_use_input', 'tool_result', 'tool_result_image', 'done']);
+
 /** SDK spawn hook: same call the SDK would make, plus `detached` (own process group). See the
  *  call site for why. Shape mirrors the SDK's own spawnLocalProcess return. */
 function spawnDetached(cfg: { command: string; args: string[]; cwd?: string; env: Record<string, string | undefined>; signal?: AbortSignal }) {
@@ -221,11 +258,75 @@ export class ClaudeCodeEngine implements AgentEngine {
     ];
   }
 
+  /** How long a resume-enabled turn waits for an earlier CLI process on the session to exit before going fresh. */
+  static cliExitWaitMs = 5_000;
+
   async *stream(opts: EngineStreamOpts): AsyncGenerator<WsEvent> {
+    let cliAlive = false;
+    if (opts.sessionId && isResumeEnabled(opts.directives, opts.config) && !(await cliExited(opts.sessionId, ClaudeCodeEngine.cliExitWaitMs))) {
+      cliAlive = true;
+      console.warn(`[claude] An earlier CLI process on session=${opts.sessionId} is still running after ${ClaudeCodeEngine.cliExitWaitMs}ms — not resuming its transcript`);
+    }
+    const plan = this.plan(opts, cliAlive);
+    if (plan.path !== 'resume') { yield* this.run(opts, plan); return; }
+    // Hold non-output events (init's model_resolved / switch notice) until the resumed query proves it
+    // runs, so a failed resume can be retried fresh with nothing duplicated on the user's side.
+    const attempt = this.run(opts, plan);
+    const held: WsEvent[] = [];
+    let live = false;
+    let r: IteratorResult<WsEvent, 'resume-failed' | void>;
+    try {
+      while (!(r = await attempt.next()).done) {
+        if (!live && !LIVE_EVENTS.has(r.value.type)) { held.push(r.value); continue; }
+        if (!live) { live = true; yield* held; }
+        yield r.value;
+      }
+    } finally {
+      await attempt.return(undefined);
+    }
+    if (r.value !== 'resume-failed') { if (!live) yield* held; return; }
+    console.warn(`[claude] Resume of ${plan.resumeId} failed before any output — retrying fresh in the same turn (session=${opts.sessionId})`);
+    setClaudeResume(opts.sessionId, undefined);
+    yield* this.run(opts, this.freshPlan(opts, plan.accountDir, 'fallback:resume-failed', plan.persist));
+  }
+
+  private freshPlan(opts: EngineStreamOpts, accountDir: string | null, path: TurnPath, persist?: RunPlan['persist']): RunPlan {
+    return {
+      path, accountDir,
+      prompt: buildHistoryPrompt(opts.conversation, opts.contextBlock, opts.prompt),
+      ...(persist ? { persist: { ...persist, sections: sectionHashes(opts.contextSections ?? { context: opts.contextBlock }), startedAt: Date.now() } } : {}),
+    };
+  }
+
+  /** Resume vs fresh, and why — see claude-resume.ts. */
+  private plan(opts: EngineStreamOpts, cliAlive: boolean): RunPlan {
+    const accountDir = claudeAccountDir(opts.userEmail);
+    if (!isResumeEnabled(opts.directives, opts.config)) return this.freshPlan(opts, accountDir, 'fresh');
+    const configDir = claudeConfigDir(accountDir);
+    const configDirHash = shortHash(configDir);
+    const state = opts.sessionId ? getSession(opts.sessionId)?.claudeResume : undefined;
+    const speaker = speakerKey(opts.uid, opts.userEmail);
+    const persist = { configDirHash, speaker, markId: opts.conversation.at(-1)?.id, summaryKey: conversationSummaryKey(opts.conversation), sections: {}, startedAt: Date.now() };
+    const decision = decideClaudeTurn({
+      enabled: true, state, conversation: opts.conversation, configDirHash, speaker, cliAlive, conversationReset: opts.conversationReset,
+      hasTranscript: (id) => !!findClaudeTranscript(id, configDir),
+    });
+    if (decision.path !== 'resume' || !state) return this.freshPlan(opts, accountDir, decision.path, persist);
+    const sections = opts.contextSections ?? { context: opts.contextBlock };
+    const hashes = sectionHashes(sections);
+    return {
+      path: 'resume', accountDir, resumeId: state.claudeSessionId,
+      prompt: buildResumePrompt(opts.prompt, decision.unseen, buildContextDelta(state.sections, sections)),
+      persist: { ...persist, sections: hashes, startedAt: state.startedAt },
+      submitSections: sectionsAfterSubmit(state.sections, hashes),
+    };
+  }
+
+  private async *run(opts: EngineStreamOpts, plan: RunPlan): AsyncGenerator<WsEvent, 'resume-failed' | void> {
     const { config, directives } = opts;
     const cwd = APP_ROOT;
 
-    const fullPrompt = buildHistoryPrompt(opts.conversation, opts.contextBlock, opts.prompt);
+    const fullPrompt = plan.prompt;
     const permMode = opts.onPermissionRequest ? 'default' : (config.permissionMode ?? 'acceptEdits');
 
     const sdkEnv: Record<string, string> = {};
@@ -251,7 +352,7 @@ export class ClaudeCodeEngine implements AgentEngine {
     // regardless of settingSources; headless they are auth stubs or self-recursion. Our MCPs come from mcp-config.
     setIfBlank('ENABLE_CLAUDEAI_MCP_SERVERS', 'false');
     // Per-user subscription (workspace/users/<contactId>/.claude): run on that login, never the box's credentials.
-    const accountDir = claudeAccountDir(opts.userEmail);
+    const accountDir = plan.accountDir;
     if (accountDir) applyClaudeAccount(sdkEnv, accountDir);
     // Which login this run is on (email/plan, never a token) — read lazily from the login's local
     // files, only once init proves the run is on a subscription login (see init below).
@@ -259,6 +360,10 @@ export class ClaudeCodeEngine implements AgentEngine {
     const accountRef = () => (accountRefP ??= claudeAccountRef(accountDir));
     let runAccount: ClaudeAccountRef | undefined;
     let sawInit = false;
+    // Did THIS attempt produce model output? Gates both the resume-failure retry and saving the session id
+    // (a resume that died on "No conversation found" can report a session id it never wrote a turn to).
+    let sawOutput = false;
+    let initModel: string | undefined;
     sdkEnv.INTERNAL_API_TOKEN = signInternalToken(opts.uid, opts.userEmail || 'unknown');
 
     const baseAllowed = config.allowedTools ?? DEFAULT_ALLOWED_TOOLS;
@@ -357,13 +462,18 @@ export class ClaudeCodeEngine implements AgentEngine {
     const addonSuffix = getPromptSuffix(opts.turnHints);
     options['systemPrompt'] = `${IMMUTABLE_SYSTEM_PROMPT}\n\n${userPrompt}${addonSuffix ? `\n\n${addonSuffix}` : ''}`;
     if (opts.abortController) options['abortController'] = opts.abortController;
+    if (plan.resumeId) options['resume'] = plan.resumeId;
     // Spawn the CLI in its OWN process group. The service manager signals the whole JOB on restart
     // (`launchctl kickstart -k`, `systemctl restart`), so an inherited process group means the child
     // dies instantly with SIGTERM — surfacing mid-reply as `exited with code 143` and making the
     // server's 90s drain (gracefulShutdown) protect nothing: it only ever waited for a turn that was
     // already dead. Detached, the signal reaches the server alone and the drain can finish the turn.
     // Teardown is unaffected: the SDK still kills the child on abort/close and on process exit.
-    options['spawnClaudeCodeProcess'] = spawnDetached;
+    options['spawnClaudeCodeProcess'] = (cfg: Parameters<typeof spawnDetached>[0]) => {
+      const child = spawnDetached(cfg);
+      trackCliExit(opts.sessionId, child);
+      return child;
+    };
 
     // Passed as a FILE, never as `options.mcpServers` — the SDK would put the whole config (every MCP
     // server's credentials) on the CLI's argv, where `ps` / `/proc` / journald expose it. See
@@ -391,6 +501,8 @@ export class ClaudeCodeEngine implements AgentEngine {
         : fullPrompt;
 
     const q = query({ prompt, options: options as any });
+    // The CLI writes this prompt to the transcript before any output: from here a cancel can't un-deliver it.
+    if (plan.submitSections && opts.sessionId) setClaudeResume(opts.sessionId, undefined, { sections: plan.submitSections });
 
     let lastSessionId = '';
     let messageCount = 0;
@@ -449,6 +561,7 @@ export class ClaudeCodeEngine implements AgentEngine {
           // default only counts when the SDK says it resolved a login, not an API key.
           if ((authSource ?? (accountDir ? 'subscription' : undefined)) === 'subscription') runAccount = await accountRef();
           if (m.model) {
+            initModel = m.model;
             console.log(`[claude] Init model=${m.model}${m.model !== options['model'] ? ` (requested ${options['model']})` : ''}`);
             // If the user explicitly asked to switch models via a [directive], announce the change
             // inline so the response confirms the switch took effect.
@@ -494,7 +607,7 @@ export class ClaudeCodeEngine implements AgentEngine {
           const raw = m.subtype ?? 'unknown';
           const sub = raw === 'error_max_turns' || (raw === 'end_turn' && sdkTurns >= maxTurns) ? 'max_turns_reached' : raw;
           console.log(`[claude] Result: subtype=${m.subtype}→${sub} session=${lastSessionId} turns=${sdkTurns}/${maxTurns} cost=$${m.total_cost_usd?.toFixed(4) ?? '?'} msgs=${messageCount} deltas=${textDeltaCount} (${elapsed()})`);
-          logCacheUsage(m.usage, activeModel);
+          logCacheUsage(m.usage, activeModel, plan.path);
           if (outstandingTasks.size > 0) {
             if (!waitingForBg) {
               waitingForBg = true; clearBgTimer();
@@ -514,6 +627,12 @@ export class ClaudeCodeEngine implements AgentEngine {
           // `error_max_turns` also sets is_error but is a benign stop reason we already model.
           if ((m.is_error || m.api_error_status) && sub !== 'max_turns_reached') {
             const detail = typeof m.result === 'string' && m.result ? m.result : `api_error_status=${m.api_error_status ?? '?'}`;
+            // The CLI's reason ("No conversation found with session ID …") rides in `errors`, not `result`.
+            const reasons = Array.isArray(m.errors) && m.errors.length ? m.errors.join('; ') : detail;
+            if (plan.resumeId && !sawOutput && isResumeFailure(reasons)) {
+              console.error(`[claude] Resume error result (subtype=${raw}) — ${reasons}`);
+              return 'resume-failed';
+            }
             // A usage/rate-limit failure is about ONE login's quota — name it, or a routed user's own
             // exhausted Pro plan reads as the shared agent subscription being out.
             const limitHit = m.api_error_status === 429 || /\b(usage|rate.?limit(ed)?|hit your limit)\b/i.test(detail);
@@ -532,10 +651,12 @@ export class ClaudeCodeEngine implements AgentEngine {
         if (m.type === 'stream_event') {
           const event = m.event;
           if (event?.type === 'content_block_delta' && event.delta?.type === 'thinking_delta') {
+            sawOutput = true;
             yield { type: 'thinking_delta', text: event.delta.thinking };
           }
           if (event?.type === 'content_block_delta' && event.delta?.type === 'text_delta') {
             textDeltaCount++;
+            sawOutput = true;
             yield { type: 'text_delta', text: event.delta.text };
           }
           if (event?.type === 'content_block_start' && event.content_block?.type === 'tool_use') {
@@ -557,6 +678,7 @@ export class ClaudeCodeEngine implements AgentEngine {
 
         if (m.type === 'assistant' && Array.isArray(m.message?.content)) {
           turnCount++;
+          sawOutput = true;
           for (const block of m.message.content) {
             if (block.type === 'tool_use') {
               pendingToolUses.set(block.id, { tool: block.name, input: block.input });
@@ -645,6 +767,7 @@ export class ClaudeCodeEngine implements AgentEngine {
         return;
       }
       console.error(`[claude] Error after ${messageCount} msgs (${elapsed()}):`, err.message || err);
+      if (plan.resumeId && !sawOutput && isResumeFailure(err.message || String(err))) return 'resume-failed';
       yield { type: 'error', message: err.message || String(err) };
       return;
     } finally {
@@ -652,6 +775,11 @@ export class ClaudeCodeEngine implements AgentEngine {
       // The CLI has read the file by now (it loads MCP config at startup); holding it any longer just
       // widens the window in which the credentials sit on disk.
       mcpConfigFile?.cleanup();
+      // Save the mapping once this attempt really ran a turn (incl. an aborted one — the transcript holds it).
+      if (plan.persist && opts.sessionId && lastSessionId && sawOutput) {
+        setClaudeResume(opts.sessionId, { ...plan.persist, claudeSessionId: lastSessionId, ...(initModel ? { model: initModel } : {}) });
+        if (plan.resumeId && plan.resumeId !== lastSessionId) console.warn(`[claude] Resume returned a new session id ${lastSessionId} (was ${plan.resumeId})`);
+      }
     }
 
     const inferredReason = turnCount >= maxTurns ? 'max_turns_reached' : 'end_turn';

package/src/server/engine/claude-resume.ts

@@ -0,0 +1,205 @@
+/**
+ * Opt-in SDK session resume for the claude-code engine — the pure half (decision + prompt building),
+ * kept free of SDK/IO wiring so every fallback reason is unit-testable.
+ *
+ * Fresh turn (today's path): ONE user message = contextBlock + <conversation_history> + new message, so
+ * the whole history is re-written to prompt cache every turn. Resume turn: `resume: <claudeSessionId>`
+ * and send only the new message; the stable context went in once on the session's fresh query, and
+ * whatever CHANGED since (context sections, messages other channels appended) plus the current speaker's
+ * `user` section rides AFTER the user text so the cached transcript prefix stays byte-identical. Only one
+ * speaker's turns ever share a CC session (speaker-change).
+ *
+ * Flag: `directives.resume` (per conversation: `[resume:on]` or PUT /api/sessions/:id/directives) over
+ * `agent-config.json` `sdkResume` (global, re-read every turn). Default OFF.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, readdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import type { ConvMessage } from '../sessions.ts';
+import type { Directives } from '../directives.ts';
+import type { AgentSettings } from '../shraga-config.ts';
+
+/** Persisted on SessionMeta.claudeResume — the facts needed to decide whether the stored CC session
+ *  may be resumed. Hashes, not content: this lives in the 9 MB sessions index. */
+export interface ClaudeResumeState {
+  /** Claude Code session id (SDK init/result `session_id`); resume keeps it stable across turns. */
+  claudeSessionId: string;
+  /** Hash of the CLAUDE_CONFIG_DIR the transcript was written under (per-user login or box default). */
+  configDirHash: string;
+  /** speakerKey() of the person whose turns this CC session holds. Another speaker never resumes it: the
+   *  transcript carries this speaker's private user context (learnings/corrections). */
+  speaker?: string;
+  /** Model the last turn resolved (informational — CC resumes across models; only the cache is per-model). */
+  model?: string;
+  /** When this CC session was started (first fresh query). */
+  startedAt: number;
+  /** Id of the last conversation message at the start of the last turn; messages after it are what CC hasn't seen. */
+  markId?: string;
+  /** Identity of the newest shraga summary / compact marker when the state was saved. */
+  summaryKey: string;
+  /** Section name → hash of the context CC has already been given. */
+  sections: Record<string, string>;
+  /** Set by the core when another engine ran a turn on this session (its turns aren't in the CC transcript). */
+  interruptedBy?: string;
+}
+
+export type TurnPath = 'resume' | 'fresh' | `fallback:${string}`;
+
+/** Unseen out-of-band text above this size means resume would re-send a history anyway — go fresh. */
+export const MAX_UNSEEN_CHARS = 30_000;
+
+export function isResumeEnabled(directives: Directives, config: AgentSettings): boolean {
+  // The per-session directives endpoint stores passthrough values opaquely, so accept string forms too.
+  const v = (directives.resume ?? config.sdkResume) as unknown;
+  return v === true || v === 'on' || v === 'true';
+}
+
+export function shortHash(text: string): string {
+  return createHash('sha256').update(text).digest('hex').slice(0, 16);
+}
+
+/** Who is speaking, as a hash (the sessions index must not gain raw emails). */
+export function speakerKey(uid: string, email?: string): string {
+  return shortHash(`${uid}\n${email?.trim().toLowerCase() ?? ''}`);
+}
+
+/** Errors that mean THIS resume can't run (the stored transcript is gone/unreadable) — worth one fresh retry.
+ *  Anything else (quota, auth, API, process crash) would fail a fresh query the same way: surface it as-is. */
+export function isResumeFailure(text: string): boolean {
+  return /No conversation found|\b(session|transcript)\b.{0,60}\b(not found|missing|corrupt|invalid)\b/i.test(text);
+}
+
+/** Where the CLI keeps transcripts for a run: the routed per-user login, else the process's config dir. */
+export function claudeConfigDir(accountDir: string | null | undefined): string {
+  return accountDir || process.env.CLAUDE_CONFIG_DIR?.trim() || path.join(homedir(), '.claude');
+}
+
+/** `<configDir>/projects/<cwd-slug>/<id>.jsonl`, found by scan rather than by re-deriving the CLI's slug
+ *  rule (a wrong guess would silently turn every resume into a fallback). */
+export function findClaudeTranscript(sessionId: string, configDir: string): string | null {
+  const projects = path.join(configDir, 'projects');
+  if (!existsSync(projects)) return null;
+  for (const dir of readdirSync(projects, { withFileTypes: true })) {
+    if (!dir.isDirectory()) continue;
+    const file = path.join(projects, dir.name, `${sessionId}.jsonl`);
+    if (existsSync(file)) return file;
+  }
+  return null;
+}
+
+/** One conversation message as history text — shared by the fresh history prompt and the resume tail. */
+export function renderConvMessage(m: ConvMessage): string | null {
+  const texts = m.blocks
+    .filter((b) => b.type === 'text' || b.type === 'context')
+    .map((b) => (b.type === 'context' ? `[${b.label}]: ${b.text}` : (b as { text: string }).text))
+    .filter(Boolean);
+  return texts.length ? `${m.role === 'user' ? 'User' : 'Assistant'}: ${texts.join('\n')}` : null;
+}
+
+/** Changes whenever maybeCompact writes a summary or /compact adds a marker (applyCompactMarkers
+ *  turns the latter into a synthetic leading message). */
+export function conversationSummaryKey(conv: ConvMessage[]): string {
+  for (let i = conv.length - 1; i >= 0; i--) {
+    const s = conv[i].blocks.find((b) => b.type === 'summary') as { compactedCount: number } | undefined;
+    if (s) return `summary:${s.compactedCount}`;
+  }
+  const first = conv[0];
+  if (first?.id === 'compact-summary') return `marker:${shortHash(renderConvMessage(first) ?? '')}`;
+  return '';
+}
+
+/**
+ * Messages CC has not seen: everything after the mark, minus the previous turn's own reply (the first
+ * message, when it is the assistant's) and this turn's prompt (the last, when it is a user message —
+ * every channel appends it before streaming). null = the mark is gone (history was rewritten).
+ */
+export function unseenMessages(conv: ConvMessage[], markId: string | undefined): ConvMessage[] | null {
+  if (!markId) return null;
+  const idx = conv.findLastIndex((m) => m.id === markId);
+  if (idx < 0) return null;
+  const after = conv.slice(idx + 1);
+  if (after[0]?.role === 'assistant') after.shift();
+  if (after.at(-1)?.role === 'user') after.pop();
+  return after;
+}
+
+export interface TurnDecisionInput {
+  enabled: boolean;
+  state?: ClaudeResumeState;
+  conversation: ConvMessage[];
+  configDirHash: string;
+  speaker: string;
+  /** A CLI process from an earlier run on this session is still alive (e.g. the run a steer took over). */
+  cliAlive?: boolean;
+  conversationReset?: boolean;
+  hasTranscript: (claudeSessionId: string) => boolean;
+}
+
+export function decideClaudeTurn(i: TurnDecisionInput): { path: TurnPath; unseen: ConvMessage[] } {
+  const fallback = (reason: string) => ({ path: `fallback:${reason}` as TurnPath, unseen: [] });
+  if (!i.enabled) return { path: 'fresh', unseen: [] };
+  const s = i.state;
+  if (!s?.claudeSessionId) return fallback('no-session');
+  // Two CLI processes appending to one transcript can interleave it; the takeover turn starts its own.
+  if (i.cliAlive) return fallback('concurrent-run');
+  if (s.speaker !== i.speaker) return fallback('speaker-change');
+  if (s.interruptedBy) return fallback('engine-switch');
+  if (s.configDirHash !== i.configDirHash) return fallback('account-change');
+  if (i.conversationReset) return fallback('reset');
+  if (s.summaryKey !== conversationSummaryKey(i.conversation)) return fallback('summary');
+  const unseen = unseenMessages(i.conversation, s.markId);
+  if (!unseen) return fallback('history-diverged');
+  if (unseen.reduce((n, m) => n + (renderConvMessage(m)?.length ?? 0), 0) > MAX_UNSEEN_CHARS) return fallback('drift');
+  // Checked last (filesystem): the CLI's periodic cleanup (cleanupPeriodDays) or a moved config dir
+  // deletes transcripts under sessions we still hold — catch it before spawning a doomed resume.
+  if (!i.hasTranscript(s.claudeSessionId)) return fallback('transcript-missing');
+  return { path: 'resume', unseen };
+}
+
+export function sectionHashes(sections: Record<string, string>): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [k, v] of Object.entries(sections)) if (v) out[k] = shortHash(v);
+  return out;
+}
+
+/** Re-sent on every resume turn regardless of hashes: who is speaking (identity + role) must never depend on
+ *  bookkeeping about what an earlier, possibly cancelled, turn managed to deliver. Small. */
+export const ALWAYS_SENT_SECTIONS = ['user'];
+
+/** Hash marking a section whose delivery is unknown — never equals a real hash, so the next turn re-sends it. */
+const UNKNOWN = '?';
+
+/**
+ * Section hashes to store the moment a resume prompt is SUBMITTED. The CLI writes the prompt to the
+ * transcript before any output, so a turn cancelled early may or may not have delivered its delta. Unchanged
+ * sections are known either way; changed, new and removed ones are marked unknown and re-sent next turn.
+ */
+export function sectionsAfterSubmit(prev: Record<string, string>, next: Record<string, string>): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const k of new Set([...Object.keys(prev), ...Object.keys(next)])) out[k] = prev[k] === next[k] ? prev[k] : UNKNOWN;
+  return out;
+}
+
+/** The context sections that changed since CC last saw them (new or edited) plus ALWAYS_SENT_SECTIONS, and a
+ *  note for sections that no longer apply. '' when there is nothing to send. */
+export function buildContextDelta(prev: Record<string, string>, sections: Record<string, string>): string {
+  const changed = Object.entries(sections).filter(([k, v]) => v && (ALWAYS_SENT_SECTIONS.includes(k) || prev[k] !== shortHash(v)));
+  const removed = Object.keys(prev).filter((k) => !sections[k]);
+  if (!changed.length && !removed.length) return '';
+  return [
+    '<context_update>',
+    'Current context for this turn. Each section below replaces its earlier version.',
+    ...changed.map(([k, v]) => `<section name="${k}">\n${v}\n</section>`),
+    ...(removed.length ? [`No longer applicable: ${removed.join(', ')}`] : []),
+    '</context_update>',
+  ].join('\n');
+}
+
+export function buildResumePrompt(prompt: string, unseen: ConvMessage[], delta: string): string {
+  const lines = unseen.map(renderConvMessage).filter(Boolean);
+  const unseenBlock = lines.length
+    ? `<messages_since_last_turn>\nAdded to this conversation since your last reply (other participants, channel context, notices):\n${lines.join('\n\n')}\n</messages_since_last_turn>`
+    : '';
+  return [prompt, unseenBlock, delta].filter(Boolean).join('\n\n');
+}

package/src/server/engine/types.ts

@@ -11,6 +11,9 @@ export interface EngineStreamOpts {
   conversation: ConvMessage[];
   /** Contextual blocks to prepend (user block, skills, workspace tree, etc.) */
   contextBlock: string;
+  /** The same context split into named sections (in contextBlock order), so an engine that keeps
+   *  state across turns can send only what changed. Joined with '\n' they equal contextBlock. */
+  contextSections?: Record<string, string>;
 
   attachments?: AttachmentMeta[];
   images?: string[];