agent-tool-forge 0.3.0

package/lib/forge-file-writer.js

@@ -0,0 +1,386 @@
+/**
+ * Forge File Writer — generates tool file content via LLM.
+ * Does NOT write to disk — returns content strings for forge.js to preview and confirm.
+ *
+ * @module forge-file-writer
+ */
+
+import { llmTurn } from './api-client.js';
+
+// ── JSON extraction ────────────────────────────────────────────────────────
+
+/**
+ * Extract a JSON object from raw LLM response text.
+ * Tries ```json...``` fenced block first, then falls back to first `{` to
+ * its matching closing `}`.
+ *
+ * @param {string} text - Raw LLM response text
+ * @returns {object} Parsed JSON object
+ * @throws {Error} If no valid JSON object can be found or parsed
+ */
+function extractJson(text) {
+  // Strategy 1: ```json ... ``` fenced block
+  const fenceMatch = text.match(/```json\s*([\s\S]*?)\s*```/);
+  if (fenceMatch) {
+    try {
+      return JSON.parse(fenceMatch[1]);
+    } catch (_) {
+      // Fenced block was malformed JSON — fall through to strategy 2
+    }
+  }
+
+  // Strategy 2: first `{` to its matching `}`
+  const start = text.indexOf('{');
+  if (start === -1) {
+    throw new Error('No JSON object found in LLM response');
+  }
+
+  let depth = 0;
+  let inString = false;
+  let escape = false;
+
+  for (let i = start; i < text.length; i++) {
+    const ch = text[i];
+
+    if (escape) {
+      escape = false;
+      continue;
+    }
+    if (ch === '\\' && inString) {
+      escape = true;
+      continue;
+    }
+    if (ch === '"') {
+      inString = !inString;
+      continue;
+    }
+    if (inString) continue;
+
+    if (ch === '{') depth++;
+    else if (ch === '}') {
+      depth--;
+      if (depth === 0) {
+        return JSON.parse(text.slice(start, i + 1));
+      }
+    }
+  }
+
+  throw new Error('Unbalanced JSON object in LLM response');
+}
+
+/**
+ * Validate that the parsed LLM output has the required shape.
+ *
+ * @param {unknown} obj
+ * @returns {{ toolFile: string, testFile: string, barrelLine: string|undefined }}
+ * @throws {Error} If required fields are missing or wrong type
+ */
+function validateLlmOutput(obj) {
+  if (!obj || typeof obj !== 'object') {
+    throw new Error('LLM response did not parse to an object');
+  }
+  if (typeof obj.toolFile !== 'string' || obj.toolFile.trim() === '') {
+    throw new Error('LLM response missing required string field: toolFile');
+  }
+  if (!/mcpRouting/i.test(obj.toolFile)) {
+    throw new Error('toolFile must contain an mcpRouting declaration');
+  }
+  if (typeof obj.testFile !== 'string' || obj.testFile.trim() === '') {
+    throw new Error('LLM response missing required string field: testFile');
+  }
+  return {
+    toolFile: obj.toolFile,
+    testFile: obj.testFile,
+    barrelLine: typeof obj.barrelLine === 'string' ? obj.barrelLine : undefined
+  };
+}
+
+// ── Prompt builder ─────────────────────────────────────────────────────────
+
+/**
+ * Build the system prompt for the LLM code-generation request.
+ *
+ * @param {object} spec - Tool specification
+ * @param {string[]} existingTools - Names of already-registered tools
+ * @returns {string}
+ */
+function buildSystemPrompt(spec, existingTools) {
+  const safeName       = (spec.name || 'unnamed').replace(/[^a-zA-Z0-9_-]/g, '_');
+  const tagsStr        = spec.tags?.join(', ')          || '';
+  const dependsOnStr   = spec.dependsOn?.join(', ')     || '';
+  const triggersStr    = spec.triggerPhrases?.join(', ') || '';
+  const schemaStr      = JSON.stringify(spec.schema ?? {}, null, 2);
+  const existingStr    = existingTools.length
+    ? existingTools.join(', ')
+    : '(none)';
+  const paramMapStr    = JSON.stringify(spec.paramMap || {});
+
+  return `You are generating a JavaScript tool file for an Agent Tool Forge project. \
+This tool generates the MCP routing layer — a tool definition that points to an internal API \
+endpoint or external data source. Business logic lives behind that endpoint.
+
+Tool spec:
+- Name: ${spec.name}
+- Description: ${spec.description}
+- Category: ${spec.category}
+- Consequence level: ${spec.consequenceLevel}
+- Requires confirmation: ${spec.requiresConfirmation}
+- Timeout: ${spec.timeout || 30000}
+- Schema: ${schemaStr}
+- Tags: ${tagsStr}
+- Depends on: ${dependsOnStr}
+- Trigger phrases: ${triggersStr}
+- Endpoint target: ${spec.endpointTarget || 'https://your-api.example.com/...'}
+- HTTP method: ${spec.httpMethod || 'GET'}
+- Auth type: ${spec.authType || 'bearer'}
+- Param map: ${paramMapStr}
+
+Existing registered tools (for barrel import reference): ${existingStr}
+
+--- TOOL FILE FORMAT ---
+The file must be a JavaScript ESM module (.js) exporting a named const.
+Follow this exact shape (adapt field values from the spec above):
+
+/**
+ * ${spec.name} — <one-line description>
+ */
+
+export const ${_camelName(spec.name)}Tool = {
+  name: '${spec.name}',
+  description: '<full description>',
+  schema: <schema as JS object literal — not JSON>,
+  category: '${spec.category}',
+  consequenceLevel: '${spec.consequenceLevel}',
+  requiresConfirmation: ${spec.requiresConfirmation},
+  timeout: ${spec.timeout || 30000},
+  version: '1.0.0',
+  status: 'active',
+  tags: ${JSON.stringify(spec.tags ?? [])},
+  dependsOn: ${JSON.stringify(spec.dependsOn ?? [])},
+  triggerPhrases: ${JSON.stringify(spec.triggerPhrases ?? [])},
+
+  mcpRouting: {
+    // EXTENSION POINT: configure your endpoint here
+    endpoint: '${spec.endpointTarget || 'https://your-api.example.com/...'}',
+    method: '${spec.httpMethod || 'GET'}',
+    auth: '${spec.authType || 'bearer'}',
+    paramMap: ${paramMapStr}
+  }
+};
+
+--- TEST FILE FORMAT ---
+The test file must be a JavaScript ESM module using describe/it/expect (Jest or Vitest style).
+It tests the exported tool object — NOT any execute() implementation.
+
+import { ${_camelName(spec.name)}Tool } from '../${safeName}.tool.js';
+
+describe('${spec.name}', () => {
+  it('has required fields', () => {
+    expect(${_camelName(spec.name)}Tool.name).toBe('${spec.name}');
+    expect(typeof ${_camelName(spec.name)}Tool.description).toBe('string');
+    expect(${_camelName(spec.name)}Tool.mcpRouting).toBeDefined();
+  });
+  it('schema matches spec', () => {
+    // assert each expected schema key is present
+  });
+  it('mcpRouting has required shape', () => {
+    expect(typeof ${_camelName(spec.name)}Tool.mcpRouting.endpoint).toBe('string');
+    expect(typeof ${_camelName(spec.name)}Tool.mcpRouting.method).toBe('string');
+  });
+});
+
+--- BARREL LINE FORMAT ---
+The barrelLine must be a single ESM named re-export, e.g.:
+export { ${_camelName(spec.name)}Tool } from './${safeName}.tool.js';
+
+--- RESPONSE FORMAT ---
+Respond ONLY with a JSON object — no prose, no markdown outside the JSON itself.
+Required keys:
+  "toolFile"   — full file content as a string (the complete .tool.js file)
+  "testFile"   — full test file content as a string (the complete .tool.test.js file)
+  "barrelLine" — single export line to add to the barrel index (string)
+
+Example response shape:
+{
+  "toolFile": "/** ... */\\nexport const myTool = { ... };",
+  "testFile": "import { myTool } from '../my_tool.tool.js';\\ndescribe(...)",
+  "barrelLine": "export { myTool } from './my_tool.tool.js';"
+}`;
+}
+
+// ── Camel-case helper ──────────────────────────────────────────────────────
+
+/**
+ * Convert a snake_case tool name to camelCase for the exported const.
+ * e.g. "get_weather" → "getWeather"
+ *
+ * @param {string} name
+ * @returns {string}
+ */
+function _camelName(name) {
+  return name.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
+}
+
+// ── Main export ────────────────────────────────────────────────────────────
+
+/**
+ * Generate tool file content via LLM.
+ *
+ * Does NOT write to disk. Returns content strings and computed paths so the
+ * caller (forge.js) can preview and confirm before writing.
+ *
+ * @param {object}   opts
+ * @param {object}   opts.spec              - Tool specification
+ * @param {string}   opts.spec.name         - Snake_case tool name
+ * @param {string}   opts.spec.description  - Human-readable description
+ * @param {object}   [opts.spec.schema]     - Parameter schema
+ * @param {string}   [opts.spec.category]   - 'read' | 'write' | 'delete' | 'action'
+ * @param {string}   [opts.spec.consequenceLevel] - 'low' | 'medium' | 'high'
+ * @param {boolean}  [opts.spec.requiresConfirmation]
+ * @param {number}   [opts.spec.timeout]
+ * @param {string[]} [opts.spec.tags]
+ * @param {string[]} [opts.spec.dependsOn]
+ * @param {string[]} [opts.spec.triggerPhrases]
+ * @param {object}   opts.projectConfig     - forge.config.json contents
+ * @param {string}   opts.projectRoot       - Absolute path to project root
+ * @param {object}   opts.modelConfig       - { provider, apiKey, model }
+ * @param {string}   opts.modelConfig.provider  - 'anthropic' | 'openai'
+ * @param {string}   opts.modelConfig.apiKey
+ * @param {string}   opts.modelConfig.model
+ * @param {string[]} [opts.existingTools]   - Existing tool names for barrel example
+ *
+ * @returns {Promise<{
+ *   toolFile: { path: string, content: string },
+ *   testFile: { path: string, content: string },
+ *   barrelDiff: { path: string, lineToAdd: string } | null
+ * }>}
+ *
+ * @throws {Error} If LLM returns invalid JSON after 2 retries
+ */
+export async function generateToolFiles({
+  spec,
+  projectConfig,
+  projectRoot,
+  modelConfig,
+  existingTools = []
+}) {
+  const toolsDir = projectConfig?.project?.toolsDir || 'example/tools';
+
+  // Resolve absolute base directory for path construction
+  const absToolsDir = toolsDir.startsWith('/')
+    ? toolsDir
+    : `${projectRoot}/${toolsDir}`;
+
+  const safeName      = (spec.name || 'unnamed').replace(/[^a-zA-Z0-9_-]/g, '_');
+  const toolFilePath  = `${absToolsDir}/${safeName}.tool.js`;
+  const testFilePath  = `${absToolsDir}/__tests__/${safeName}.tool.test.js`;
+  const barrelPath    = `${absToolsDir}/index.js`;
+
+  const systemPrompt = buildSystemPrompt(spec, existingTools);
+  const userMessage  = `Generate the tool file, test file, and barrel line for the "${spec.name}" tool.`;
+
+  const messages = [{ role: 'user', content: userMessage }];
+
+  const MAX_RETRIES = 2;
+  let lastError;
+
+  for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+    let responseText;
+
+    try {
+      const turn = await llmTurn({
+        provider:  modelConfig.provider,
+        apiKey:    modelConfig.apiKey,
+        model:     modelConfig.model,
+        system:    systemPrompt,
+        messages,
+        maxTokens: 8192,
+        timeoutMs: 120_000
+      });
+
+      responseText = turn.text;
+    } catch (err) {
+      // Network / API errors propagate immediately — no retry benefit
+      throw new Error(
+        `LLM API call failed while generating tool "${spec.name}": ${err.message}`
+      );
+    }
+
+    if (!responseText || responseText.trim() === '') {
+      lastError = new Error(
+        `LLM returned an empty response on attempt ${attempt}/${MAX_RETRIES}`
+      );
+      // Append a nudge for the retry
+      messages.push({ role: 'assistant', content: responseText || '' });
+      messages.push({
+        role: 'user',
+        content:
+          'Your response was empty. Please respond with ONLY a JSON object containing ' +
+          '"toolFile", "testFile", and "barrelLine" keys.'
+      });
+      continue;
+    }
+
+    let parsed;
+    try {
+      parsed = extractJson(responseText);
+    } catch (parseErr) {
+      lastError = new Error(
+        `Attempt ${attempt}/${MAX_RETRIES}: Could not extract JSON from LLM response — ` +
+        parseErr.message +
+        `\nRaw response (first 300 chars): ${responseText.slice(0, 300)}`
+      );
+      messages.push({ role: 'assistant', content: responseText });
+      messages.push({
+        role: 'user',
+        content:
+          'Your previous response did not contain a valid JSON object. ' +
+          'Respond ONLY with a JSON object with keys "toolFile", "testFile", and "barrelLine". ' +
+          'Do not include any text outside the JSON.'
+      });
+      continue;
+    }
+
+    let validated;
+    try {
+      validated = validateLlmOutput(parsed);
+    } catch (validErr) {
+      lastError = new Error(
+        `Attempt ${attempt}/${MAX_RETRIES}: LLM JSON was missing required fields — ` +
+        validErr.message
+      );
+      messages.push({ role: 'assistant', content: responseText });
+      messages.push({
+        role: 'user',
+        content:
+          `The JSON you returned was invalid: ${validErr.message}. ` +
+          'Please provide a JSON object with non-empty string fields "toolFile", "testFile", ' +
+          'and optionally "barrelLine".'
+      });
+      continue;
+    }
+
+    // Success — build result
+    const barrelDiff = validated.barrelLine
+      ? { path: barrelPath, lineToAdd: validated.barrelLine }
+      : null;
+
+    return {
+      toolFile: {
+        path:    toolFilePath,
+        content: validated.toolFile
+      },
+      testFile: {
+        path:    testFilePath,
+        content: validated.testFile
+      },
+      barrelDiff
+    };
+  }
+
+  // Exhausted retries
+  throw new Error(
+    `generateToolFiles: failed to obtain valid LLM output for "${spec.name}" ` +
+    `after ${MAX_RETRIES} attempts. Last error: ${lastError?.message}`
+  );
+}

