agent-freeway 0.1.0-alpha.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,180 @@
+# agent-freeway
+
+`agent-freeway` is a small hook-first bridge for local agent runtimes such as Claude Code and Codex.
+
+It is intentionally narrow:
+
+- send a message to a runtime
+- normalize runtime hook events
+- resolve those events onto your own application thread id
+- deliver the normalized event through a product adapter
+
+It does **not** include product-specific backend logic, pairing UX, feed/card models, scan/watch daemons, or history sync.
+
+## Install
+
+```bash
+npm install -g agent-freeway
+```
+
+## Concepts
+
+There are two ids:
+
+- `sessionId`: the runtime session/thread id used by Claude Code or Codex
+- `appThreadId`: your own stable conversation id
+
+`agent-freeway` stores an explicit mapping between them. It does not guess by working directory.
+
+## Commands
+
+### Register a mapping
+
+```bash
+agent-freeway register \
+  --runtime claude_code \
+  --app-thread-id thread_123 \
+  --session-id claude_session_456 \
+  --project-dir /path/to/repo
+```
+
+```bash
+agent-freeway register \
+  --runtime codex \
+  --app-thread-id thread_123 \
+  --session-id codex_thread_456 \
+  --cwd /path/to/repo
+```
+
+### Send a message
+
+Resume an existing Claude Code session:
+
+```bash
+agent-freeway send \
+  --runtime claude_code \
+  --app-thread-id thread_123 \
+  --text "hello"
+```
+
+Create a new Claude Code session:
+
+```bash
+agent-freeway send \
+  --runtime claude_code \
+  --app-thread-id thread_123 \
+  --project-dir /path/to/repo \
+  --text "start a new session"
+```
+
+Resume an existing Codex session:
+
+```bash
+agent-freeway send \
+  --runtime codex \
+  --app-thread-id thread_123 \
+  --text "hello"
+```
+
+Create a new Codex session:
+
+```bash
+agent-freeway send \
+  --runtime codex \
+  --app-thread-id thread_123 \
+  --cwd /path/to/repo \
+  --text "start a new session"
+```
+
+### Dispatch a hook event through an adapter
+
+Ticlawk:
+
+```bash
+agent-freeway dispatch-hook \
+  --runtime claude_code \
+  --adapter ticlawk
+```
+
+Telegram:
+
+```bash
+agent-freeway dispatch-hook \
+  --runtime codex \
+  --adapter telegram
+```
+
+The command reads the hook payload from stdin, resolves the runtime `session_id` to a registered `appThreadId`, normalizes the event, and passes it into the selected adapter.
+
+Built-in adapters:
+
+- `ticlawk`
+- `telegram`
+
+Low-level raw webhook delivery is still available, but it is treated as a helper transport rather than the main adapter surface.
+
+### Raw webhook delivery
+
+```bash
+agent-freeway dispatch-hook \
+  --runtime codex \
+  --webhook https://example.com/agent-events
+```
+
+## Webhook payload
+
+```json
+{
+  "runtime": "codex",
+  "kind": "assistant",
+  "appThreadId": "thread_123",
+  "runtimeSessionId": "codex_thread_456",
+  "text": "done",
+  "timestamp": "2026-04-06T00:00:00.000Z"
+}
+```
+
+## Adapter configuration
+
+### Ticlawk
+
+```bash
+export TICLAWK_API_URL=https://ticlawk.com
+export TICLAWK_API_KEY=tk_xxxx
+```
+
+The `ticlawk` adapter maps:
+
+- `appThreadId` -> `channelId`
+- `assistant` -> `type: "assistant"`
+- `user` -> `type: "user"`
+
+### Telegram
+
+```bash
+export TELEGRAM_BOT_TOKEN=123:abc
+export TELEGRAM_CHAT_ID=123456789
+```
+
+The `telegram` adapter sends normalized events into `sendMessage`.
+
+## Hook snippets
+
+Print a ready-to-paste hook command:
+
+```bash
+agent-freeway print-hook --runtime claude_code --adapter ticlawk
+agent-freeway print-hook --runtime codex --adapter ticlawk
+```
+
+## Storage
+
+Mappings are stored in:
+
+```bash
+~/.agent-freeway/registrations.json
+```
+
+## Scope
+
+This package is best used as a small runtime bridge with product adapters, not as a full agent platform.

