agent-tool-forge 0.3.0

package/lib/hitl-engine.js

@@ -0,0 +1,261 @@
+/**
+ * HITL Engine — pause/resume for confirmable tool calls.
+ *
+ * Sensitivity levels:
+ *   autonomous — never pause
+ *   cautious   — pause if tool spec has requiresConfirmation flag
+ *   standard   — pause for POST/PUT/PATCH/DELETE methods
+ *   paranoid   — always pause
+ *
+ * Storage backends:
+ *   memory  — in-process Map (default, single-instance only)
+ *   sqlite  — hitl_pending table (single-instance, survives restart)
+ *   redis   — forge:hitl:{token} keys with TTL (multi-instance, recommended for production)
+ *
+ * Paused state has a TTL — expired states cannot be resumed.
+ */
+
+import { randomUUID } from 'crypto';
+
+const DEFAULT_TTL_MS = 5 * 60 * 1000; // 5 minutes
+const REDIS_KEY_PREFIX = 'forge:hitl:';
+
+export class HitlEngine {
+  /**
+   * @param {object} opts
+   * @param {import('better-sqlite3').Database} [opts.db] — SQLite backend
+   * @param {object} [opts.redis] — Redis client instance (ioredis or node-redis compatible)
+   * @param {import('pg').Pool} [opts.pgPool] — Postgres pool instance
+   * @param {number} [opts.ttlMs] — pause state TTL (default 5 min)
+   */
+  constructor(opts = {}) {
+    this._db = opts.db ?? null;
+    this._redis = opts.redis ?? null;
+    this._pgPool = opts.pgPool ?? null;
+    this._ttlMs = opts.ttlMs ?? DEFAULT_TTL_MS;
+
+    // In-memory store as fallback when no DB, no Redis, and no Postgres
+    this._memStore = new Map();
+
+    // Periodic cleanup of expired in-memory entries (every 60s)
+    if (!this._db && !this._redis && !this._pgPool) {
+      this._cleanupTimer = setInterval(() => {
+        const now = Date.now();
+        for (const [key, entry] of this._memStore) {
+          if (now > entry.expiresAt) this._memStore.delete(key);
+        }
+      }, 60_000);
+      this._cleanupTimer.unref();
+    }
+
+    // Ensure hitl_pending table exists if using SQLite (and not Redis/Postgres)
+    if (this._db && !this._redis && !this._pgPool) {
+      this._db.exec(`
+        CREATE TABLE IF NOT EXISTS hitl_pending (
+          resume_token TEXT PRIMARY KEY,
+          state_json TEXT NOT NULL,
+          expires_at TEXT NOT NULL,
+          created_at TEXT NOT NULL
+        )
+      `);
+
+      // SQLite path — cleanup expired rows every 5 minutes.
+      // DESIGN NOTE: 5-minute interval chosen deliberately. A shorter interval (e.g. 60s)
+      // risks write contention under high HITL volume; a longer one (e.g. 30min) lets
+      // stale rows accumulate more. 5min is a conservative middle ground.
+      // If you see write contention on hitl_pending at scale, reduce to 60s.
+      const db = this._db;
+      this._sqliteCleanupTimer = setInterval(() => {
+        try {
+          db.prepare('DELETE FROM hitl_pending WHERE expires_at < ?')
+            .run(new Date().toISOString());
+        } catch { /* cleanup failure is non-fatal */ }
+      }, 5 * 60_000);
+      this._sqliteCleanupTimer.unref();
+    }
+
+    // Postgres table creation is deferred to first use (_ensurePgTable)
+    this._pgTableReady = false;
+  }
+
+  /** @private */
+  async _ensurePgTable() {
+    if (this._pgTableReady) return;
+    await this._pgPool.query(`
+      CREATE TABLE IF NOT EXISTS hitl_pending (
+        resume_token TEXT PRIMARY KEY,
+        state_json TEXT NOT NULL,
+        expires_at TEXT NOT NULL,
+        created_at TEXT NOT NULL
+      )
+    `);
+    this._pgTableReady = true;
+  }
+
+  /**
+   * Determine whether a tool call should pause for confirmation.
+   *
+   * @param {string} hitlLevel — user's HITL sensitivity level
+   * @param {object} toolSpec — { name, method?, requiresConfirmation? }
+   * @returns {boolean}
+   */
+  shouldPause(hitlLevel, toolSpec = {}) {
+    switch (hitlLevel) {
+      case 'autonomous':
+        return false;
+      case 'cautious':
+        return !!toolSpec.requiresConfirmation;
+      case 'standard': {
+        const method = (toolSpec.method || 'GET').toUpperCase();
+        return ['POST', 'PUT', 'PATCH', 'DELETE'].includes(method);
+      }
+      case 'paranoid':
+        return true;
+      default:
+        return false;
+    }
+  }
+
+  /**
+   * Store paused state and return a resume token.
+   *
+   * @param {object} state — arbitrary state to store (conversation, pending tool calls, etc.)
+   * @returns {Promise<string>} resumeToken
+   */
+  async pause(state) {
+    const resumeToken = randomUUID();
+    const stateJson = JSON.stringify(state);
+
+    if (this._redis) {
+      const ttlSeconds = Math.ceil(this._ttlMs / 1000);
+      await this._redis.set(
+        REDIS_KEY_PREFIX + resumeToken,
+        stateJson,
+        'EX',
+        ttlSeconds
+      );
+      return resumeToken;
+    }
+
+    if (this._pgPool) {
+      await this._ensurePgTable();
+      const expiresAt = new Date(Date.now() + this._ttlMs).toISOString();
+      await this._pgPool.query(
+        `INSERT INTO hitl_pending (resume_token, state_json, expires_at, created_at)
+         VALUES ($1, $2, $3, $4)`,
+        [resumeToken, stateJson, expiresAt, new Date().toISOString()]
+      );
+      return resumeToken;
+    }
+
+    if (this._db) {
+      const expiresAt = new Date(Date.now() + this._ttlMs).toISOString();
+      this._db.prepare(`
+        INSERT INTO hitl_pending (resume_token, state_json, expires_at, created_at)
+        VALUES (?, ?, ?, ?)
+      `).run(resumeToken, stateJson, expiresAt, new Date().toISOString());
+      return resumeToken;
+    }
+
+    // In-memory fallback
+    this._memStore.set(resumeToken, { state, expiresAt: Date.now() + this._ttlMs });
+    return resumeToken;
+  }
+
+  /**
+   * Resume a paused state. Returns the state if valid, null if expired or not found.
+   * Deletes the state on successful resume (one-time use).
+   *
+   * @param {string} resumeToken
+   * @returns {Promise<object|null>}
+   */
+  async resume(resumeToken) {
+    if (this._redis) {
+      const key = REDIS_KEY_PREFIX + resumeToken;
+      // Atomic get-and-delete: use a pipeline or multi/exec
+      // For simplicity, GET then DEL — race window is acceptable for HITL
+      const stateJson = await this._redis.get(key);
+      if (!stateJson) return null;
+      await this._redis.del(key);
+      try {
+        return JSON.parse(stateJson);
+      } catch {
+        return null;
+      }
+    }
+
+    if (this._pgPool) {
+      await this._ensurePgTable();
+      const { rows } = await this._pgPool.query(
+        'SELECT * FROM hitl_pending WHERE resume_token = $1',
+        [resumeToken]
+      );
+      if (rows.length === 0) return null;
+
+      const row = rows[0];
+      // Delete regardless (one-time use)
+      await this._pgPool.query(
+        'DELETE FROM hitl_pending WHERE resume_token = $1',
+        [resumeToken]
+      );
+
+      // Check expiry
+      if (new Date(row.expires_at) < new Date()) return null;
+
+      try {
+        return JSON.parse(row.state_json);
+      } catch {
+        return null;
+      }
+    }
+
+    if (this._db) {
+      const row = this._db.prepare(
+        'SELECT * FROM hitl_pending WHERE resume_token = ?'
+      ).get(resumeToken);
+
+      if (!row) return null;
+
+      // Delete regardless (one-time use)
+      this._db.prepare('DELETE FROM hitl_pending WHERE resume_token = ?').run(resumeToken);
+
+      // Check expiry
+      if (new Date(row.expires_at) < new Date()) return null;
+
+      try {
+        return JSON.parse(row.state_json);
+      } catch {
+        return null;
+      }
+    }
+
+    // In-memory fallback
+    const entry = this._memStore.get(resumeToken);
+    if (!entry) return null;
+    this._memStore.delete(resumeToken);
+    if (Date.now() > entry.expiresAt) return null;
+    return entry.state;
+  }
+}
+
+/**
+ * Factory — selects storage backend from config.
+ * Priority: Redis → Postgres → SQLite → in-memory.
+ *
+ * @param {object} config — forge config
+ * @param {import('better-sqlite3').Database} [db]
+ * @param {object} [redis] — pre-created Redis client instance
+ * @param {import('pg').Pool} [pgPool] — pre-created Postgres pool instance
+ * @returns {HitlEngine}
+ */
+export function makeHitlEngine(config, db, redis, pgPool) {
+  const ttlMs = config?.hitl?.ttlMs ?? config?.ttlMs ?? undefined;
+  const ttlOpt = ttlMs !== undefined ? { ttlMs } : {};
+  if (redis) {
+    return new HitlEngine({ redis, ...ttlOpt });
+  }
+  if (pgPool) {
+    return new HitlEngine({ pgPool, ...ttlOpt });
+  }
+  return new HitlEngine({ db, ...ttlOpt });
+}

