throughline 0.9.0 → 0.10.0

package/src/grok-history-inject.mjs

@@ -0,0 +1,71 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+// Grok includes native injections only when synthetic_reason is
+// system_reminder. A custom reason is written to disk and dropped from
+// the model prompt (live session 01a00cf9).
+export const GROK_HANDOFF_SYNTHETIC_REASON = 'system_reminder';
+export const GROK_HANDOFF_MARKER = 'data-throughline-handoff="1"';
+
+function rowText(entry) {
+  if (typeof entry?.content === 'string') return entry.content;
+  if (Array.isArray(entry?.content)) {
+    return entry.content
+      .filter((block) => block && block.type === 'text' && typeof block.text === 'string')
+      .map((block) => block.text)
+      .join('');
+  }
+  return '';
+}
+
+function parseLines(raw) {
+  const rows = [];
+  for (const line of raw.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      rows.push(JSON.parse(trimmed));
+    } catch {
+      rows.push({ type: 'unparsed', content: line });
+    }
+  }
+  return rows;
+}
+
+/**
+ * Insert Throughline resume text as a Grok synthetic user row immediately
+ * before the latest <user_query>. Grok ignores UserPromptSubmit stdout.
+ */
+export function injectGrokHandoffContext(transcriptPath, injectionText) {
+  if (!transcriptPath || typeof injectionText !== 'string' || injectionText.length === 0) {
+    return { injected: false, reason: 'missing_path_or_text' };
+  }
+
+  const existing = existsSync(transcriptPath) ? readFileSync(transcriptPath, 'utf8') : '';
+  const rows = parseLines(existing);
+  if (rows.some((row) => rowText(row).includes(GROK_HANDOFF_MARKER))) {
+    return { injected: false, reason: 'already_present' };
+  }
+
+  const reminder = {
+    type: 'user',
+    content: [{
+      type: 'text',
+      text: `<system-reminder ${GROK_HANDOFF_MARKER}>\n${injectionText}\n</system-reminder>`,
+    }],
+    synthetic_reason: GROK_HANDOFF_SYNTHETIC_REASON,
+  };
+
+  let insertAt = rows.length;
+  for (let i = rows.length - 1; i >= 0; i--) {
+    if (rows[i].type === 'user' && rowText(rows[i]).includes('<user_query>')) {
+      insertAt = i;
+      break;
+    }
+  }
+  rows.splice(insertAt, 0, reminder);
+
+  mkdirSync(dirname(transcriptPath), { recursive: true });
+  writeFileSync(transcriptPath, `${rows.map((row) => JSON.stringify(row)).join('\n')}\n`, 'utf8');
+  return { injected: true, reason: null, insertAt };
+}

package/src/grok-history-inject.test.mjs

@@ -0,0 +1,69 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import {
+  GROK_HANDOFF_SYNTHETIC_REASON,
+  injectGrokHandoffContext,
+} from './grok-history-inject.mjs';
+
+test('injectGrokHandoffContext inserts reminder before the latest user_query', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'tl-grok-inject-'));
+  const path = join(dir, 'chat_history.jsonl');
+  writeFileSync(
+    path,
+    [
+      JSON.stringify({ type: 'system', content: 'sys' }),
+      JSON.stringify({ type: 'user', content: [{ type: 'text', text: '<user_info>x</user_info>' }] }),
+      JSON.stringify({ type: 'user', content: [{ type: 'text', text: '<user_query>\nこれかな？\n</user_query>' }] }),
+    ].join('\n') + '\n',
+  );
+  try {
+    const result = injectGrokHandoffContext(path, 'old assistant body');
+    assert.equal(result.injected, true);
+    const rows = readFileSync(path, 'utf8')
+      .split('\n')
+      .filter(Boolean)
+      .map((line) => JSON.parse(line));
+    assert.equal(rows.length, 4);
+    assert.equal(rows[2].synthetic_reason, GROK_HANDOFF_SYNTHETIC_REASON);
+    assert.match(rows[2].content[0].text, /data-throughline-handoff="1"/);
+    assert.match(rows[2].content[0].text, /old assistant body/);
+    assert.match(rows[3].content[0].text, /これかな？/);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('injectGrokHandoffContext appends when no user_query exists yet', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'tl-grok-inject-'));
+  const path = join(dir, 'chat_history.jsonl');
+  writeFileSync(path, `${JSON.stringify({ type: 'system', content: 'sys' })}\n`);
+  try {
+    const result = injectGrokHandoffContext(path, 'memory');
+    assert.equal(result.injected, true);
+    const rows = readFileSync(path, 'utf8')
+      .split('\n')
+      .filter(Boolean)
+      .map((line) => JSON.parse(line));
+    assert.equal(rows.at(-1).synthetic_reason, GROK_HANDOFF_SYNTHETIC_REASON);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('injectGrokHandoffContext is idempotent', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'tl-grok-inject-'));
+  const path = join(dir, 'chat_history.jsonl');
+  try {
+    assert.equal(injectGrokHandoffContext(path, 'memory').injected, true);
+    assert.deepEqual(injectGrokHandoffContext(path, 'memory'), {
+      injected: false,
+      reason: 'already_present',
+    });
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});