package/bin/agent-freeway.mjs

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import {
+  dispatchHookToAdapter,
+  dispatchHookToWebhook,
+  listRegistrations,
+  sendMessage,
+  upsertRegistration,
+} from '../src/index.mjs';
+
+function parseArgs(argv) {
+  const args = { _: [] };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg.startsWith('--')) {
+      const key = arg.slice(2);
+      const value = argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[++i] : true;
+      args[key] = value;
+    } else {
+      args._.push(arg);
+    }
+  }
+  return args;
+}
+
+function printUsage() {
+  console.log(`agent-freeway
+
+Usage:
+  agent-freeway register --runtime <claude_code|codex> --app-thread-id <id> --session-id <id> [--project-dir <dir>] [--cwd <dir>]
+  agent-freeway list
+  agent-freeway send --runtime <claude_code|codex> --text <message> [--app-thread-id <id>] [--session-id <id>] [--project-dir <dir>] [--cwd <dir>]
+  agent-freeway dispatch-hook --runtime <claude_code|codex> --adapter <ticlawk|telegram> [adapter flags]
+  agent-freeway dispatch-hook --runtime <claude_code|codex> --webhook <url> [--bearer-token <token>]
+  agent-freeway print-hook --runtime <claude_code|codex> --adapter <ticlawk|telegram> [adapter flags]
+  agent-freeway version
+`);
+}
+
+async function readStdinJson() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  const text = Buffer.concat(chunks).toString('utf8').trim();
+  return text ? JSON.parse(text) : {};
+}
+
+function printCodexContinue() {
+  process.stdout.write('{"continue":true}\n');
+}
+
+function requireRuntime(runtime) {
+  if (runtime !== 'claude_code' && runtime !== 'codex') {
+    throw new Error('--runtime must be claude_code or codex');
+  }
+  return runtime;
+}
+
+function printHookCommand({ runtime, webhookUrl, bearerToken }) {
+  const parts = ['agent-freeway', 'dispatch-hook', '--runtime', runtime];
+  if (webhookUrl) parts.push('--webhook', JSON.stringify(webhookUrl));
+  if (bearerToken) parts.push('--bearer-token', JSON.stringify(bearerToken));
+  console.log(parts.join(' '));
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const command = args._[0];
+
+  if (!command || command === 'help' || args.help) {
+    printUsage();
+    return;
+  }
+
+  if (command === 'version' || args.version) {
+    const pkgPath = join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json');
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+    console.log(pkg.version);
+    return;
+  }
+
+  if (command === 'register') {
+    const runtime = requireRuntime(args.runtime);
+    if (!args['app-thread-id']) throw new Error('--app-thread-id is required');
+    if (!args['session-id']) throw new Error('--session-id is required');
+    const registration = upsertRegistration({
+      runtime,
+      appThreadId: String(args['app-thread-id']),
+      sessionId: String(args['session-id']),
+      cwd: args.cwd ? String(args.cwd) : null,
+      projectDir: args['project-dir'] ? String(args['project-dir']) : null,
+    });
+    console.log(JSON.stringify(registration, null, 2));
+    return;
+  }
+
+  if (command === 'list') {
+    console.log(JSON.stringify(listRegistrations(), null, 2));
+    return;
+  }
+
+  if (command === 'send') {
+    const runtime = requireRuntime(args.runtime);
+    const result = await sendMessage({
+      runtime,
+      appThreadId: args['app-thread-id'] ? String(args['app-thread-id']) : null,
+      sessionId: args['session-id'] ? String(args['session-id']) : null,
+      text: args.text ? String(args.text) : '',
+      cwd: args.cwd ? String(args.cwd) : null,
+      projectDir: args['project-dir'] ? String(args['project-dir']) : null,
+    });
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  if (command === 'dispatch-hook') {
+    const runtime = requireRuntime(args.runtime);
+    const event = await readStdinJson();
+    try {
+      const delivered = args.adapter
+        ? await dispatchHookToAdapter({
+            runtime,
+            event,
+            adapter: String(args.adapter),
+            options: {
+              apiUrl: args['api-url'] ? String(args['api-url']) : undefined,
+              apiKey: args['api-key'] ? String(args['api-key']) : undefined,
+              botToken: args['bot-token'] ? String(args['bot-token']) : undefined,
+              chatId: args['chat-id'] ? String(args['chat-id']) : undefined,
+              webhookUrl: args.webhook ? String(args.webhook) : undefined,
+              bearerToken: args['bearer-token'] ? String(args['bearer-token']) : undefined,
+            },
+          })
+        : await dispatchHookToWebhook({
+            runtime,
+            event,
+            webhookUrl: args.webhook ? String(args.webhook) : undefined,
+            bearerToken: args['bearer-token'] ? String(args['bearer-token']) : undefined,
+          });
+      if (runtime === 'codex') printCodexContinue();
+      if (delivered) {
+        console.error(`[agent-freeway] delivered ${delivered.kind} for ${runtime}:${delivered.runtimeSessionId}`);
+      }
+      return;
+    } catch (err) {
+      if (runtime === 'codex') printCodexContinue();
+      console.error(`[agent-freeway] ${err.message}`);
+      process.exitCode = 1;
+      return;
+    }
+  }
+
+  if (command === 'print-hook') {
+    const runtime = requireRuntime(args.runtime);
+    if (args.adapter === 'ticlawk') {
+      console.log(`agent-freeway dispatch-hook --runtime ${runtime} --adapter ticlawk`);
+      return;
+    }
+    if (args.adapter === 'telegram') {
+      console.log(`agent-freeway dispatch-hook --runtime ${runtime} --adapter telegram`);
+      return;
+    }
+    printHookCommand({
+      runtime,
+      webhookUrl: args.webhook ? String(args.webhook) : undefined,
+      bearerToken: args['bearer-token'] ? String(args['bearer-token']) : undefined,
+    });
+    return;
+  }
+
+  throw new Error(`unknown command: ${command}`);
+}
+
+main().catch((err) => {
+  console.error(err.message || String(err));
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "agent-freeway",
+  "version": "0.1.0-alpha.2",
+  "description": "Hook-first runtime bridge for Claude Code and Codex.",
+  "type": "module",
+  "main": "src/index.mjs",
+  "bin": {
+    "agent-freeway": "bin/agent-freeway.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "check": "node --check bin/agent-freeway.mjs && node --check src/index.mjs && node --check src/store/file-store.mjs && node --check src/delivery/webhook.mjs && node --check src/adapters/ticlawk.mjs && node --check src/adapters/telegram.mjs && node --check src/runtimes/claude-code.mjs && node --check src/runtimes/codex.mjs"
+  },
+  "keywords": [
+    "agent",
+    "bridge",
+    "claude-code",
+    "codex",
+    "hooks"
+  ],
+  "author": "ticlawk",
+  "license": "MIT"
+}

package/src/adapters/telegram.mjs

@@ -0,0 +1,30 @@
+function buildTelegramText(event) {
+  const runtime = event?.runtime || 'agent';
+  const prefix = event?.kind === 'user' ? 'User' : 'Assistant';
+  return `[${runtime}] ${prefix}\n\n${event?.text || ''}`;
+}
+
+export async function deliverToTelegram(event, options = {}) {
+  const botToken = options.botToken || process.env.TELEGRAM_BOT_TOKEN || '';
+  const chatId = options.chatId || event?.appThreadId || process.env.TELEGRAM_CHAT_ID || '';
+  if (!botToken) throw new Error('TELEGRAM_BOT_TOKEN is required');
+  if (!chatId) throw new Error('Telegram chat id is required');
+
+  const res = await fetch(`https://api.telegram.org/bot${botToken}/sendMessage`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      chat_id: chatId,
+      text: buildTelegramText(event),
+      disable_web_page_preview: false,
+    }),
+    signal: AbortSignal.timeout(Number(options.timeoutMs || 15000)),
+  });
+
+  if (!res.ok) {
+    const text = await res.text().catch(() => '');
+    throw new Error(`telegram ${res.status}: ${text || res.statusText}`);
+  }
+
+  return true;
+}