package/lib/http-utils.js

@@ -0,0 +1,92 @@
+/**
+ * Shared HTTP helpers for sidecar request handlers.
+ */
+
+import { getAllToolRegistry } from './db.js';
+
+const MAX_BODY_SIZE = 1_048_576; // 1 MB
+
+/**
+ * Read and JSON-parse a request body. Returns {} on parse failure.
+ * Rejects bodies larger than MAX_BODY_SIZE.
+ * @param {import('http').IncomingMessage} req
+ * @returns {Promise<object>}
+ */
+export function readBody(req) {
+  return new Promise((resolve, reject) => {
+    let data = '';
+    let size = 0;
+    req.on('data', (chunk) => {
+      size += chunk.length;
+      if (size > MAX_BODY_SIZE) {
+        req.destroy();
+        reject(new Error('Request body too large'));
+        return;
+      }
+      data += chunk;
+    });
+    req.on('end', () => {
+      try { resolve(data ? JSON.parse(data) : {}); } catch { resolve({}); }
+    });
+    req.on('error', () => resolve({}));
+  });
+}
+
+/**
+ * Send a JSON response with the given status code.
+ * @param {import('http').ServerResponse} res
+ * @param {number} statusCode
+ * @param {object} body
+ */
+export function sendJson(res, statusCode, body) {
+  const payload = JSON.stringify(body);
+  res.writeHead(statusCode, { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) });
+  res.end(payload);
+}
+
+/**
+ * Extract a JWT from an HTTP request.
+ * Checks Authorization: Bearer <token> first, then falls back to ?token= query param.
+ * @param {import('http').IncomingMessage} req
+ * @returns {string|null}
+ */
+export function extractJwt(req) {
+  const auth = req.headers.authorization ?? '';
+  if (auth.startsWith('Bearer ')) return auth.slice(7) || null;
+  try {
+    return new URL(req.url, 'http://localhost').searchParams.get('token') || null;
+  } catch { return null; }
+}
+
+/**
+ * Load promoted tools from the tool registry and convert to LLM-format tool defs.
+ * @param {import('better-sqlite3').Database} db
+ * @param {string|string[]} [allowlist='*'] — '*' for all, or array of tool_names to include
+ * @returns {{ toolRows: object[], tools: object[] }}
+ */
+export function loadPromotedTools(db, allowlist = '*') {
+  let toolRows = getAllToolRegistry(db).filter(r => r.lifecycle_state === 'promoted');
+  if (Array.isArray(allowlist)) {
+    const allowSet = new Set(allowlist);
+    toolRows = toolRows.filter(r => allowSet.has(r.tool_name));
+  }
+  const tools = [];
+  for (const row of toolRows) {
+    try {
+      const spec = JSON.parse(row.spec_json);
+      const schema = spec.schema || {};
+      const properties = {};
+      const required = [];
+      for (const [k, v] of Object.entries(schema)) {
+        properties[k] = { type: v.type || 'string', description: v.description || k };
+        if (!v.optional) required.push(k);
+      }
+      tools.push({
+        name: spec.name || row.tool_name,
+        description: spec.description || '',
+        inputSchema: { type: 'object', properties, required }
+      });
+    } catch { /* skip malformed specs */ }
+  }
+  return { toolRows, tools };
+}

