la-machina-engine 0.13.0 → 0.14.0

package/dist/index.cjs

@@ -137,23 +137,23 @@ var init_fetchData = __esm({
 });
 
 // src/orchestrator/types.ts
-var import_zod26, PlanStepSchema, PlanSchema;
+var import_zod27, PlanStepSchema, PlanSchema;
 var init_types = __esm({
   "src/orchestrator/types.ts"() {
     "use strict";
     init_cjs_shims();
-    import_zod26 = require("zod");
-    PlanStepSchema = import_zod26.z.object({
-      id: import_zod26.z.string().min(1),
-      description: import_zod26.z.string().min(1),
-      action: import_zod26.z.enum(["research", "implement", "verify", "review", "custom"]),
-      files: import_zod26.z.array(import_zod26.z.string()).optional(),
-      spec: import_zod26.z.string().optional(),
-      dependsOn: import_zod26.z.array(import_zod26.z.string()).optional()
+    import_zod27 = require("zod");
+    PlanStepSchema = import_zod27.z.object({
+      id: import_zod27.z.string().min(1),
+      description: import_zod27.z.string().min(1),
+      action: import_zod27.z.enum(["research", "implement", "verify", "review", "custom"]),
+      files: import_zod27.z.array(import_zod27.z.string()).optional(),
+      spec: import_zod27.z.string().optional(),
+      dependsOn: import_zod27.z.array(import_zod27.z.string()).optional()
     });
-    PlanSchema = import_zod26.z.object({
-      summary: import_zod26.z.string().min(1),
-      steps: import_zod26.z.array(PlanStepSchema).min(1)
+    PlanSchema = import_zod27.z.object({
+      summary: import_zod27.z.string().min(1),
+      steps: import_zod27.z.array(PlanStepSchema).min(1)
     });
   }
 });
@@ -889,6 +889,7 @@ __export(src_exports, {
   canSpawnProcesses: () => canSpawnProcesses,
   capabilityStub: () => capabilityStub,
   createApiCallTool: () => createApiCallTool,
+  createDescribeServiceTool: () => createDescribeServiceTool,
   createFetchDataTool: () => createFetchDataTool,
   createLogger: () => createLogger,
   createModelAdapter: () => createModelAdapter,
@@ -905,6 +906,7 @@ __export(src_exports, {
   getCoordinatorBasePrompt: () => getCoordinatorBasePrompt,
   getCoordinatorSystemPrompt: () => getCoordinatorSystemPrompt,
   getExtractor: () => getExtractor,
+  hasDescribableEndpoints: () => hasDescribableEndpoints,
   hasProcessLifecycle: () => hasProcessLifecycle,
   initEngine: () => initEngine,
   isCoordinatorMode: () => isCoordinatorMode,
@@ -1259,6 +1261,16 @@ var ApiAuthSchema = import_zod.z.discriminatedUnion("type", [
   }).strict(),
   import_zod.z.object({ type: import_zod.z.literal("custom"), id: import_zod.z.string().min(1) }).strict()
 ]);
+var ApiEndpointSchema = import_zod.z.object({
+  method: ApiHttpMethodEnum,
+  path: import_zod.z.string().regex(/^\//, "path must start with /"),
+  description: import_zod.z.string().min(1),
+  // JSON Schema 7 — passed through opaquely. Validated at author
+  // time by higher-level tooling (nikaido's yaml compiler), not
+  // here.
+  inputSchema: import_zod.z.unknown().optional(),
+  outputHint: import_zod.z.string().optional()
+}).strict();
 var ApiServiceSchema = import_zod.z.object({
   name: import_zod.z.string().min(1),
   description: import_zod.z.string().optional(),
@@ -1269,11 +1281,15 @@ var ApiServiceSchema = import_zod.z.object({
   allowedPaths: import_zod.z.array(import_zod.z.union([import_zod.z.string(), import_zod.z.instanceof(RegExp)])).optional(),
   allowedMethods: import_zod.z.array(ApiHttpMethodEnum).optional(),
   defaultHeaders: import_zod.z.record(import_zod.z.string(), import_zod.z.string()).optional(),
-  maxBodyBytes: import_zod.z.number().int().positive().optional()
+  maxBodyBytes: import_zod.z.number().int().positive().optional(),
+  endpoints: import_zod.z.array(ApiEndpointSchema).optional()
 }).strict();
+var ApiCatalogModeEnum = import_zod.z.enum(["eager", "lazy", "auto"]);
 var ApiConfigResolved = import_zod.z.object({
   services: import_zod.z.array(ApiServiceSchema),
-  maxResponseBytes: import_zod.z.number().int().positive().optional()
+  maxResponseBytes: import_zod.z.number().int().positive().optional(),
+  mode: ApiCatalogModeEnum.optional(),
+  lazyTokenThreshold: import_zod.z.number().int().positive().optional()
 }).strict();
 var KnowledgeConfigResolved = import_zod.z.object({
   enabled: import_zod.z.boolean(),
@@ -8047,6 +8063,89 @@ function getMcpSection(options) {
   return lines.join("\n");
 }
 
+// src/prompts/sections/apiServices.ts
+init_cjs_shims();
+var DEFAULT_LAZY_TOKEN_THRESHOLD = 6e3;
+function getApiServicesSection(opts) {
+  if (opts.services.length === 0) return null;
+  const threshold = opts.lazyTokenThreshold ?? DEFAULT_LAZY_TOKEN_THRESHOLD;
+  const effective = resolveEffectiveMode(opts.services, opts.mode, threshold);
+  const withEndpoints = [];
+  const withoutEndpoints = [];
+  for (const svc of opts.services) {
+    if (svc.endpoints !== void 0 && svc.endpoints.length > 0) {
+      withEndpoints.push(svc);
+    } else {
+      withoutEndpoints.push(svc);
+    }
+  }
+  const lines = ["# API Services"];
+  lines.push("");
+  if (effective === "eager") {
+    lines.push(
+      "Configured external HTTP APIs. Use the `ApiCall` tool to invoke \u2014 auth is injected automatically. Do not pass credentials via headers."
+    );
+    lines.push("");
+    for (const svc of withEndpoints) {
+      lines.push(`## ${svc.name}${svc.description ? ` \u2014 ${svc.description}` : ""}`);
+      lines.push(`baseUrl: ${svc.baseUrl}`);
+      lines.push("");
+      lines.push("Endpoints:");
+      for (const ep of svc.endpoints) {
+        lines.push(`- ${ep.method} ${ep.path} \u2014 ${ep.description}`);
+        if (ep.outputHint !== void 0) {
+          lines.push(`  (${ep.outputHint})`);
+        }
+      }
+      lines.push("");
+    }
+    if (withoutEndpoints.length > 0) {
+      lines.push("## Services without a structured catalog");
+      lines.push("Supply the endpoint path from context; `ApiCall` accepts any path.");
+      for (const svc of withoutEndpoints) {
+        lines.push(
+          `- ${svc.name}${svc.description ? ` \u2014 ${svc.description}` : ""} (${svc.baseUrl})`
+        );
+      }
+      lines.push("");
+    }
+  } else {
+    lines.push(
+      "Configured external HTTP APIs. Use `ApiCall` to invoke, but first call `DescribeService(service)` to fetch that service's endpoint catalog. Auth is injected automatically."
+    );
+    lines.push("");
+    for (const svc of withEndpoints) {
+      const count = svc.endpoints.length;
+      const suffix = svc.description ? ` \u2014 ${svc.description}` : "";
+      lines.push(
+        `- **${svc.name}**${suffix} \u2022 ${count} endpoint${count === 1 ? "" : "s"} \u2022 ${svc.baseUrl}`
+      );
+    }
+    if (withoutEndpoints.length > 0) {
+      lines.push("");
+      lines.push("Services without a structured catalog (no DescribeService entry):");
+      for (const svc of withoutEndpoints) {
+        lines.push(
+          `- ${svc.name}${svc.description ? ` \u2014 ${svc.description}` : ""} (${svc.baseUrl})`
+        );
+      }
+    }
+  }
+  return lines.join("\n").trimEnd();
+}
+function resolveEffectiveMode(services, requested, threshold) {
+  if (requested === "eager" || requested === "lazy") return requested;
+  let total = 0;
+  for (const svc of services) {
+    if (svc.endpoints === void 0) continue;
+    for (const ep of svc.endpoints) {
+      total += ep.description.length;
+      total += ep.method.length + ep.path.length + 4;
+    }
+  }
+  return total > threshold ? "lazy" : "eager";
+}
+
 // src/prompts/systemPrompt.ts
 async function buildSystemPrompt(options) {
   const sections = [];
@@ -8073,6 +8172,14 @@ async function buildSystemPrompt(options) {
     const mcpSection = getMcpSection({ mcpTools: options.mcpTools });
     if (mcpSection !== null) sections.push(mcpSection);
   }
+  if (options.apiServices !== void 0 && options.apiServices.length > 0) {
+    const apiSection = getApiServicesSection({
+      services: options.apiServices,
+      mode: options.apiCatalogMode ?? "lazy",
+      ...options.apiLazyTokenThreshold !== void 0 ? { lazyTokenThreshold: options.apiLazyTokenThreshold } : {}
+    });
+    if (apiSection !== null) sections.push(apiSection);
+  }
   const identity = await options.memory.recallIdentity();
   if (identity.length > 0) {
     sections.push(`# Identity
@@ -8307,13 +8414,14 @@ function createApiCallTool(opts) {
       if (!svc) {
         return errResult(`ERR_API_UNKNOWN_SERVICE: ${input.service}`);
       }
-      const allowedMethods = svc.allowedMethods ?? ALL_METHODS;
-      if (!allowedMethods.includes(input.method)) {
+      const effectiveMethods = resolveAllowedMethods(svc);
+      if (!effectiveMethods.includes(input.method)) {
         return errResult(
           `ERR_API_METHOD_NOT_ALLOWED: ${input.method} not permitted for service ${svc.name}`
         );
       }
-      if (!pathAllowed(input.path, svc.allowedPaths)) {
+      const effectivePaths = resolveAllowedPaths(svc);
+      if (!pathAllowed(input.path, effectivePaths)) {
         return errResult(`ERR_API_PATH_NOT_ALLOWED: ${input.path} for service ${svc.name}`);
       }
       let bodyText;
@@ -8409,6 +8517,27 @@ function pathAllowed(path, allowed) {
   }
   return false;
 }
+function resolveAllowedMethods(svc) {
+  if (svc.allowedMethods !== void 0) return svc.allowedMethods;
+  if (svc.endpoints && svc.endpoints.length > 0) {
+    const set = /* @__PURE__ */ new Set();
+    for (const ep of svc.endpoints) set.add(ep.method);
+    return Array.from(set);
+  }
+  return ALL_METHODS;
+}
+function resolveAllowedPaths(svc) {
+  if (svc.allowedPaths !== void 0) return svc.allowedPaths;
+  if (svc.endpoints && svc.endpoints.length > 0) {
+    const prefixes = /* @__PURE__ */ new Set();
+    for (const ep of svc.endpoints) {
+      const brace = ep.path.indexOf("{");
+      prefixes.add(brace === -1 ? ep.path : ep.path.slice(0, brace));
+    }
+    return Array.from(prefixes);
+  }
+  return void 0;
+}
 function byteLength2(s) {
   return new TextEncoder().encode(s).byteLength;
 }
@@ -8474,12 +8603,74 @@ async function invokeHook(hook, event) {
   }
 }
 
+// src/tools/describeService.ts
+init_cjs_shims();
+var import_zod24 = require("zod");
+init_contract();
+function describe(svc) {
+  const endpoints = (svc.endpoints ?? []).map(
+    (ep) => ({
+      method: ep.method,
+      path: ep.path,
+      description: ep.description,
+      ...ep.inputSchema !== void 0 ? { inputSchema: ep.inputSchema } : {},
+      ...ep.outputHint !== void 0 ? { outputHint: ep.outputHint } : {}
+    })
+  );
+  return {
+    service: svc.name,
+    ...svc.description !== void 0 ? { description: svc.description } : {},
+    baseUrl: svc.baseUrl,
+    endpoints
+  };
+}
+function hasDescribableEndpoints(svc) {
+  return svc.endpoints !== void 0 && svc.endpoints.length > 0;
+}
+function createDescribeServiceTool(opts) {
+  const describable = opts.services.filter(hasDescribableEndpoints);
+  if (describable.length === 0) {
+    throw new Error(
+      "createDescribeServiceTool: no services with endpoints[] \u2014 do not register this tool"
+    );
+  }
+  const serviceMap = /* @__PURE__ */ new Map();
+  for (const svc of describable) serviceMap.set(svc.name, svc);
+  const serviceNames = [...serviceMap.keys()];
+  const cache = /* @__PURE__ */ new Map();
+  const inputSchema19 = import_zod24.z.object({
+    service: import_zod24.z.enum(serviceNames)
+  });
+  const description = `Look up the endpoint catalog for one configured API service. Returns every endpoint's method, path, description, and input schema. Call this before invoking \`ApiCall\` when the service has lazy endpoints. Services: ${serviceNames.join(", ")}.`;
+  return defineTool({
+    name: opts.toolName ?? "DescribeService",
+    description,
+    inputSchema: inputSchema19,
+    execute: async (input) => {
+      const cached = cache.get(input.service);
+      if (cached !== void 0) {
+        return { content: JSON.stringify(cached), metadata: { cached: true } };
+      }
+      const svc = serviceMap.get(input.service);
+      if (!svc) {
+        return {
+          content: `ERR_DESCRIBE_UNKNOWN_SERVICE: ${input.service}`,
+          isError: true
+        };
+      }
+      const payload = describe(svc);
+      cache.set(input.service, payload);
+      return { content: JSON.stringify(payload), metadata: { cached: false } };
+    }
+  });
+}
+
 // src/engine/engine.ts
 init_fetchData();
 
 // src/tools/searchKnowledge.ts
 init_cjs_shims();
-var import_zod24 = require("zod");
+var import_zod25 = require("zod");
 init_contract();
 
 // src/knowledge/indexer.ts
@@ -8776,9 +8967,9 @@ function refInScope(folders, filePath) {
 
 // src/tools/searchKnowledge.ts
 var DEFAULT_MAX_RESULTS = 5;
-var inputSchema17 = import_zod24.z.object({
-  query: import_zod24.z.string().min(1),
-  maxResults: import_zod24.z.number().int().positive().optional()
+var inputSchema17 = import_zod25.z.object({
+  query: import_zod25.z.string().min(1),
+  maxResults: import_zod25.z.number().int().positive().optional()
 });
 function createSearchKnowledgeTool(opts) {
   const scoped = opts.folders.map(parseFolderRef);
@@ -8883,7 +9074,7 @@ async function loadIndex(adapter, base, cache) {
 
 // src/tools/readKnowledge.ts
 init_cjs_shims();
-var import_zod25 = require("zod");
+var import_zod26 = require("zod");
 init_contract();
 
 // src/knowledge/extractors.ts
@@ -8995,8 +9186,8 @@ function getExtractor(format) {
 
 // src/tools/readKnowledge.ts
 var DEFAULT_MAX_READ_BYTES = 1e4;
-var inputSchema18 = import_zod25.z.object({
-  ref: import_zod25.z.string().min(1)
+var inputSchema18 = import_zod26.z.object({
+  ref: import_zod26.z.string().min(1)
 });
 function createReadKnowledgeTool(opts) {
   const scoped = opts.folders.map(parseFolderRef);
@@ -10599,7 +10790,13 @@ var Engine = class {
       provider: this.config.model.provider,
       registeredToolNames: toolNameSet,
       mcpTools,
-      coordinatorMode: isCoordinatorMode(this.config)
+      coordinatorMode: isCoordinatorMode(this.config),
+      // Plan 047 — render API services catalog (lazy by default).
+      ...apiConfig !== void 0 && apiConfig.services.length > 0 ? {
+        apiServices: apiConfig.services,
+        apiCatalogMode: apiConfig.mode ?? "lazy",
+        ...apiConfig.lazyTokenThreshold !== void 0 ? { apiLazyTokenThreshold: apiConfig.lazyTokenThreshold } : {}
+      } : {}
     });
     if (options.outputFormat === "json") {
       systemPrompt += "\n\n" + buildSchemaPrompt(options.outputSchema);
@@ -10797,7 +10994,13 @@ var Engine = class {
       provider: this.config.model.provider,
       registeredToolNames: toolNameSet,
       mcpTools,
-      coordinatorMode: isCoordinatorMode(this.config)
+      coordinatorMode: isCoordinatorMode(this.config),
+      // Plan 047 — render API services catalog (lazy by default).
+      ...apiConfig !== void 0 && apiConfig.services.length > 0 ? {
+        apiServices: apiConfig.services,
+        apiCatalogMode: apiConfig.mode ?? "lazy",
+        ...apiConfig.lazyTokenThreshold !== void 0 ? { apiLazyTokenThreshold: apiConfig.lazyTokenThreshold } : {}
+      } : {}
     });
     if (options.outputFormat === "json") {
       systemPrompt += "\n\n" + buildSchemaPrompt(options.outputSchema);
@@ -12088,6 +12291,21 @@ function buildToolRegistry(options) {
       registry.register(apiTool);
       childRegistry.register(apiTool);
     }
+    const describable = options.apiConfig.services.filter(
+      (s) => s.endpoints !== void 0 && s.endpoints.length > 0
+    );
+    if (describable.length > 0) {
+      const requested = options.apiConfig.mode ?? "lazy";
+      const threshold = options.apiConfig.lazyTokenThreshold ?? DEFAULT_LAZY_TOKEN_THRESHOLD;
+      const effective = resolveEffectiveMode(options.apiConfig.services, requested, threshold);
+      if (effective === "lazy") {
+        if (!disabled.has("DescribeService") && (wantAll || enabled.has("DescribeService"))) {
+          const describeTool = createDescribeServiceTool({ services: describable });
+          registry.register(describeTool);
+          childRegistry.register(describeTool);
+        }
+      }
+    }
   }
   if (options.toolResultOffload?.enabled === true) {
     if (!disabled.has("FetchData") && (wantAll || enabled.has("FetchData"))) {
@@ -12174,9 +12392,9 @@ init_contract();
 
 // src/tools/capabilityStub.ts
 init_cjs_shims();
-var import_zod27 = require("zod");
+var import_zod28 = require("zod");
 init_contract();
-var anyInput = import_zod27.z.unknown();
+var anyInput = import_zod28.z.unknown();
 function capabilityStub(original) {
   return defineTool({
     name: original.name,
@@ -12287,6 +12505,7 @@ function resolveApiKey(config) {
   canSpawnProcesses,
   capabilityStub,
   createApiCallTool,
+  createDescribeServiceTool,
   createFetchDataTool,
   createLogger,
   createModelAdapter,
@@ -12303,6 +12522,7 @@ function resolveApiKey(config) {
   getCoordinatorBasePrompt,
   getCoordinatorSystemPrompt,
   getExtractor,
+  hasDescribableEndpoints,
   hasProcessLifecycle,
   initEngine,
   isCoordinatorMode,