gramatr 0.3.0

package/bin/uninstall.ts

@@ -0,0 +1,289 @@
+#!/usr/bin/env node
+/**
+ * gramatr uninstaller — reverses install, restores configs to pre-gramatr state.
+ *
+ * Usage:
+ *   bun uninstall.ts              # Interactive — confirms each step
+ *   bun uninstall.ts --yes        # Non-interactive — uninstall everything
+ *   bun uninstall.ts --keep-auth  # Keep ~/.gmtr.json (preserve login)
+ *   npx tsx uninstall.ts          # Without bun
+ */
+
+import { existsSync, readFileSync, writeFileSync, rmSync, readdirSync, statSync } from 'fs';
+import { join, dirname } from 'path';
+import { createInterface } from 'readline';
+
+const HOME = process.env.HOME || process.env.USERPROFILE || '';
+const args = process.argv.slice(2);
+const YES = args.includes('--yes') || args.includes('-y');
+const KEEP_AUTH = args.includes('--keep-auth');
+
+function log(msg: string): void { process.stdout.write(`${msg}\n`); }
+
+async function confirm(msg: string): Promise<boolean> {
+  if (YES) return true;
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(`  ${msg} [Y/n]: `, (answer) => {
+      rl.close();
+      resolve(!answer || answer.toLowerCase() === 'y');
+    });
+  });
+}
+
+function findLatestBackup(filePath: string): string | null {
+  const dir = dirname(filePath);
+  const base = filePath.split('/').pop() || '';
+  try {
+    const files = readdirSync(dir)
+      .filter(f => f.startsWith(`${base}.backup-`))
+      .sort()
+      .reverse();
+    return files.length > 0 ? join(dir, files[0]) : null;
+  } catch { return null; }
+}
+
+function removeGramatrFromJson(filePath: string, keys: string[]): boolean {
+  try {
+    if (!existsSync(filePath)) return false;
+    const data = JSON.parse(readFileSync(filePath, 'utf8'));
+    let changed = false;
+    for (const key of keys) {
+      if (key in data) {
+        delete data[key];
+        changed = true;
+      }
+      // Handle nested keys like "env.GMTR_TOKEN"
+      if (key.includes('.')) {
+        const [parent, child] = key.split('.');
+        if (data[parent] && child in data[parent]) {
+          delete data[parent][child];
+          changed = true;
+        }
+      }
+    }
+    // Remove gramatr from mcpServers
+    if (data.mcpServers?.gramatr) {
+      delete data.mcpServers.gramatr;
+      changed = true;
+    }
+    if (changed) {
+      writeFileSync(filePath, JSON.stringify(data, null, 2) + '\n');
+    }
+    return changed;
+  } catch { return false; }
+}
+
+function dirSize(dir: string): string {
+  try {
+    let total = 0;
+    const walk = (d: string) => {
+      for (const f of readdirSync(d)) {
+        const p = join(d, f);
+        const s = statSync(p);
+        if (s.isDirectory()) walk(p); else total += s.size;
+      }
+    };
+    walk(dir);
+    if (total > 1048576) return `${(total / 1048576).toFixed(1)}MB`;
+    if (total > 1024) return `${(total / 1024).toFixed(0)}KB`;
+    return `${total}B`;
+  } catch { return '?'; }
+}
+
+async function main(): Promise<void> {
+  log('');
+  log('  gramatr uninstaller');
+  log('  ===================');
+  log('');
+
+  const gmtrClient = join(HOME, 'gmtr-client');
+  const gmtrJson = join(HOME, '.gmtr.json');
+  const gmtrDotDir = join(HOME, '.gmtr');
+  const claudeSettings = join(HOME, '.claude', 'settings.json');
+  const claudeJson = join(HOME, '.claude.json');
+  const claudeSkills = join(HOME, '.claude', 'skills');
+  const claudeAgents = join(HOME, '.claude', 'agents');
+  const claudeCommands = join(HOME, '.claude', 'commands');
+  const codexHooks = join(HOME, '.codex', 'hooks.json');
+  const codexAgents = join(HOME, '.codex', 'AGENTS.md');
+  const geminiExt = join(HOME, '.gemini', 'extensions', 'gramatr');
+
+  // Detect what's installed
+  const installed: string[] = [];
+  if (existsSync(gmtrClient)) installed.push(`~/gmtr-client (${dirSize(gmtrClient)})`);
+  if (existsSync(gmtrDotDir)) installed.push(`~/.gmtr/ (${dirSize(gmtrDotDir)})`);
+  if (existsSync(gmtrJson)) installed.push('~/.gmtr.json');
+  if (existsSync(claudeSettings)) installed.push('~/.claude/settings.json (hooks)');
+  if (existsSync(claudeJson)) installed.push('~/.claude.json (MCP server)');
+  if (existsSync(codexHooks)) installed.push('~/.codex/hooks.json');
+  if (existsSync(geminiExt)) installed.push(`~/.gemini/extensions/gramatr (${dirSize(geminiExt)})`);
+
+  if (installed.length === 0) {
+    log('  Nothing to uninstall — gramatr is not installed.');
+    log('');
+    return;
+  }
+
+  log('  Found:');
+  for (const item of installed) log(`    - ${item}`);
+  log('');
+
+  if (!await confirm('Proceed with uninstall?')) {
+    log('  Cancelled.');
+    return;
+  }
+
+  log('');
+
+  // 1. Remove ~/gmtr-client (hooks, bin, skills, agents, tools)
+  if (existsSync(gmtrClient)) {
+    rmSync(gmtrClient, { recursive: true, force: true });
+    log('  OK Removed ~/gmtr-client');
+  }
+
+  // 2. Remove ~/.gmtr/ (bun binary, PATH additions)
+  if (existsSync(gmtrDotDir)) {
+    rmSync(gmtrDotDir, { recursive: true, force: true });
+    log('  OK Removed ~/.gmtr/');
+  }
+
+  // 3. Remove ~/.gmtr.json (auth token) — unless --keep-auth
+  if (existsSync(gmtrJson)) {
+    if (KEEP_AUTH) {
+      log('  -- Kept ~/.gmtr.json (--keep-auth)');
+    } else {
+      rmSync(gmtrJson);
+      log('  OK Removed ~/.gmtr.json');
+    }
+  }
+
+  // 4. Restore ~/.claude/settings.json from backup or clean gramatr hooks
+  if (existsSync(claudeSettings)) {
+    const backup = findLatestBackup(claudeSettings);
+    if (backup && await confirm(`Restore settings.json from backup (${backup.split('/').pop()})?`)) {
+      const backupContent = readFileSync(backup, 'utf8');
+      writeFileSync(claudeSettings, backupContent);
+      log(`  OK Restored ~/.claude/settings.json from ${backup.split('/').pop()}`);
+    } else {
+      // Remove gramatr hooks from settings
+      try {
+        const settings = JSON.parse(readFileSync(claudeSettings, 'utf8'));
+        if (settings.hooks) {
+          // Remove hook entries that reference gmtr-client
+          for (const [event, hooks] of Object.entries(settings.hooks)) {
+            if (Array.isArray(hooks)) {
+              settings.hooks[event] = (hooks as any[]).filter(
+                (h: any) => !h.command?.includes('gmtr-client') && !h.command?.includes('gramatr')
+              );
+              if (settings.hooks[event].length === 0) delete settings.hooks[event];
+            }
+          }
+          if (Object.keys(settings.hooks).length === 0) delete settings.hooks;
+        }
+        if (settings.statusLine?.command?.includes('gmtr-client')) {
+          delete settings.statusLine;
+        }
+        writeFileSync(claudeSettings, JSON.stringify(settings, null, 2) + '\n');
+        log('  OK Removed gramatr hooks from ~/.claude/settings.json');
+      } catch {
+        log('  X Could not clean settings.json — restore from backup manually');
+      }
+    }
+  }
+
+  // 5. Remove gramatr from ~/.claude.json (MCP server + env vars)
+  if (existsSync(claudeJson)) {
+    const cleaned = removeGramatrFromJson(claudeJson, ['env.GMTR_TOKEN', 'env.AIOS_MCP_TOKEN']);
+    if (cleaned) log('  OK Removed gramatr MCP server + env vars from ~/.claude.json');
+  }
+
+  // 6. Remove gramatr skills from ~/.claude/skills/
+  if (existsSync(claudeSkills)) {
+    try {
+      const skillDirs = readdirSync(claudeSkills);
+      let removed = 0;
+      for (const dir of skillDirs) {
+        const skillPath = join(claudeSkills, dir);
+        // Check if it's a gramatr-installed skill (has gramatr marker or matches known patterns)
+        if (existsSync(join(skillPath, '.gramatr')) || existsSync(join(skillPath, 'README.md'))) {
+          rmSync(skillPath, { recursive: true, force: true });
+          removed++;
+        }
+      }
+      if (removed > 0) log(`  OK Removed ${removed} skill directories from ~/.claude/skills/`);
+    } catch { /* non-critical */ }
+  }
+
+  // 7. Remove gramatr agents from ~/.claude/agents/
+  if (existsSync(claudeAgents)) {
+    try {
+      rmSync(claudeAgents, { recursive: true, force: true });
+      log('  OK Removed ~/.claude/agents/');
+    } catch { /* non-critical */ }
+  }
+
+  // 8. Remove gramatr commands from ~/.claude/commands/
+  if (existsSync(claudeCommands)) {
+    try {
+      const cmds = readdirSync(claudeCommands).filter(f => f.startsWith('gmtr-') || f.startsWith('gramatr-'));
+      for (const cmd of cmds) {
+        rmSync(join(claudeCommands, cmd), { recursive: true, force: true });
+      }
+      if (cmds.length > 0) log(`  OK Removed ${cmds.length} gramatr commands from ~/.claude/commands/`);
+    } catch { /* non-critical */ }
+  }
+
+  // 9. Clean Codex config
+  if (existsSync(codexHooks)) {
+    try {
+      const hooks = JSON.parse(readFileSync(codexHooks, 'utf8'));
+      if (hooks.hooks) {
+        for (const [event, eventHooks] of Object.entries(hooks.hooks)) {
+          if (Array.isArray(eventHooks)) {
+            hooks.hooks[event] = (eventHooks as any[]).filter(
+              (h: any) => !h.command?.includes('gmtr-client') && !h.command?.includes('gramatr')
+            );
+            if (hooks.hooks[event].length === 0) delete hooks.hooks[event];
+          }
+        }
+        writeFileSync(codexHooks, JSON.stringify(hooks, null, 2) + '\n');
+        log('  OK Cleaned gramatr hooks from ~/.codex/hooks.json');
+      }
+    } catch { /* non-critical */ }
+  }
+  if (existsSync(codexAgents)) {
+    // Remove managed block from AGENTS.md
+    try {
+      let content = readFileSync(codexAgents, 'utf8');
+      const startMarker = '<!-- GMTR-CODEX-START -->';
+      const endMarker = '<!-- GMTR-CODEX-END -->';
+      const startIdx = content.indexOf(startMarker);
+      const endIdx = content.indexOf(endMarker);
+      if (startIdx !== -1 && endIdx !== -1) {
+        content = content.slice(0, startIdx) + content.slice(endIdx + endMarker.length);
+        writeFileSync(codexAgents, content.trim() + '\n');
+        log('  OK Removed gramatr block from ~/.codex/AGENTS.md');
+      }
+    } catch { /* non-critical */ }
+  }
+
+  // 10. Remove Gemini extension
+  if (existsSync(geminiExt)) {
+    rmSync(geminiExt, { recursive: true, force: true });
+    log('  OK Removed ~/.gemini/extensions/gramatr');
+  }
+
+  log('');
+  log('  Uninstall complete.');
+  log('  Restart Claude Code / Codex / Gemini CLI to apply changes.');
+  if (KEEP_AUTH) {
+    log('  Auth token preserved in ~/.gmtr.json (use --token with next install).');
+  }
+  log('');
+}
+
+main().catch((err) => {
+  log(`  Error: ${err.message}`);
+  process.exit(1);
+});