package/src/adapters/ticlawk.mjs

@@ -0,0 +1,51 @@
+async function ticlawkFetch(path, options = {}) {
+  const apiUrl = options.apiUrl || process.env.TICLAWK_API_URL || 'https://ticlawk.com';
+  const apiKey = options.apiKey || process.env.TICLAWK_API_KEY || '';
+  if (!apiKey) throw new Error('TICLAWK_API_KEY is required');
+
+  const res = await fetch(`${apiUrl}${path}`, {
+    method: options.method || 'POST',
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify(options.body || {}),
+    signal: AbortSignal.timeout(Number(options.timeoutMs || 15000)),
+  });
+
+  if (!res.ok) {
+    const text = await res.text().catch(() => '');
+    throw new Error(`ticlawk ${res.status}: ${text || res.statusText}`);
+  }
+
+  return res;
+}
+
+export function toTiclawkDispatchEvent(event) {
+  if (!event?.appThreadId) {
+    throw new Error('appThreadId is required for ticlawk delivery');
+  }
+  if (!event?.text) {
+    throw new Error('text is required for ticlawk delivery');
+  }
+  if (event.kind !== 'assistant' && event.kind !== 'user') {
+    throw new Error(`unsupported ticlawk event kind: ${event.kind}`);
+  }
+  return {
+    type: event.kind,
+    text: event.text,
+    channelId: event.appThreadId,
+    timestamp: event.timestamp || new Date().toISOString(),
+  };
+}
+
+export async function deliverToTiclawk(event, options = {}) {
+  const payload = toTiclawkDispatchEvent(event);
+  await ticlawkFetch('/dispatch', {
+    apiUrl: options.apiUrl,
+    apiKey: options.apiKey,
+    timeoutMs: options.timeoutMs,
+    body: payload,
+  });
+  return payload;
+}