package/lib/index.d.ts

@@ -0,0 +1,20 @@
+// Barrel re-export of all public types for `import type { ... } from 'agent-tool-forge'`
+export * from './sidecar.js';
+export type { AuthResult, AuthConfig, Authenticator, AdminAuthResult } from './auth.js';
+export type { ConversationMessage, SessionSummary, ConversationStore } from './conversation-store.js';
+export type {
+  ReactEvent, ReactLoopParams, ReactEventType,
+  TextEvent, TextDeltaEvent, ToolCallEvent, ToolResultEvent,
+  ToolWarningEvent, HitlEvent, ErrorEvent, DoneEvent
+} from './react-engine.js';
+export type {
+  SidecarConfig, AgentConfig, RateLimitConfig, VerificationConfig,
+  ConversationConfig, DatabaseConfig, AuthConfig as SidecarAuthConfig
+} from './config-schema.js';
+export type { HitlEngine, HitlEngineOptions, HitlLevel, HitlToolSpec } from './hitl-engine.js';
+export type { PromptStore, PromptVersion } from './prompt-store.js';
+export type { PreferenceStore, UserPreferences, EffectiveSettings } from './preference-store.js';
+export type { RateLimiter, RateLimitResult } from './rate-limiter.js';
+export type { PostgresStore } from './postgres-store.js';
+export type { Db } from './db.js';
+export type { SSEHandle } from './sse.js';