package/bin/version-sync.ts

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+/**
+ * version-sync — stamps the current package.json version into files that display it.
+ *
+ * Called automatically by:
+ *   npm run version:patch   →  0.3.0 → 0.3.1
+ *   npm run version:minor   →  0.3.0 → 0.4.0
+ *   npm run version:major   →  0.3.0 → 1.0.0
+ *   npm run prepublishOnly  →  ensures sync before publish
+ */
+
+import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const clientDir = dirname(__dirname);
+const pkg = JSON.parse(readFileSync(join(clientDir, 'package.json'), 'utf8'));
+const version = pkg.version;
+
+console.log(`gramatr version: ${version}`);
+
+// 1. Stamp into settings.json template (install.ts writes this)
+//    No file to patch — install.ts reads package.json at runtime.
+
+// 2. Stamp into CLAUDE.md if it has a version marker
+const claudeMd = join(clientDir, 'CLAUDE.md');
+if (existsSync(claudeMd)) {
+  let content = readFileSync(claudeMd, 'utf8');
+  const versionPattern = /gramatr\s+v[\d.]+/g;
+  const newContent = content.replace(versionPattern, `gramatr v${version}`);
+  if (newContent !== content) {
+    writeFileSync(claudeMd, newContent);
+    console.log(`  OK Stamped version in CLAUDE.md`);
+  }
+}
+
+// 3. Write a version.ts module that other TS files can import
+const versionTs = join(clientDir, 'core', 'version.ts');
+writeFileSync(versionTs, `/** Auto-generated by version-sync.ts — do not edit */\nexport const VERSION = '${version}';\n`);
+console.log(`  OK Wrote core/version.ts`);
+
+// 4. Log next steps
+console.log('');
+console.log(`  To publish: npm publish --access public`);
+console.log(`  To tag:     git tag v${version} && git push origin v${version}`);