package/src/delivery/webhook.mjs

@@ -0,0 +1,25 @@
+export async function deliverToWebhook(event, options = {}) {
+  const webhookUrl = options.webhookUrl || process.env.AGENT_BRIDGE_WEBHOOK_URL;
+  const bearerToken = options.bearerToken || process.env.AGENT_BRIDGE_WEBHOOK_BEARER || '';
+
+  if (!webhookUrl) {
+    throw new Error('webhook URL is required');
+  }
+
+  const res = await fetch(webhookUrl, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      ...(bearerToken ? { Authorization: `Bearer ${bearerToken}` } : {}),
+    },
+    body: JSON.stringify(event),
+    signal: AbortSignal.timeout(Number(options.timeoutMs || 15000)),
+  });
+
+  if (!res.ok) {
+    const text = await res.text().catch(() => '');
+    throw new Error(`webhook ${res.status}: ${text || res.statusText}`);
+  }
+
+  return true;
+}

package/src/index.mjs

@@ -0,0 +1,139 @@
+import {
+  listRegistrations,
+  resolveByAppThreadId,
+  resolveBySessionId,
+  upsertRegistration,
+} from './store/file-store.mjs';
+import { deliverToWebhook } from './delivery/webhook.mjs';
+import { deliverToTiclawk } from './adapters/ticlawk.mjs';
+import { deliverToTelegram } from './adapters/telegram.mjs';
+import {
+  createClaudeSession,
+  normalizeClaudeHookEvent,
+  resumeClaudeSession,
+} from './runtimes/claude-code.mjs';
+import {
+  createCodexSession,
+  normalizeCodexHookEvent,
+  resumeCodexSession,
+} from './runtimes/codex.mjs';
+
+export {
+  listRegistrations,
+  resolveByAppThreadId,
+  resolveBySessionId,
+  upsertRegistration,
+  deliverToWebhook,
+  deliverToTiclawk,
+  deliverToTelegram,
+  createClaudeSession,
+  normalizeClaudeHookEvent,
+  resumeClaudeSession,
+  createCodexSession,
+  normalizeCodexHookEvent,
+  resumeCodexSession,
+};
+
+export function normalizeRuntimeHook({ runtime, event, registration }) {
+  return runtime === 'claude_code'
+    ? normalizeClaudeHookEvent(event, registration)
+    : runtime === 'codex'
+      ? normalizeCodexHookEvent(event, registration)
+      : null;
+}
+
+export async function dispatchHookEvent({ runtime, event, deliver }) {
+  const sessionId = event?.session_id ? String(event.session_id) : '';
+  if (!sessionId) return null;
+
+  const registration = resolveBySessionId(runtime, sessionId);
+  if (!registration) {
+    throw new Error(`no registration for ${runtime}:${sessionId}`);
+  }
+
+  const normalized = normalizeRuntimeHook({ runtime, event, registration });
+
+  if (!normalized) return null;
+  if (deliver) {
+    await deliver(normalized, registration);
+  }
+  return normalized;
+}
+
+export async function dispatchHookToWebhook({ runtime, event, webhookUrl, bearerToken }) {
+  return dispatchHookEvent({
+    runtime,
+    event,
+    deliver: (normalized) => deliverToWebhook(normalized, { webhookUrl, bearerToken }),
+  });
+}
+
+export async function dispatchHookToAdapter({ runtime, event, adapter, options = {} }) {
+  if (adapter === 'ticlawk') {
+    return dispatchHookEvent({
+      runtime,
+      event,
+      deliver: (normalized) => deliverToTiclawk(normalized, options),
+    });
+  }
+  if (adapter === 'telegram') {
+    return dispatchHookEvent({
+      runtime,
+      event,
+      deliver: (normalized) => deliverToTelegram(normalized, options),
+    });
+  }
+  if (adapter === 'webhook') {
+    return dispatchHookToWebhook({
+      runtime,
+      event,
+      webhookUrl: options.webhookUrl,
+      bearerToken: options.bearerToken,
+    });
+  }
+  throw new Error(`unsupported adapter: ${adapter}`);
+}
+
+export async function sendMessage({ runtime, appThreadId, sessionId, text, cwd, projectDir }) {
+  if (!runtime) throw new Error('runtime is required');
+  if (!text) throw new Error('text is required');
+
+  const registration = appThreadId ? resolveByAppThreadId(runtime, appThreadId) : null;
+  const effectiveSessionId = sessionId || registration?.sessionId || null;
+
+  if (runtime === 'claude_code') {
+    const effectiveProjectDir = projectDir || registration?.projectDir || null;
+    if (effectiveSessionId) {
+      return resumeClaudeSession({ sessionId: effectiveSessionId, projectDir: effectiveProjectDir, text });
+    }
+    const created = createClaudeSession({ projectDir: effectiveProjectDir, text });
+    if (appThreadId) {
+      upsertRegistration({
+        runtime,
+        appThreadId,
+        sessionId: created.sessionId,
+        projectDir: created.projectDir,
+      });
+    }
+    return created;
+  }
+
+  if (runtime === 'codex') {
+    const effectiveCwd = cwd || registration?.cwd || null;
+    if (effectiveSessionId) {
+      return resumeCodexSession({ sessionId: effectiveSessionId, cwd: effectiveCwd, text });
+    }
+    const created = await createCodexSession({ cwd: effectiveCwd, text });
+    if (appThreadId) {
+      upsertRegistration({
+        runtime,
+        appThreadId,
+        sessionId: created.sessionId,
+        cwd: created.cwd,
+      });
+    }
+    return created;
+  }
+
+  throw new Error(`unsupported runtime: ${runtime}`);
+}

