loopengine 0.1.4 → 0.1.5

package/dist/index.d.ts

@@ -27,6 +27,8 @@ export { listQuestions, answerQuestion as resolvePendingQuestion, findQuestion,
 export type { PendingQuestion } from './core/system-tools/index.js';
 export { editAgentFile, AgentEditNotSupportedError, AgentFileNotFoundError } from './web/agent-file-admin.js';
 export type { AgentEditableFields, AgentEditResult } from './web/agent-file-admin.js';
+export { createHttpTool, HttpToolNameError, HttpToolExistsError, HttpToolIndexShapeError } from './web/http-tool-admin.js';
+export type { HttpToolSpec, HttpToolField } from './web/http-tool-admin.js';
 export { agentsConfigPageHtml } from './web/agents-config-page.js';
 export { agentsListPageHtml } from './web/agents-list-page.js';
 export { globalConfigPageHtml } from './web/global-config-page.js';

package/dist/index.js

@@ -34,6 +34,7 @@ export { WebhookNotifier } from './core/http-notify-triggers/webhook.js';
 // question in-process, aliased to avoid colliding with that name.
 export { listQuestions, answerQuestion as resolvePendingQuestion, findQuestion, createAskUserTool } from './core/system-tools/index.js';
 export { editAgentFile, AgentEditNotSupportedError, AgentFileNotFoundError } from './web/agent-file-admin.js';
+export { createHttpTool, HttpToolNameError, HttpToolExistsError, HttpToolIndexShapeError } from './web/http-tool-admin.js';
 export { agentsConfigPageHtml } from './web/agents-config-page.js';
 export { agentsListPageHtml } from './web/agents-list-page.js';
 export { globalConfigPageHtml } from './web/global-config-page.js';

package/dist/web/agents-config-page.js

@@ -131,6 +131,18 @@ export const agentsConfigPageHtml = `<!doctype html>
     letter-spacing: normal;
     padding: 2px 8px;
   }
+  .http-tool-subsection {
+    margin-top: 14px;
+    padding-top: 14px;
+    border-top: 1px dashed light-dark(#eee, #2a2a2e);
+  }
+  .http-tool-subsection h4 {
+    font-size: 12px;
+    text-transform: uppercase;
+    letter-spacing: 0.04em;
+    color: light-dark(#666, #999);
+    margin: 0 0 8px;
+  }
   pre {
     background: light-dark(#fff, #26262b);
     border: 1px solid light-dark(#ddd, #3a3a3e);
@@ -1145,7 +1157,9 @@ export const agentsConfigPageHtml = `<!doctype html>
   // describeGatewayTools), a real cost not worth paying up front. ----
 
   function renderToolsTabHtml(cfg) {
-    return '<section><h3>Local tools (' + cfg.localTools.length + ')</h3>' + renderTools(cfg.localTools) + '</section>' +
+    return '<section><h3>Local tools (' + cfg.localTools.length + ')</h3>' + renderTools(cfg.localTools) +
+      '<div class="http-tool-subsection"><h4>Create an HTTP tool</h4>' + renderHttpToolFormHtml() + '</div>' +
+      '</section>' +
       '<section id="gatewayToolsSection">' +
         '<h3>Gateway Tools <button type="button" id="gatewayToolsRefreshBtn" class="hint-btn">Refresh</button></h3>' +
         '<div id="gatewayToolsContent"><p class="hint">Loading&hellip;</p></div>' +
@@ -1153,6 +1167,170 @@ export const agentsConfigPageHtml = `<!doctype html>
       '<section><h3>Agent as Tools (' + cfg.agentAsTools.length + ')</h3>' + renderTools(cfg.agentAsTools) + '</section>';
   }
 
+  // ---- Create an HTTP tool: generates a real agents/:name/tools/<tool>.ts
+  // file from this form (loopengine's own createHttpTool), never arbitrary
+  // code — only one shape, a parameterized HTTP call. See
+  // web/http-tool-admin.ts's own header comment for why this is the line
+  // this repo draws instead of, say, storing code in a SKILL.md and
+  // executing it at request time. ----
+
+  var httpToolFieldRowCount = 0;
+  var httpToolHeaderRowCount = 0;
+
+  function renderHttpToolFieldRow(index) {
+    return '<div class="http-tool-field-row" data-row="' + index + '">' +
+      '<input type="text" class="http-tool-field-name" placeholder="field_name" pattern="[a-zA-Z_][a-zA-Z0-9_]*">' +
+      '<select class="http-tool-field-type">' +
+        '<option value="string">string</option>' +
+        '<option value="number">number</option>' +
+        '<option value="boolean">boolean</option>' +
+      '</select>' +
+      '<input type="text" class="http-tool-field-description" placeholder="description (optional)">' +
+      '<label class="http-tool-inline-label"><input type="checkbox" class="http-tool-field-required" checked> required</label>' +
+      '<button type="button" class="delete-btn http-tool-remove-row" title="Remove this field" aria-label="Remove this field">Delete</button>' +
+      '</div>';
+  }
+
+  function renderHttpToolHeaderRow(index) {
+    return '<div class="http-tool-header-row" data-row="' + index + '">' +
+      '<input type="text" class="http-tool-header-key" placeholder="Header-Name">' +
+      '<input type="text" class="http-tool-header-value" placeholder="value, {field}, or {{ENV_VAR}}">' +
+      '<button type="button" class="delete-btn http-tool-remove-row" title="Remove this header" aria-label="Remove this header">Delete</button>' +
+      '</div>';
+  }
+
+  function renderHttpToolFormHtml() {
+    httpToolFieldRowCount = 0;
+    httpToolHeaderRowCount = 0;
+    return '<form class="add-source" id="httpToolForm">' +
+      '<label>Name <span class="hint">(snake_case, e.g. lookup_order_status)</span>' +
+        '<input type="text" name="name" required pattern="[a-z][a-z0-9_]*" placeholder="lookup_order_status">' +
+      '</label>' +
+      '<label>Description' +
+        '<input type="text" name="description" required placeholder="What this tool does">' +
+      '</label>' +
+      '<label>Fields' +
+        '<div id="httpToolFieldRows"></div>' +
+        '<button type="button" id="httpToolAddFieldBtn" class="hint-btn">Add field</button>' +
+      '</label>' +
+      '<label>Method &amp; URL <span class="hint">(use {field} for a field defined above)</span>' +
+        '<div class="http-tool-method-url">' +
+          '<select name="method">' +
+            '<option value="GET">GET</option>' +
+            '<option value="POST">POST</option>' +
+            '<option value="PUT">PUT</option>' +
+            '<option value="PATCH">PATCH</option>' +
+            '<option value="DELETE">DELETE</option>' +
+          '</select>' +
+          '<input type="text" name="url" required placeholder="https://api.example.com/orders/{orderId}">' +
+        '</div>' +
+      '</label>' +
+      '<label>Headers <span class="hint">(a value may reference {field} or {{ENV_VAR}} &mdash; never paste a real secret here)</span>' +
+        '<div id="httpToolHeaderRows"></div>' +
+        '<button type="button" id="httpToolAddHeaderBtn" class="hint-btn">Add header</button>' +
+      '</label>' +
+      '<label class="http-tool-inline-label"><input type="checkbox" name="sendFieldsAsJsonBody"> Send fields as a JSON body (POST/PUT/PATCH only)</label>' +
+      '<label>Response JSON path <span class="hint">(optional &mdash; e.g. data.status; leave blank to return the raw response text)</span>' +
+        '<input type="text" name="responseJsonPath" placeholder="data.status">' +
+      '</label>' +
+      '<label>Grant permission <span class="hint">(optional &mdash; leave blank to leave this tool at actauth&#39;s own default, typically deny)</span>' +
+        '<select name="decision">' +
+          '<option value="">(leave unset)</option>' +
+          '<option value="allow">allow</option>' +
+          '<option value="ask">ask</option>' +
+          '<option value="deny">deny</option>' +
+        '</select>' +
+      '</label>' +
+      '<button type="submit" id="httpToolSubmitBtn">Create tool</button>' +
+      '<div id="httpToolError" class="error"></div>' +
+      '</form>';
+  }
+
+  function wireHttpToolRemoveButton(row) {
+    var btn = row.querySelector('.http-tool-remove-row');
+    btn.addEventListener('click', function () {
+      row.parentNode.removeChild(row);
+    });
+  }
+
+  function wireHttpToolFormHandlers(name) {
+    var form = detail.querySelector('#httpToolForm');
+    if (!form) return;
+
+    var fieldRows = detail.querySelector('#httpToolFieldRows');
+    var headerRows = detail.querySelector('#httpToolHeaderRows');
+    var addFieldBtn = detail.querySelector('#httpToolAddFieldBtn');
+    var addHeaderBtn = detail.querySelector('#httpToolAddHeaderBtn');
+    var errorEl = detail.querySelector('#httpToolError');
+    var submitBtn = detail.querySelector('#httpToolSubmitBtn');
+
+    addFieldBtn.addEventListener('click', function () {
+      fieldRows.insertAdjacentHTML('beforeend', renderHttpToolFieldRow(httpToolFieldRowCount++));
+      wireHttpToolRemoveButton(fieldRows.lastElementChild);
+    });
+    addHeaderBtn.addEventListener('click', function () {
+      headerRows.insertAdjacentHTML('beforeend', renderHttpToolHeaderRow(httpToolHeaderRowCount++));
+      wireHttpToolRemoveButton(headerRows.lastElementChild);
+    });
+
+    form.addEventListener('submit', function (ev) {
+      ev.preventDefault();
+      errorEl.textContent = '';
+
+      var fields = [];
+      var fieldRowEls = fieldRows.querySelectorAll('.http-tool-field-row');
+      for (var i = 0; i < fieldRowEls.length; i++) {
+        var row = fieldRowEls[i];
+        var fieldName = row.querySelector('.http-tool-field-name').value.trim();
+        if (!fieldName) continue;
+        fields.push({
+          name: fieldName,
+          type: row.querySelector('.http-tool-field-type').value,
+          description: row.querySelector('.http-tool-field-description').value.trim() || undefined,
+          required: row.querySelector('.http-tool-field-required').checked,
+        });
+      }
+
+      var headers = [];
+      var headerRowEls = headerRows.querySelectorAll('.http-tool-header-row');
+      for (var j = 0; j < headerRowEls.length; j++) {
+        var hrow = headerRowEls[j];
+        var headerKey = hrow.querySelector('.http-tool-header-key').value.trim();
+        if (!headerKey) continue;
+        headers.push({ key: headerKey, value: hrow.querySelector('.http-tool-header-value').value });
+      }
+
+      var formData = new FormData(form);
+      var payload = {
+        name: formData.get('name'),
+        description: formData.get('description'),
+        fields: fields,
+        method: formData.get('method'),
+        url: formData.get('url'),
+        headers: headers,
+        sendFieldsAsJsonBody: formData.get('sendFieldsAsJsonBody') === 'on',
+        responseJsonPath: formData.get('responseJsonPath') ? formData.get('responseJsonPath') : undefined,
+        decision: formData.get('decision') ? formData.get('decision') : undefined,
+      };
+
+      submitBtn.disabled = true;
+      fetch('/agents/' + encodeURIComponent(name) + '/tools/http', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify(payload),
+      })
+        .then(function (r) { return r.json().then(function (j) { return { ok: r.ok, body: j }; }); })
+        .then(function (result) {
+          if (!result.ok) throw new Error(result.body.error || 'request failed');
+          selectAgent(name);
+        })
+        .catch(function (err) {
+          errorEl.textContent = err.message;
+          submitBtn.disabled = false;
+        });
+    });
+  }
+
   // Removing a source used to be one "Remove" button per source, at the
   // bottom of the card — dropping every tool it produces at once, with
   // no way to remove just one. Each slug now gets its own remove icon
@@ -1565,6 +1743,7 @@ export const agentsConfigPageHtml = `<!doctype html>
 
     wireSkillsHandlers(cfg.name);
     wireOverviewHandlers(cfg.name);
+    wireHttpToolFormHandlers(cfg.name);
     var gatewayRefreshBtn = detail.querySelector('#gatewayToolsRefreshBtn');
     if (gatewayRefreshBtn) {
       gatewayRefreshBtn.addEventListener('click', function () { loadGatewayTab(cfg.name, true); });

package/dist/web/http-tool-admin.d.ts

@@ -0,0 +1,37 @@
+import type { ToolDefinition } from '../core/agent-config.js';
+export declare class HttpToolNameError extends Error {
+}
+export declare class HttpToolExistsError extends Error {
+}
+export declare class HttpToolIndexShapeError extends Error {
+}
+export interface HttpToolField {
+    name: string;
+    type: 'string' | 'number' | 'boolean';
+    description?: string;
+    required: boolean;
+}
+export interface HttpToolSpec {
+    name: string;
+    description: string;
+    fields: HttpToolField[];
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    url: string;
+    headers: {
+        key: string;
+        value: string;
+    }[];
+    sendFieldsAsJsonBody: boolean;
+    responseJsonPath?: string;
+}
+/** Generates agents/<agentName>/tools/<spec.name>.ts, registers it in
+ * that agent's tools/index.ts, then imports the file it just wrote and
+ * returns the real, callable ToolDefinition object — so the route
+ * handler (adapters/http.ts's POST /agents/:name/tools/http) can splice
+ * it straight into the live agent registry (core/agent-registry.ts's
+ * updateAgent) without guessing an export name or re-deriving anything
+ * this module already knows. */
+export declare function createHttpTool(agentName: string, spec: HttpToolSpec): Promise<{
+    path: string;
+    tool: ToolDefinition;
+}>;

package/dist/web/http-tool-admin.js

@@ -0,0 +1,223 @@
+// Lets an operator generate a real, hand-editable tool file from a
+// constrained form — the Tools tab's fourth section, alongside Local
+// tools/Subagents/Gateway Tools — instead of writing agents/<name>/
+// tools/<tool>.ts by hand. Deliberately narrow: the only thing this
+// generates is a parameterized HTTP call (method, a {field}-templated
+// URL, headers, an optional JSON body/response-path mapping), never
+// arbitrary code. A SKILL.md-style "store code as markdown, eval it at
+// request time" version of this was considered and rejected: SKILL.md
+// is safe specifically because its content is only ever read by the
+// model, never executed — this generates a normal, readable, type-
+// checked .ts file instead, the same class of artifact a human would
+// have written by hand, just templated for one well-understood shape.
+//
+// Field/URL/header substitution is compiled into the *generated code*
+// (a template literal with ${...} interpolations), not resolved at
+// generation time — so a value is only ever combined with the URL via
+// real encodeURIComponent, at call time, off whatever the model actually
+// passed as input. A header value may also reference {{ENV_VAR}} — the
+// generated code reads that from process.env at call time; the literal
+// secret itself is never accepted by this module, persisted to the
+// generated file, or echoed back through the admin API, the same
+// "always env-sourced, never a config literal" rule SendEmail/
+// HttpNotifierConfig's own secrets already follow (core/agent-config.ts).
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { agentDir } from '../core/gateway-tools.js';
+export class HttpToolNameError extends Error {
+}
+export class HttpToolExistsError extends Error {
+}
+export class HttpToolIndexShapeError extends Error {
+}
+const TOOL_NAME_PATTERN = /^[a-z][a-z0-9_]*$/;
+const FIELD_NAME_PATTERN = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+const ENV_VAR_PATTERN = /^[A-Z_][A-Z0-9_]*$/;
+// Same escaping bin/cli.ts's own local tsStringLiteral uses for a
+// single-quoted literal — duplicated here rather than imported, since
+// it's two lines and not worth a cross-module export for.
+function tsStringLiteral(value) {
+    return "'" + value.replace(/\\/g, '\\\\').replace(/'/g, "\\'") + "'";
+}
+// snake_case tool name -> camelCase export identifier, e.g.
+// "lookup_order_status" -> "lookupOrderStatus" — matches every
+// hand-written tool file's own convention (see agents/customer-service/
+// tools/*.ts: issue_refund.ts exports `issueRefund`, etc.).
+function toCamelCase(snakeCase) {
+    return snakeCase.replace(/_([a-z0-9])/g, (_, c) => c.toUpperCase());
+}
+// Escapes a literal segment for safe interpolation inside a generated
+// JS template literal (backtick string) — the three characters that
+// would otherwise break out of it or start a nested interpolation.
+function escapeTemplateLiteralSegment(segment) {
+    return segment.replace(/\\/g, '\\\\').replace(/`/g, '\\`').replace(/\$\{/g, '\\${');
+}
+/** Compiles a "{field}" template string into the *inside* of a JS
+ * template literal (caller wraps it in backticks) — each {field}
+ * becomes `${wrap(fieldExpr)}`, everything else is a literal segment,
+ * escaped for backtick safety. Throws if a referenced field isn't one
+ * of `fieldNames` — a typo'd placeholder should fail at generation
+ * time, not silently produce "undefined" in a live request later. */
+function compileFieldTemplate(template, fieldNames, wrap) {
+    let out = '';
+    let lastIndex = 0;
+    const pattern = /\{([a-zA-Z_][a-zA-Z0-9_]*)\}/g;
+    let match;
+    while ((match = pattern.exec(template))) {
+        out += escapeTemplateLiteralSegment(template.slice(lastIndex, match.index));
+        const field = match[1];
+        if (!fieldNames.has(field)) {
+            throw new HttpToolNameError(`Template references {${field}}, which isn't one of this tool's own fields.`);
+        }
+        out += '${' + wrap(`input.${field}`) + '}';
+        lastIndex = pattern.lastIndex;
+    }
+    out += escapeTemplateLiteralSegment(template.slice(lastIndex));
+    return out;
+}
+function generateToolCode(spec) {
+    const fieldNames = new Set(spec.fields.map((f) => f.name));
+    for (const field of spec.fields) {
+        if (!FIELD_NAME_PATTERN.test(field.name)) {
+            throw new HttpToolNameError(`Field name "${field.name}" must be a valid identifier (letters, digits, underscore, not starting with a digit).`);
+        }
+    }
+    // Every distinct {{ENV_VAR}} referenced across header values becomes
+    // one `const NAME = process.env.NAME` read (with a clear failure if
+    // unset), generated once up front — cleaner than inlining a
+    // read-and-check expression at every point of use, and it means a
+    // missing secret fails loudly the moment the tool actually runs, not
+    // silently as an empty header value.
+    const envVars = new Set();
+    const headerEntries = spec.headers.map(({ key, value }) => {
+        let compiled = '';
+        let lastIndex = 0;
+        const pattern = /\{\{([A-Z_][A-Z0-9_]*)\}\}|\{([a-zA-Z_][a-zA-Z0-9_]*)\}/g;
+        let match;
+        while ((match = pattern.exec(value))) {
+            compiled += escapeTemplateLiteralSegment(value.slice(lastIndex, match.index));
+            if (match[1]) {
+                if (!ENV_VAR_PATTERN.test(match[1])) {
+                    throw new HttpToolNameError(`"{{${match[1]}}}" isn't a valid env var name (uppercase letters, digits, underscore).`);
+                }
+                envVars.add(match[1]);
+                compiled += '${' + match[1] + '}';
+            }
+            else {
+                const field = match[2];
+                if (!fieldNames.has(field)) {
+                    throw new HttpToolNameError(`Header "${key}" references {${field}}, which isn't one of this tool's own fields.`);
+                }
+                compiled += '${String(input.' + field + ')}';
+            }
+            lastIndex = pattern.lastIndex;
+        }
+        compiled += escapeTemplateLiteralSegment(value.slice(lastIndex));
+        return { key, compiled };
+    });
+    const urlInner = compileFieldTemplate(spec.url, fieldNames, (expr) => `encodeURIComponent(String(${expr}))`);
+    const properties = spec.fields
+        .map((f) => `      ${JSON.stringify(f.name)}: { type: ${JSON.stringify(f.type)}${f.description ? `, description: ${JSON.stringify(f.description)}` : ''} },`)
+        .join('\n');
+    const required = spec.fields.filter((f) => f.required).map((f) => JSON.stringify(f.name));
+    const envReads = [...envVars]
+        .map((name) => `    const ${name} = process.env.${name}\n    if (!${name}) throw new Error(${tsStringLiteral(`${spec.name}: ${name} is not set`)})\n`)
+        .join('');
+    const headersObj = headerEntries.length === 0
+        ? ''
+        : `      headers: {\n${headerEntries.map(({ key, compiled }) => `        ${JSON.stringify(key)}: \`${compiled}\`,`).join('\n')}\n      },\n`;
+    const bodyLine = spec.sendFieldsAsJsonBody && spec.method !== 'GET' && spec.method !== 'DELETE' ? '      body: JSON.stringify(input),\n' : '';
+    const responseHandling = spec.responseJsonPath
+        ? (() => {
+            const segments = spec.responseJsonPath.split('.').filter(Boolean);
+            for (const seg of segments) {
+                if (!FIELD_NAME_PATTERN.test(seg)) {
+                    throw new HttpToolNameError(`responseJsonPath segment "${seg}" must be a valid identifier.`);
+                }
+            }
+            const access = segments.map((s) => `?.${s}`).join('');
+            return `    const body = await res.json()\n    return JSON.stringify(body${access} ?? null)\n`;
+        })()
+        : '    return await res.text()\n';
+    return `// Generated by the Admin UI's HTTP tool builder (Tools tab) — a
+// parameterized HTTP call, not hand-written logic. Edit freely for
+// anything this template can't express; the Admin UI only ever
+// regenerates a tool it created itself, never overwrites a file it
+// doesn't recognize (see web/http-tool-admin.ts's own HttpToolExistsError).
+import type { ToolDefinition } from 'loopengine'
+
+export const ${toCamelCase(spec.name)}: ToolDefinition = {
+  name: ${tsStringLiteral(spec.name)},
+  description: ${tsStringLiteral(spec.description)},
+  input_schema: {
+    type: 'object',
+    properties: {
+${properties}
+    },
+    required: [${required.join(', ')}],
+  },
+  execute: async (input) => {
+${envReads}    const res = await fetch(\`${urlInner}\`, {
+      method: ${tsStringLiteral(spec.method)},
+${headersObj}${bodyLine}    })
+    if (!res.ok) throw new Error(\`${spec.name}: HTTP \${res.status}\`)
+${responseHandling}  },
+}
+`;
+}
+// tools/index.ts's own shape is deliberately simple and consistent
+// across every real example in this repo (agents/customer-service/
+// tools/index.ts, create-loopengine's own template) — a handful of
+// named imports, then one `export const tools: ToolDefinition[] = [...]`
+// array literal. This patches that exact shape with two small string
+// edits (one new import line, one new array entry) rather than a full
+// TS-AST rewrite; if the file has been hand-edited into something this
+// pattern doesn't recognize, it refuses instead of risking corrupting it
+// — same "refuse rather than guess" discipline agent-file-admin.ts's own
+// doc comment already establishes for index.ts edits.
+function addToolToIndex(toolsIndexPath, toolFileName, exportName) {
+    const source = readFileSync(toolsIndexPath, 'utf8');
+    const arrayMatch = source.match(/export const tools: ToolDefinition\[\] = \[([^\]]*)\]/);
+    if (!arrayMatch) {
+        throw new HttpToolIndexShapeError(`${toolsIndexPath} doesn't match the expected "export const tools: ToolDefinition[] = [...]" shape — add this tool to it by hand instead.`);
+    }
+    const importLine = `import { ${exportName} } from './${toolFileName}.js'\n`;
+    const lastImportMatch = [...source.matchAll(/^import .+\n/gm)].pop();
+    const insertAt = lastImportMatch ? lastImportMatch.index + lastImportMatch[0].length : 0;
+    const withImport = source.slice(0, insertAt) + importLine + source.slice(insertAt);
+    const existingEntries = arrayMatch[1].trim();
+    const newEntries = existingEntries ? `${existingEntries}, ${exportName}` : exportName;
+    const withEntry = withImport.replace(/export const tools: ToolDefinition\[\] = \[([^\]]*)\]/, `export const tools: ToolDefinition[] = [${newEntries}]`);
+    writeFileSync(toolsIndexPath, withEntry);
+}
+/** Generates agents/<agentName>/tools/<spec.name>.ts, registers it in
+ * that agent's tools/index.ts, then imports the file it just wrote and
+ * returns the real, callable ToolDefinition object — so the route
+ * handler (adapters/http.ts's POST /agents/:name/tools/http) can splice
+ * it straight into the live agent registry (core/agent-registry.ts's
+ * updateAgent) without guessing an export name or re-deriving anything
+ * this module already knows. */
+export async function createHttpTool(agentName, spec) {
+    if (!TOOL_NAME_PATTERN.test(spec.name)) {
+        throw new HttpToolNameError(`Tool name must be lowercase snake_case (e.g. "lookup_order_status") — got "${spec.name}"`);
+    }
+    const toolsDir = join(agentDir(agentName), 'tools');
+    const toolPath = join(toolsDir, `${spec.name}.ts`);
+    if (existsSync(toolPath)) {
+        throw new HttpToolExistsError(`agents/${agentName}/tools/${spec.name}.ts already exists — pick a different name or edit it directly.`);
+    }
+    const code = generateToolCode(spec);
+    mkdirSync(toolsDir, { recursive: true });
+    writeFileSync(toolPath, code);
+    const indexPath = join(toolsDir, 'index.ts');
+    if (existsSync(indexPath)) {
+        addToolToIndex(indexPath, spec.name, toCamelCase(spec.name));
+    }
+    else {
+        writeFileSync(indexPath, `import type { ToolDefinition } from 'loopengine'\nimport { ${toCamelCase(spec.name)} } from './${spec.name}.js'\n\nexport const tools: ToolDefinition[] = [${toCamelCase(spec.name)}]\n`);
+    }
+    const exportName = toCamelCase(spec.name);
+    const mod = (await import(pathToFileURL(toolPath).href));
+    return { path: toolPath, tool: mod[exportName] };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loopengine",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "type": "module",
   "description": "Runtime for tool-using AI agents with a transparent ReAct loop.",
   "license": "MIT",