package/codex/README.md

@@ -0,0 +1,28 @@
+# Codex Integration
+
+This directory contains the first-pass Codex client scaffolding for gramatr.
+
+Current scope:
+- TypeScript hook implementations for `UserPromptSubmit` and `SessionStart`
+- pure formatting utilities with Vitest coverage
+- a repo-local `.codex/hooks.json` template
+- a fallback `AGENTS.md` template for Codex sessions
+
+Runtime approach:
+- use Codex hooks for interception and session restore
+- keep the hook code in TypeScript
+- keep formatting/decision logic in pure utility modules so coverage is meaningful
+
+Packaging direction:
+- hooks remain the runtime interception layer
+- plugin packaging remains the distribution/update layer
+
+Install locally with:
+- `pnpm --filter @aios-v2/client install-codex`
+
+The installer:
+- syncs this Codex runtime into `~/gmtr-client/codex`
+- syncs the shared `gmtr-hook-utils.ts` dependency into `~/gmtr-client/hooks/lib`
+- merges `~/.codex/hooks.json`
+- enables `codex_hooks` in `~/.codex/config.toml`
+- upserts a managed gramatr block in `~/.codex/AGENTS.md`

package/codex/hooks/session-start.ts

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+
+import {
+  getGitContext,
+  readHookInput,
+} from '../../hooks/lib/gmtr-hook-utils.ts';
+import {
+  loadProjectHandoff,
+  normalizeSessionStartResponse,
+  persistSessionRegistration,
+  prepareProjectSessionState,
+  startRemoteSession,
+} from '../../core/session.ts';
+import {
+  buildCodexHookOutput,
+  buildSessionStartAdditionalContext,
+  type HandoffResponse,
+  type SessionStartResponse,
+} from '../lib/codex-hook-utils.ts';
+
+async function main(): Promise<void> {
+  try {
+    const input = await readHookInput();
+    const git = getGitContext();
+    if (!git) return;
+
+    const transcriptPath = input.transcript_path || '';
+    const sessionId = input.session_id || 'unknown';
+    const prepared = prepareProjectSessionState({
+      git,
+      sessionId,
+      transcriptPath,
+    });
+
+    const sessionStart = (await startRemoteSession({
+      clientType: 'codex',
+      sessionId: input.session_id,
+      projectId: prepared.projectId,
+      projectName: git.projectName,
+      gitRemote: git.remote,
+      directory: git.root,
+    })) as SessionStartResponse | null;
+
+    if (sessionStart) {
+      persistSessionRegistration(git.root, sessionStart);
+    }
+
+    const handoff = (await loadProjectHandoff(prepared.projectId)) as HandoffResponse | null;
+    const normalizedSessionStart = sessionStart
+      ? {
+          ...sessionStart,
+          interaction_id: normalizeSessionStartResponse(sessionStart).interactionId || undefined,
+        }
+      : null;
+
+    const additionalContext = buildSessionStartAdditionalContext(
+      prepared.projectId,
+      normalizedSessionStart,
+      handoff,
+    );
+    const output = buildCodexHookOutput(
+      'SessionStart',
+      additionalContext,
+      'gramatr session context loaded',
+    );
+
+    process.stdout.write(JSON.stringify(output));
+  } catch {
+    // Never block startup if the hook fails.
+  }
+}
+
+void main();