package/src/runtimes/claude-code.mjs

@@ -0,0 +1,56 @@
+import { execSync, spawn } from 'node:child_process';
+
+export function normalizeClaudeHookEvent(event, registration) {
+  if (event?.hook_event_name !== 'Stop') return null;
+  if (!event?.last_assistant_message || !event?.session_id) return null;
+  if (!registration?.appThreadId) return null;
+  return {
+    runtime: 'claude_code',
+    kind: 'assistant',
+    appThreadId: registration.appThreadId,
+    runtimeSessionId: String(event.session_id),
+    text: String(event.last_assistant_message),
+    timestamp: new Date().toISOString(),
+  };
+}
+
+export function resumeClaudeSession({ sessionId, projectDir, text, timeoutMs = Number(process.env.CC_EXEC_TIMEOUT_MS || 1800000) }) {
+  if (!sessionId) throw new Error('sessionId is required');
+  if (!projectDir) throw new Error('projectDir is required');
+  if (!text) throw new Error('text is required');
+
+  const child = spawn(
+    'claude',
+    ['-p', text, '--resume', sessionId, '--dangerously-skip-permissions', '--output-format', 'json'],
+    { cwd: projectDir, stdio: ['ignore', 'pipe', 'ignore'] }
+  );
+
+  if (timeoutMs > 0) {
+    const timeout = setTimeout(() => child.kill('SIGTERM'), timeoutMs);
+    timeout.unref();
+    child.on('exit', () => clearTimeout(timeout));
+    child.on('error', () => clearTimeout(timeout));
+  }
+
+  child.unref();
+  return { sessionId, projectDir };
+}
+
+export function createClaudeSession({ projectDir, text, timeoutMs = Number(process.env.CC_EXEC_TIMEOUT_MS || 1800000) }) {
+  if (!projectDir) throw new Error('projectDir is required');
+  if (!text) throw new Error('text is required');
+
+  const output = execSync(
+    `claude -p ${JSON.stringify(text)} --dangerously-skip-permissions --output-format json`,
+    { cwd: projectDir, timeout: timeoutMs, encoding: 'utf8' }
+  );
+  const lines = String(output || '').trim().split('\n').filter(Boolean);
+  const payload = JSON.parse(lines[lines.length - 1] || '{}');
+  if (!payload.session_id) {
+    throw new Error('claude session_id missing from output');
+  }
+  return {
+    sessionId: String(payload.session_id),
+    projectDir,
+  };
+}