package/lib/index.js

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+/**
+ * Forge CLI — Entry point.
+ *
+ * Usage:
+ *   node lib/index.js           # Full-screen TUI
+ *   node lib/index.js --manual  # Skip to manual endpoint entry (fallback)
+ */
+
+import { readFileSync, existsSync, writeFileSync } from 'fs';
+import { resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { runTui } from './tui.js';
+import { addEndpointManually } from './manual-entry.js';
+import * as readline from 'readline';
+
+const CONFIG_FILE = 'forge.config.json';
+const PENDING_SPEC_FILE = 'forge-pending-tool.json';
+
+function findProjectRoot() {
+  return resolve(dirname(fileURLToPath(import.meta.url)), '..');
+}
+
+function loadConfig() {
+  const projectRoot = findProjectRoot();
+  const configPath = resolve(projectRoot, CONFIG_FILE);
+  if (!existsSync(configPath)) {
+    console.error(`No ${CONFIG_FILE} found in ${projectRoot}.\nRun "forge init" to set up your project, or create one from config/forge.config.template.json`);
+    process.exit(1);
+  }
+  const raw = readFileSync(configPath, 'utf-8');
+  try {
+    return JSON.parse(raw);
+  } catch (err) {
+    console.error(`${CONFIG_FILE} contains invalid JSON: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+/**
+ * Returns true if the user needs to go through onboarding:
+ * - No API key in .env AND no API key in environment variables AND no key in config
+ */
+function needsOnboarding(config) {
+  const projectRoot = findProjectRoot();
+  const envPath = resolve(projectRoot, '.env');
+
+  // Check process env first
+  if (process.env.ANTHROPIC_API_KEY || process.env.OPENAI_API_KEY ||
+      process.env.GOOGLE_API_KEY || process.env.GEMINI_API_KEY) return false;
+
+  // Check .env file
+  if (existsSync(envPath)) {
+    try {
+      const envText = readFileSync(envPath, 'utf-8');
+      if (/ANTHROPIC_API_KEY\s*=\s*\S/.test(envText)) return false;
+      if (/OPENAI_API_KEY\s*=\s*\S/.test(envText)) return false;
+      if (/GOOGLE_API_KEY\s*=\s*\S/.test(envText)) return false;
+      if (/GEMINI_API_KEY\s*=\s*\S/.test(envText)) return false;
+    } catch (_) { /* ignore */ }
+  }
+
+  // Check config object for configured credentials
+  if (config?.auth?.signingKey && typeof config.auth.signingKey === 'string' &&
+      config.auth.signingKey.trim() && !config.auth.signingKey.startsWith('${')) {
+    return false;
+  }
+  if (config?.adminKey && typeof config.adminKey === 'string' &&
+      config.adminKey.trim() && !config.adminKey.startsWith('${')) {
+    return false;
+  }
+
+  return true; // No key found anywhere
+}
+
+async function main() {
+  process.chdir(findProjectRoot());
+
+  const args = process.argv.slice(2);
+
+  if (args[0] === 'run') {
+    const { runCli } = await import('./runner/cli.js');
+    await runCli(args.slice(1));
+    return;
+  }
+
+  if (args[0] === 'init') {
+    const { runInit } = await import('./init.js');
+    await runInit();
+    return;
+  }
+
+  const manualOnly = args.includes('--manual') || args.includes('-m');
+
+  if (manualOnly) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    let endpoint;
+    try {
+      endpoint = await addEndpointManually(rl);
+    } finally {
+      rl.close();
+    }
+
+    const projectRoot = findProjectRoot();
+    let config;
+    if (existsSync(resolve(projectRoot, CONFIG_FILE))) {
+      try {
+        config = JSON.parse(readFileSync(resolve(projectRoot, CONFIG_FILE), 'utf-8'));
+      } catch (err) {
+        console.error('Error reading forge.config.json:', err.message);
+        config = {};
+      }
+    } else {
+      config = { project: {} };
+    }
+
+    const pendingSpec = {
+      _source: 'forge-api-tui',
+      _createdAt: new Date().toISOString(),
+      endpoint,
+      project: config.project || {}
+    };
+    writeFileSync(resolve(projectRoot, PENDING_SPEC_FILE), JSON.stringify(pendingSpec, null, 2), 'utf-8');
+    console.log(`\nWrote ${PENDING_SPEC_FILE}. Run /forge-tool in Claude.\n`);
+    return;
+  }
+
+  const config = loadConfig();
+
+  // Check if onboarding is needed, and if so, pass the flag to the TUI
+  if (needsOnboarding(config)) {
+    config._startOnOnboarding = true;
+  }
+
+  await runTui(config);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});