package/src/hook-entrypoints.test.mjs

@@ -34,10 +34,10 @@ function childEnv(home) {
   };
 }
 
-function runNode(args, { home, cwd = REPO_ROOT, input = '' }) {
+function runNode(args, { home, cwd = REPO_ROOT, input = '', env = {} }) {
   return spawnSync(process.execPath, args, {
     cwd,
-    env: childEnv(home),
+    env: { ...childEnv(home), ...env },
     input,
     encoding: 'utf8',
   });
@@ -74,6 +74,202 @@ test('hook modules can be imported without executing their hook body', () => {
   }
 });
 
+test('Grok camelCase envelopes register a grok: session instead of no-op', () => {
+  const home = makeTempHome();
+  const project = makeTempProject();
+  const sessionId = '01a00aa2-50f8-7791-86fd-df2d27cf003e';
+  const common = {
+    sessionId,
+    cwd: project,
+    workspaceRoot: project,
+    timestamp: '2026-08-17T00:00:00Z',
+    permissionMode: 'default',
+  };
+
+  try {
+    const start = runNode([join(REPO_ROOT, 'src/session-start.mjs')], {
+      home,
+      cwd: project,
+      input: JSON.stringify({ ...common, hookEventName: 'session_start', source: 'startup' }),
+    });
+    assert.equal(start.status, 0, start.stderr);
+
+    const prompt = runNode([join(REPO_ROOT, 'src/prompt-submit.mjs')], {
+      home,
+      cwd: project,
+      input: JSON.stringify({ ...common, hookEventName: 'user_prompt_submit', prompt: 'hello grok' }),
+    });
+    assert.equal(prompt.status, 0, prompt.stderr);
+
+    const historyDir = join(home, '.grok', 'sessions', encodeURIComponent(project), sessionId);
+    mkdirSync(historyDir, { recursive: true });
+    writeFileSync(
+      join(historyDir, 'chat_history.jsonl'),
+      [
+        JSON.stringify({ type: 'user', content: [{ type: 'text', text: 'hello grok' }] }),
+        JSON.stringify({ type: 'assistant', content: 'captured reply' }),
+      ].join('\n'),
+    );
+    const stop = runNode([join(REPO_ROOT, 'src/turn-processor.mjs')], {
+      home,
+      cwd: project,
+      input: JSON.stringify({
+        ...common,
+        hookEventName: 'stop',
+        lastAssistantMessage: 'captured reply',
+      }),
+    });
+    assert.equal(stop.status, 0, stop.stderr);
+
+    const db = openDb(home);
+    const row = db.prepare('SELECT session_id, project_path FROM sessions').get();
+    assert.equal(row.session_id, `grok:${sessionId}`);
+    assert.equal(row.project_path, project);
+    const bodies = db.prepare('SELECT role, text FROM bodies ORDER BY role').all();
+    assert.deepEqual(
+      bodies.map((b) => ({ role: b.role, text: b.text })),
+      [
+        { role: 'assistant', text: 'captured reply' },
+        { role: 'user', text: 'hello grok' },
+      ],
+    );
+    db.close();
+  } finally {
+    rmSync(project, { recursive: true, force: true });
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test('Grok Stop with updates.jsonl transcriptPath still captures L2 from chat_history', () => {
+  const home = makeTempHome();
+  const project = makeTempProject();
+  const sessionId = '01a00b38-87ea-7670-8f7d-a9fe937263c5';
+  const common = {
+    sessionId,
+    cwd: project,
+    workspaceRoot: project,
+    timestamp: '2026-08-17T00:00:00Z',
+    permissionMode: 'default',
+  };
+
+  try {
+    const start = runNode([join(REPO_ROOT, 'src/session-start.mjs')], {
+      home,
+      cwd: project,
+      input: JSON.stringify({ ...common, hookEventName: 'session_start', source: 'startup' }),
+    });
+    assert.equal(start.status, 0, start.stderr);
+
+    const historyDir = join(home, '.grok', 'sessions', encodeURIComponent(project), sessionId);
+    mkdirSync(historyDir, { recursive: true });
+    writeFileSync(
+      join(historyDir, 'updates.jsonl'),
+      JSON.stringify({
+        method: '_x.ai/session/update',
+        params: { update: { sessionUpdate: 'hook_execution', event_name: 'stop' } },
+      }) + '\n',
+    );
+    writeFileSync(
+      join(historyDir, 'chat_history.jsonl'),
+      [
+        JSON.stringify({ type: 'user', content: [{ type: 'text', text: 'hello grok' }] }),
+        JSON.stringify({ type: 'assistant', content: 'captured reply' }),
+      ].join('\n'),
+    );
+    const stop = runNode([join(REPO_ROOT, 'src/turn-processor.mjs')], {
+      home,
+      cwd: project,
+      input: JSON.stringify({
+        ...common,
+        hookEventName: 'stop',
+        transcriptPath: join(historyDir, 'updates.jsonl'),
+        lastAssistantMessage: 'captured reply',
+      }),
+    });
+    assert.equal(stop.status, 0, stop.stderr);
+
+    const db = openDb(home);
+    const bodies = db.prepare('SELECT role, text FROM bodies ORDER BY role').all();
+    assert.deepEqual(
+      bodies.map((b) => ({ role: b.role, text: b.text })),
+      [
+        { role: 'assistant', text: 'captured reply' },
+        { role: 'user', text: 'hello grok' },
+      ],
+    );
+    db.close();
+  } finally {
+    rmSync(project, { recursive: true, force: true });
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test('Grok wrapped /tl prompt writes a grok: baton', () => {
+  const home = makeTempHome();
+  const project = makeTempProject();
+  const sessionId = '01a00b38-87ea-7670-8f7d-a9fe937263c5';
+  try {
+    const result = runNode([join(REPO_ROOT, 'src/prompt-submit.mjs')], {
+      home,
+      cwd: project,
+      input: JSON.stringify({
+        sessionId,
+        cwd: project,
+        hookEventName: 'user_prompt_submit',
+        prompt:
+          '<user_query>\n/tl\n</user_query>\n<skill_information>\nThroughline saved the baton.\n</skill_information>',
+      }),
+    });
+    assert.equal(result.status, 0, result.stderr);
+    assert.match(result.stderr, /grok-continue exited/);
+
+    const db = openDb(home);
+    const row = db.prepare('SELECT project_path, session_id FROM handoff_batons').get();
+    assert.equal(row.project_path, project);
+    assert.equal(row.session_id, `grok:${sessionId}`);
+    db.close();
+  } finally {
+    rmSync(project, { recursive: true, force: true });
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test('Grok empty hook prompt still writes /tl baton from chat_history', () => {
+  const home = makeTempHome();
+  const project = makeTempProject();
+  const sessionId = '01a00b38-87ea-7670-8f7d-a9fe937263c5';
+  const historyDir = join(home, '.grok', 'sessions', encodeURIComponent(project), sessionId);
+  mkdirSync(historyDir, { recursive: true });
+  writeFileSync(
+    join(historyDir, 'chat_history.jsonl'),
+    JSON.stringify({
+      type: 'user',
+      content: [{ type: 'text', text: '<user_query>\n/tl\n</user_query>\n<skill_information>x</skill_information>' }],
+    }) + '\n',
+  );
+  try {
+    const result = runNode([join(REPO_ROOT, 'src/prompt-submit.mjs')], {
+      home,
+      cwd: project,
+      input: JSON.stringify({
+        sessionId,
+        cwd: project,
+        hookEventName: 'user_prompt_submit',
+      }),
+    });
+    assert.equal(result.status, 0, result.stderr);
+    assert.match(result.stderr, /grok-continue exited/);
+
+    const db = openDb(home);
+    const row = db.prepare('SELECT session_id FROM handoff_batons').get();
+    assert.equal(row.session_id, `grok:${sessionId}`);
+    db.close();
+  } finally {
+    rmSync(project, { recursive: true, force: true });
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
 test('prompt-submit subprocess writes a /tl baton into an isolated DB', () => {
   const home = makeTempHome();
   const project = makeTempProject();
@@ -89,6 +285,7 @@ test('prompt-submit subprocess writes a /tl baton into an isolated DB', () => {
     });
 
     assert.equal(result.status, 0, result.stderr);
+    assert.equal(result.stderr.includes('grok-continue'), false);
 
     const db = openDb(home);
     const row = db.prepare('SELECT project_path, session_id FROM handoff_batons').get();
@@ -184,6 +381,87 @@ test('prompt-submit: non-baton prompt does not write any baton', () => {
   }
 });
 
+test('Grok first prompt injects handoff into chat_history instead of stdout', () => {
+  const home = makeTempHome();
+  const project = makeTempProject();
+  const oldId = '01a00aa2-50f8-7791-86fd-df2d27cf003e';
+  const newId = '01a00ce5-0169-7852-95c0-9e6b8cc50c06';
+  const historyDir = join(home, '.grok', 'sessions', encodeURIComponent(project), newId);
+  mkdirSync(historyDir, { recursive: true });
+  writeFileSync(
+    join(historyDir, 'chat_history.jsonl'),
+    [
+      JSON.stringify({ type: 'system', content: 'sys' }),
+      JSON.stringify({
+        type: 'user',
+        content: [{ type: 'text', text: '<user_query>\nこれかな？\n</user_query>' }],
+      }),
+    ].join('\n') + '\n',
+  );
+  try {
+    const baton = runNode([join(REPO_ROOT, 'src/prompt-submit.mjs')], {
+      home,
+      cwd: project,
+      input: JSON.stringify({
+        sessionId: oldId,
+        cwd: project,
+        hookEventName: 'user_prompt_submit',
+        prompt: '/tl',
+      }),
+    });
+    assert.equal(baton.status, 0, baton.stderr);
+
+    const db = openDb(home);
+    db.prepare(
+      `INSERT INTO sessions (session_id, project_path, status, created_at, updated_at)
+       VALUES (?, ?, 'active', 1, 1)`,
+    ).run(`grok:${oldId}`, project);
+    db.prepare(
+      `INSERT INTO bodies
+         (session_id, origin_session_id, turn_number, role, text, token_count, created_at)
+       VALUES (?, ?, 1, 'assistant', 'old assistant body', 4, 2)`,
+    ).run(`grok:${oldId}`, `grok:${oldId}`);
+    db.close();
+
+    const started = runNode([join(REPO_ROOT, 'src/session-start.mjs')], {
+      home,
+      cwd: project,
+      input: JSON.stringify({
+        sessionId: newId,
+        cwd: project,
+        hookEventName: 'session_start',
+        source: 'new',
+      }),
+    });
+    assert.equal(started.status, 0, started.stderr);
+
+    const firstPrompt = runNode([join(REPO_ROOT, 'src/prompt-submit.mjs')], {
+      home,
+      cwd: project,
+      input: JSON.stringify({
+        sessionId: newId,
+        cwd: project,
+        hookEventName: 'user_prompt_submit',
+        prompt: 'これかな？',
+      }),
+    });
+    assert.equal(firstPrompt.status, 0, firstPrompt.stderr);
+    assert.equal(firstPrompt.stdout, '', 'Grok must not rely on ignored hook stdout');
+
+    const rows = readFileSync(join(historyDir, 'chat_history.jsonl'), 'utf8')
+      .split('\n')
+      .filter(Boolean)
+      .map((line) => JSON.parse(line));
+    assert.equal(rows[1].synthetic_reason, 'system_reminder');
+    assert.match(rows[1].content[0].text, /data-throughline-handoff="1"/);
+    assert.match(rows[1].content[0].text, /old assistant body/);
+    assert.match(rows[2].content[0].text, /これかな？/);
+  } finally {
+    rmSync(project, { recursive: true, force: true });
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
 test('two-phase: session-start registers intent only; first prompt consumes baton and injects', () => {
   const home = makeTempHome();
   const project = makeTempProject();

package/src/hook-envelope.mjs

@@ -0,0 +1,51 @@
+// Grok sends Claude-compatible hook commands with a camelCase wire
+// (sessionId, hookEventName) and no session_id. Throughline treats that
+// envelope as host=grok: normalize to the Claude snake_case contract and
+// prefix session ids so they never mix with Claude predecessor search.
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export const GROK_SESSION_PREFIX = 'grok:';
+
+export function isGrokEnvelope(payload) {
+  return payload !== null
+    && typeof payload === 'object'
+    && typeof payload.sessionId === 'string'
+    && payload.sessionId.length > 0
+    && typeof payload.hookEventName === 'string'
+    && payload.hookEventName.length > 0
+    && !Object.hasOwn(payload, 'session_id');
+}
+
+export function grokBareSessionId(sessionId) {
+  if (typeof sessionId !== 'string' || sessionId.length === 0) return null;
+  return sessionId.startsWith(GROK_SESSION_PREFIX)
+    ? sessionId.slice(GROK_SESSION_PREFIX.length)
+    : sessionId;
+}
+
+export function deriveGrokChatHistoryPath(projectPath, sessionId, { home = homedir() } = {}) {
+  const bare = grokBareSessionId(sessionId);
+  if (!projectPath || !bare) return null;
+  return join(home, '.grok', 'sessions', encodeURIComponent(projectPath), bare, 'chat_history.jsonl');
+}
+
+export function normalizeHookPayload(payload, { home = homedir() } = {}) {
+  if (!isGrokEnvelope(payload)) return payload;
+  const cwd = typeof payload.cwd === 'string' && payload.cwd.length > 0
+    ? payload.cwd
+    : (typeof payload.workspaceRoot === 'string' ? payload.workspaceRoot : undefined);
+  // Live Grok Stop sets transcriptPath to updates.jsonl (sessionUpdate frames,
+  // no user/assistant rows). L2 lives in chat_history.jsonl only.
+  const transcriptPath = deriveGrokChatHistoryPath(cwd, payload.sessionId, { home });
+  return {
+    ...payload,
+    session_id: `${GROK_SESSION_PREFIX}${payload.sessionId}`,
+    cwd,
+    source: payload.source,
+    prompt: payload.prompt,
+    hook_event_name: payload.hookEventName,
+    transcript_path: transcriptPath,
+    last_assistant_message: payload.lastAssistantMessage,
+  };
+}

package/src/hook-envelope.test.mjs

@@ -0,0 +1,79 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { join } from 'node:path';
+
+import {
+  deriveGrokChatHistoryPath,
+  isGrokEnvelope,
+  normalizeHookPayload,
+} from './hook-envelope.mjs';
+
+test('isGrokEnvelope detects camelCase wire without session_id', () => {
+  assert.equal(
+    isGrokEnvelope({
+      sessionId: '01a00aa2-dead-beef',
+      hookEventName: 'session_start',
+      cwd: '/tmp/proj',
+    }),
+    true,
+  );
+  assert.equal(
+    isGrokEnvelope({
+      session_id: 'claude-session',
+      hook_event_name: 'SessionStart',
+    }),
+    false,
+  );
+});
+
+test('normalizeHookPayload prefixes grok: and derives chat_history path', () => {
+  const home = '/tmp/tl-home';
+  const cwd = '/Users/kite/Developer/dotagents';
+  const payload = normalizeHookPayload(
+    {
+      sessionId: '01a00aa2-dead-beef',
+      hookEventName: 'user_prompt_submit',
+      cwd,
+      prompt: 'hello',
+      lastAssistantMessage: 'hi',
+    },
+    { home },
+  );
+  assert.equal(payload.session_id, 'grok:01a00aa2-dead-beef');
+  assert.equal(payload.prompt, 'hello');
+  assert.equal(payload.last_assistant_message, 'hi');
+  assert.equal(
+    payload.transcript_path,
+    join(home, '.grok', 'sessions', encodeURIComponent(cwd), '01a00aa2-dead-beef', 'chat_history.jsonl'),
+  );
+  assert.equal(
+    deriveGrokChatHistoryPath(cwd, 'grok:01a00aa2-dead-beef', { home }),
+    payload.transcript_path,
+  );
+});
+
+test('normalizeHookPayload ignores Grok transcriptPath pointing at updates.jsonl', () => {
+  const home = '/tmp/tl-home';
+  const cwd = '/Users/kite/Developer/dotagents';
+  const sessionId = '01a00b38-87ea-7670-8f7d-a9fe937263c5';
+  const payload = normalizeHookPayload(
+    {
+      sessionId,
+      hookEventName: 'stop',
+      cwd,
+      transcriptPath: join(
+        home,
+        '.grok',
+        'sessions',
+        encodeURIComponent(cwd),
+        sessionId,
+        'updates.jsonl',
+      ),
+    },
+    { home },
+  );
+  assert.equal(
+    payload.transcript_path,
+    join(home, '.grok', 'sessions', encodeURIComponent(cwd), sessionId, 'chat_history.jsonl'),
+  );
+});