package/lib/forge-service-client.js

@@ -0,0 +1,190 @@
+#!/usr/bin/env node
+/**
+ * Forge Service Client — CLI wrapper for the forge-service HTTP bridge.
+ * Used by the forge-tool skill (Claude) to interact with the queue.
+ *
+ * Usage:
+ *   node cli/forge-service-client.js start
+ *   node cli/forge-service-client.js health
+ *   node cli/forge-service-client.js next          # exits 0 + JSON or 1 on empty
+ *   node cli/forge-service-client.js complete
+ *   node cli/forge-service-client.js enqueue <json>
+ *   node cli/forge-service-client.js shutdown
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { spawn } from 'child_process';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PROJECT_ROOT = resolve(__dirname, '..');
+const LOCK_FILE = resolve(PROJECT_ROOT, '.forge-service.lock');
+
+function readLock() {
+  if (!existsSync(LOCK_FILE)) return null;
+  try {
+    return JSON.parse(readFileSync(LOCK_FILE, 'utf-8'));
+  } catch (_) {
+    return null;
+  }
+}
+
+async function httpRequest(method, path, body, timeoutMs = 35_000) {
+  const lock = readLock();
+  if (!lock) throw new Error('No forge service running (.forge-service.lock not found)');
+  const { port } = lock;
+
+  const { request } = await import('http');
+  return new Promise((res, rej) => {
+    const payload = body ? JSON.stringify(body) : undefined;
+    const options = {
+      hostname: '127.0.0.1',
+      port,
+      path,
+      method,
+      headers: {
+        'Content-Type': 'application/json',
+        ...(payload ? { 'Content-Length': Buffer.byteLength(payload) } : {})
+      }
+    };
+
+    const req = request(options, (response) => {
+      let data = '';
+      response.on('data', (chunk) => { data += chunk; });
+      response.on('end', () => {
+        res({ statusCode: response.statusCode, body: data });
+      });
+    });
+
+    req.on('error', rej);
+    const timer = setTimeout(() => {
+      req.destroy(new Error('timeout'));
+    }, timeoutMs);
+
+    req.on('close', () => clearTimeout(timer));
+
+    if (payload) req.write(payload);
+    req.end();
+  });
+}
+
+async function cmdStart() {
+  const existing = readLock();
+  if (existing) {
+    // Verify it's actually alive
+    try {
+      const r = await httpRequest('GET', '/health', null, 3000);
+      if (r.statusCode === 200) {
+        const data = JSON.parse(r.body);
+        console.log(`Forge service already active on port ${existing.port}`);
+        console.log(JSON.stringify(data));
+        process.exit(0);
+      }
+    } catch (_) {
+      // Stale lock — remove it before spawning a new instance
+    }
+    try {
+      const { unlinkSync } = await import('fs');
+      unlinkSync(LOCK_FILE);
+    } catch (_) { /* ignore */ }
+  }
+
+  const child = spawn('node', [resolve(__dirname, 'forge-service.js')], {
+    detached: true,
+    stdio: ['ignore', 'pipe', 'pipe']
+  });
+
+  let output = '';
+  let stderrOutput = '';
+  child.stdout.on('data', (d) => { output += d.toString(); });
+  child.stderr.on('data', (d) => { stderrOutput += d.toString(); });
+
+  await new Promise((res, rej) => {
+    const timeout = setTimeout(() => {
+      const detail = stderrOutput.trim() ? `\nService stderr: ${stderrOutput.trim()}` : '';
+      rej(new Error(`Service start timeout${detail}`));
+    }, 10_000);
+    const poll = setInterval(() => {
+      if (readLock()) {
+        clearTimeout(timeout);
+        clearInterval(poll);
+        res();
+      }
+    }, 200);
+    child.on('error', (err) => { clearTimeout(timeout); clearInterval(poll); rej(err); });
+  });
+
+  child.unref();
+  const lock = readLock();
+  console.log(`Forge service started on port ${lock.port}`);
+  process.exit(0);
+}
+
+async function cmdHealth() {
+  const r = await httpRequest('GET', '/health');
+  console.log(r.body);
+  process.exit(r.statusCode === 200 ? 0 : 1);
+}
+
+async function cmdNext() {
+  // Long-poll /next — 30s server timeout + 35s client timeout
+  const r = await httpRequest('GET', '/next', null, 36_000);
+  if (r.statusCode === 200) {
+    console.log(r.body);
+    process.exit(0);
+  } else {
+    // 204 = nothing in queue after timeout
+    process.exit(1);
+  }
+}
+
+async function cmdComplete() {
+  const r = await httpRequest('POST', '/complete');
+  console.log(r.body);
+  process.exit(r.statusCode === 200 ? 0 : 1);
+}
+
+async function cmdEnqueue(jsonArg) {
+  if (!jsonArg) {
+    console.error('Usage: forge-service-client.js enqueue <json>');
+    process.exit(1);
+  }
+  let endpoint;
+  try {
+    endpoint = JSON.parse(jsonArg);
+  } catch (_) {
+    console.error('Invalid JSON argument');
+    process.exit(1);
+  }
+  const r = await httpRequest('POST', '/enqueue', { endpoint });
+  console.log(r.body);
+  process.exit(r.statusCode === 200 ? 0 : 1);
+}
+
+async function cmdShutdown() {
+  const r = await httpRequest('DELETE', '/shutdown');
+  console.log(r.body);
+  process.exit(0);
+}
+
+const [,, cmd, ...args] = process.argv;
+
+const handlers = {
+  start: cmdStart,
+  health: cmdHealth,
+  next: cmdNext,
+  complete: cmdComplete,
+  enqueue: () => cmdEnqueue(args[0]),
+  shutdown: cmdShutdown
+};
+
+if (!cmd || !handlers[cmd]) {
+  console.error(`Usage: forge-service-client.js <start|health|next|complete|enqueue|shutdown>`);
+  process.exit(1);
+}
+
+handlers[cmd]().catch((err) => {
+  console.error(`Error: ${err.message}`);
+  process.exit(1);
+});

package/lib/forge-service.d.ts

@@ -0,0 +1,4 @@
+// forge-service.js implements buildSidecarContext and createSidecarRouter.
+// These functions are re-exported by sidecar.js and declared there to avoid duplication.
+export { buildSidecarContext, createSidecarRouter } from './sidecar.js';
+export type { SidecarContext, SidecarOptions } from './sidecar.js';