package/src/runtimes/codex.mjs

@@ -0,0 +1,129 @@
+import { spawn } from 'node:child_process';
+
+export function normalizeCodexHookEvent(event, registration) {
+  if (!event?.session_id || !registration?.appThreadId) return null;
+
+  if (event.hook_event_name === 'Stop' && event.last_assistant_message) {
+    return {
+      runtime: 'codex',
+      kind: 'assistant',
+      appThreadId: registration.appThreadId,
+      runtimeSessionId: String(event.session_id),
+      text: String(event.last_assistant_message),
+      timestamp: new Date().toISOString(),
+    };
+  }
+
+  if (event.hook_event_name === 'UserPromptSubmit' && typeof event.prompt === 'string' && event.prompt.trim()) {
+    return {
+      runtime: 'codex',
+      kind: 'user',
+      appThreadId: registration.appThreadId,
+      runtimeSessionId: String(event.session_id),
+      text: event.prompt.trim(),
+      timestamp: new Date().toISOString(),
+    };
+  }
+
+  return null;
+}
+
+export function resumeCodexSession({ sessionId, cwd, text, timeoutMs = Number(process.env.CODEX_EXEC_TIMEOUT_MS || 1800000) }) {
+  if (!sessionId) throw new Error('sessionId is required');
+  if (!cwd) throw new Error('cwd is required');
+  if (!text) throw new Error('text is required');
+
+  const child = spawn(
+    'codex',
+    [
+      'exec',
+      'resume',
+      sessionId,
+      '--json',
+      '--skip-git-repo-check',
+      '--dangerously-bypass-approvals-and-sandbox',
+      text,
+    ],
+    { cwd, stdio: 'ignore' }
+  );
+
+  if (timeoutMs > 0) {
+    const timeout = setTimeout(() => child.kill('SIGTERM'), timeoutMs);
+    timeout.unref();
+    child.on('exit', () => clearTimeout(timeout));
+    child.on('error', () => clearTimeout(timeout));
+  }
+
+  child.unref();
+  return { sessionId, cwd };
+}
+
+export function createCodexSession({ cwd, text, timeoutMs = Number(process.env.CODEX_EXEC_TIMEOUT_MS || 1800000) }) {
+  if (!cwd) throw new Error('cwd is required');
+  if (!text) throw new Error('text is required');
+
+  return new Promise((resolve, reject) => {
+    const child = spawn(
+      'codex',
+      [
+        'exec',
+        '--json',
+        '--skip-git-repo-check',
+        '--dangerously-bypass-approvals-and-sandbox',
+        text,
+      ],
+      {
+        cwd,
+        stdio: ['ignore', 'pipe', 'ignore'],
+      }
+    );
+
+    let settled = false;
+    let buffer = '';
+    let timeout = null;
+
+    const settle = (fn, value) => {
+      if (settled) return;
+      settled = true;
+      if (timeout) clearTimeout(timeout);
+      fn(value);
+    };
+
+    if (timeoutMs > 0) {
+      timeout = setTimeout(() => {
+        child.kill('SIGTERM');
+        settle(reject, new Error('codex session creation timed out'));
+      }, timeoutMs);
+      timeout.unref();
+    }
+
+    child.stdout.on('data', (chunk) => {
+      buffer += chunk.toString('utf8');
+      const lines = buffer.split('\n');
+      buffer = lines.pop() || '';
+      for (const line of lines) {
+        if (!line.trim()) continue;
+        let payload;
+        try {
+          payload = JSON.parse(line);
+        } catch {
+          continue;
+        }
+        if (payload.type === 'thread.started' && payload.thread_id) {
+          settle(resolve, {
+            sessionId: String(payload.thread_id),
+            cwd,
+          });
+          return;
+        }
+      }
+    });
+
+    child.on('error', (err) => settle(reject, err));
+    child.on('exit', (code, signal) => {
+      if (settled) return;
+      if (signal) settle(reject, new Error(`codex session exited via ${signal}`));
+      else if (code !== 0) settle(reject, new Error(`codex session exited with code ${code}`));
+    });
+  });
+}