package/codex/hooks/stop.ts

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+
+import {
+  getGitContext,
+  readHookInput,
+} from '../../hooks/lib/gmtr-hook-utils.ts';
+import { parseTranscript } from '../../hooks/lib/transcript-parser.ts';
+import { submitPendingClassificationFeedback } from '../../hooks/lib/classification-feedback.ts';
+
+async function main(): Promise<void> {
+  try {
+    const input = await readHookInput();
+    if (!input.transcript_path || !input.session_id) return;
+
+    const git = getGitContext();
+    if (!git) return;
+
+    const parsed = parseTranscript(input.transcript_path);
+    if (parsed.responseState !== 'completed') return;
+
+    await submitPendingClassificationFeedback({
+      rootDir: git.root,
+      sessionId: input.session_id,
+      originalPrompt: parsed.lastUserPrompt,
+      clientType: 'codex',
+      agentName: 'Codex',
+      downstreamProvider: 'openai',
+    });
+  } catch {
+    // Never block completion if the hook fails.
+  }
+}
+
+void main();

package/codex/hooks/user-prompt-submit.ts

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+
+import {
+  deriveProjectId,
+  getGitContext,
+  readHookInput,
+} from '../../hooks/lib/gmtr-hook-utils.ts';
+import {
+  describeRoutingFailure,
+  persistClassificationResult,
+  routePrompt,
+  shouldSkipPromptRouting,
+} from '../../core/routing.ts';
+import {
+  buildHookFailureAdditionalContext,
+  buildCodexHookOutput,
+  buildUserPromptAdditionalContext,
+  type RouteResponse,
+} from '../lib/codex-hook-utils.ts';
+
+async function main(): Promise<void> {
+  try {
+    const input = await readHookInput();
+    const prompt = (input.prompt || input.message || '').trim();
+
+    if (shouldSkipPromptRouting(prompt)) {
+      return;
+    }
+
+    const git = getGitContext();
+    const projectId = git ? deriveProjectId(git.remote, git.projectName) : undefined;
+    const result = await routePrompt({
+      prompt,
+      projectId,
+      sessionId: input.session_id,
+      timeoutMs: 15000,
+    });
+    const route = result.route as RouteResponse | null;
+
+    if (!route) {
+      if (result.error) {
+        const failure = describeRoutingFailure(result.error);
+        const output = buildCodexHookOutput(
+          'UserPromptSubmit',
+          buildHookFailureAdditionalContext(failure),
+          'gramatr request routing unavailable',
+        );
+        process.stdout.write(JSON.stringify(output));
+      }
+      return;
+    }
+
+    const additionalContext = buildUserPromptAdditionalContext(route);
+    if (git) {
+      persistClassificationResult({
+        rootDir: git.root,
+        prompt,
+        route,
+        downstreamModel: null,
+        clientType: 'codex',
+        agentName: 'Codex',
+      });
+    }
+    const output = buildCodexHookOutput(
+      'UserPromptSubmit',
+      additionalContext,
+      'gramatr request routing active',
+    );
+
+    process.stdout.write(JSON.stringify(output));
+  } catch {
+    // Never block the user prompt if the hook fails.
+  }
+}
+
+void main();

package/codex/install.ts

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync, copyFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+import {
+  buildManagedHooks,
+  ensureCodexHooksFeature,
+  mergeHooksFile,
+  upsertManagedBlock,
+} from './lib/codex-install-utils.ts';
+
+const START_MARKER = '<!-- GMTR-CODEX-START -->';
+const END_MARKER = '<!-- GMTR-CODEX-END -->';
+
+function log(message: string): void {
+  process.stdout.write(`${message}\n`);
+}
+
+function ensureDir(path: string): void {
+  if (!existsSync(path)) mkdirSync(path, { recursive: true });
+}
+
+function copyRecursive(source: string, target: string): void {
+  const stats = statSync(source);
+
+  if (stats.isDirectory()) {
+    ensureDir(target);
+    for (const entry of readdirSync(source)) {
+      copyRecursive(join(source, entry), join(target, entry));
+    }
+    return;
+  }
+
+  ensureDir(dirname(target));
+  copyFileSync(source, target);
+}
+
+function readJsonFile<T>(path: string, fallback: T): T {
+  if (!existsSync(path)) return fallback;
+  return JSON.parse(readFileSync(path, 'utf8')) as T;
+}
+
+function main(): void {
+  const home = process.env.HOME || process.env.USERPROFILE;
+  if (!home) {
+    throw new Error('HOME is not set');
+  }
+
+  const gmtrDir = process.env.GMTR_DIR || join(home, 'gmtr-client');
+  const codexHome = join(home, '.codex');
+  const hooksPath = join(codexHome, 'hooks.json');
+  const configPath = join(codexHome, 'config.toml');
+  const agentsPath = join(codexHome, 'AGENTS.md');
+
+  const currentFile = fileURLToPath(import.meta.url);
+  const codexSourceDir = dirname(currentFile);
+  const clientSourceDir = dirname(codexSourceDir);
+  const packagesDir = dirname(clientSourceDir);
+  const repoRoot = dirname(packagesDir);
+  const codexTargetDir = join(gmtrDir, 'codex');
+  const sharedHookUtilsSource = join(clientSourceDir, 'hooks', 'lib', 'gmtr-hook-utils.ts');
+  const sharedHookUtilsTarget = join(gmtrDir, 'hooks', 'lib', 'gmtr-hook-utils.ts');
+  const managedAgentsContent = readFileSync(join(repoRoot, 'AGENTS.md'), 'utf8');
+
+  ensureDir(gmtrDir);
+  ensureDir(codexHome);
+
+  copyRecursive(codexSourceDir, codexTargetDir);
+  copyRecursive(sharedHookUtilsSource, sharedHookUtilsTarget);
+  log(`OK Synced Codex runtime to ${codexTargetDir}`);
+
+  const managedHooks = buildManagedHooks(gmtrDir);
+  const existingHooks = readJsonFile(hooksPath, { hooks: {} });
+  const mergedHooks = mergeHooksFile(existingHooks, managedHooks);
+  writeFileSync(hooksPath, `${JSON.stringify(mergedHooks, null, 2)}\n`, 'utf8');
+  log(`OK Updated ${hooksPath}`);
+
+  const existingConfig = existsSync(configPath) ? readFileSync(configPath, 'utf8') : '';
+  const updatedConfig = ensureCodexHooksFeature(existingConfig);
+  writeFileSync(configPath, updatedConfig, 'utf8');
+  log(`OK Enabled Codex hooks in ${configPath}`);
+
+  const existingAgents = existsSync(agentsPath) ? readFileSync(agentsPath, 'utf8') : '';
+  const managedAgents = upsertManagedBlock(
+    existingAgents,
+    managedAgentsContent,
+    START_MARKER,
+    END_MARKER,
+  );
+  writeFileSync(agentsPath, managedAgents, 'utf8');
+  log(`OK Updated ${agentsPath}`);
+
+  log('');
+  log('Codex installer complete.');
+  log('Restart Codex or start a new session to load the updated hook configuration.');
+}
+
+main();