package/src/store/file-store.mjs

@@ -0,0 +1,63 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export const AGENT_FREEWAY_HOME = join(homedir(), '.agent-freeway');
+export const REGISTRATIONS_PATH = join(AGENT_FREEWAY_HOME, 'registrations.json');
+
+function ensureStateDir() {
+  mkdirSync(AGENT_FREEWAY_HOME, { recursive: true });
+}
+
+function normalizeState(raw) {
+  if (Array.isArray(raw)) return { registrations: raw };
+  if (raw && Array.isArray(raw.registrations)) return { registrations: raw.registrations };
+  return { registrations: [] };
+}
+
+export function loadState() {
+  if (!existsSync(REGISTRATIONS_PATH)) return { registrations: [] };
+  try {
+    return normalizeState(JSON.parse(readFileSync(REGISTRATIONS_PATH, 'utf8')));
+  } catch {
+    return { registrations: [] };
+  }
+}
+
+export function saveState(state) {
+  ensureStateDir();
+  writeFileSync(REGISTRATIONS_PATH, `${JSON.stringify(normalizeState(state), null, 2)}\n`, 'utf8');
+}
+
+export function listRegistrations() {
+  return loadState().registrations;
+}
+
+export function upsertRegistration(registration) {
+  const state = loadState();
+  const next = {
+    runtime: registration.runtime,
+    appThreadId: registration.appThreadId,
+    sessionId: registration.sessionId,
+    cwd: registration.cwd || null,
+    projectDir: registration.projectDir || null,
+    updatedAt: new Date().toISOString(),
+  };
+  state.registrations = state.registrations.filter((item) => {
+    if (item.runtime !== next.runtime) return true;
+    if (item.appThreadId === next.appThreadId) return false;
+    if (item.sessionId === next.sessionId) return false;
+    return true;
+  });
+  state.registrations.push(next);
+  saveState(state);
+  return next;
+}
+
+export function resolveByAppThreadId(runtime, appThreadId) {
+  return listRegistrations().find((item) => item.runtime === runtime && item.appThreadId === appThreadId) || null;
+}
+
+export function resolveBySessionId(runtime, sessionId) {
+  return listRegistrations().find((item) => item.runtime === runtime && item.sessionId === sessionId) || null;
+}