package/codex/lib/codex-hook-utils.ts

@@ -0,0 +1,48 @@
+import {
+  buildHookFailureAdditionalContext,
+  buildSessionStartAdditionalContext,
+  buildUserPromptAdditionalContext,
+} from '../../core/formatting.ts';
+import type {
+  HandoffResponse,
+  HookFailure,
+  RouteResponse,
+  SessionStartResponse,
+} from '../../core/types.ts';
+
+export type {
+  HandoffResponse,
+  HookFailure,
+  RouteResponse,
+  SessionStartResponse,
+};
+
+export interface CodexHookOutput {
+  continue: boolean;
+  hookSpecificOutput: {
+    hookEventName: 'UserPromptSubmit' | 'SessionStart';
+    additionalContext: string;
+  };
+  systemMessage?: string;
+}
+
+export {
+  buildHookFailureAdditionalContext,
+  buildSessionStartAdditionalContext,
+  buildUserPromptAdditionalContext,
+};
+
+export function buildCodexHookOutput(
+  hookEventName: 'UserPromptSubmit' | 'SessionStart',
+  additionalContext: string,
+  systemMessage?: string,
+): CodexHookOutput {
+  return {
+    continue: true,
+    hookSpecificOutput: {
+      hookEventName,
+      additionalContext,
+    },
+    ...(systemMessage ? { systemMessage } : {}),
+  };
+}