la-machina-engine 0.13.0 → 0.15.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,23 @@ 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 HEADER_NAME_RE = /^[!#$%&'*+\-.0-9A-Z^_`a-z|~]+$/;
+var RESERVED_HEADER_NAMES = /* @__PURE__ */ new Set([
+  "authorization",
+  "cookie",
+  "set-cookie",
+  "proxy-authorization"
+]);
 var ApiServiceSchema = import_zod.z.object({
   name: import_zod.z.string().min(1),
   description: import_zod.z.string().optional(),
@@ -1269,11 +1288,46 @@ 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()
-}).strict();
+  maxBodyBytes: import_zod.z.number().int().positive().optional(),
+  endpoints: import_zod.z.array(ApiEndpointSchema).optional(),
+  secretHeaders: import_zod.z.record(import_zod.z.string(), import_zod.z.string().min(1)).optional()
+}).strict().superRefine((svc, ctx) => {
+  if (svc.secretHeaders === void 0) return;
+  const lowerDefault = /* @__PURE__ */ new Set();
+  for (const k of Object.keys(svc.defaultHeaders ?? {})) lowerDefault.add(k.toLowerCase());
+  for (const headerName of Object.keys(svc.secretHeaders)) {
+    if (!HEADER_NAME_RE.test(headerName)) {
+      ctx.addIssue({
+        code: "custom",
+        message: `secretHeaders key "${headerName}" is not a valid HTTP header name (RFC 7230 token charset)`,
+        path: ["secretHeaders", headerName]
+      });
+      continue;
+    }
+    const lower = headerName.toLowerCase();
+    if (RESERVED_HEADER_NAMES.has(lower)) {
+      ctx.addIssue({
+        code: "custom",
+        message: `secretHeaders key "${headerName}" is reserved \u2014 primary \`auth\` owns ${headerName}`,
+        path: ["secretHeaders", headerName]
+      });
+      continue;
+    }
+    if (lowerDefault.has(lower)) {
+      ctx.addIssue({
+        code: "custom",
+        message: `secretHeaders key "${headerName}" collides with defaultHeaders (case-insensitive). Move the secret-bearing version to secretHeaders only.`,
+        path: ["secretHeaders", headerName]
+      });
+    }
+  }
+});
+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 +8101,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 +8210,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
@@ -8273,6 +8418,12 @@ function createApiCallTool(opts) {
         `createApiCallTool: service "${svc.name}" uses custom auth (id: ${svc.auth.id}) but no resolveAuth was supplied`
       );
     }
+    const hasSecretHeaders = svc.secretHeaders !== void 0 && Object.keys(svc.secretHeaders).length > 0;
+    if (hasSecretHeaders && opts.resolveAuth === void 0) {
+      throw new Error(
+        `createApiCallTool: service "${svc.name}" declares secretHeaders but no resolveAuth was supplied (the resolver is required to look up the secret values)`
+      );
+    }
   }
   const fetchFn = opts.fetch ?? globalThis.fetch.bind(globalThis);
   const maxResponseBytes = opts.maxResponseBytes ?? DEFAULT_MAX_RESPONSE_BYTES;
@@ -8307,13 +8458,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;
@@ -8336,13 +8488,20 @@ function createApiCallTool(opts) {
           return errResult(`ERR_API_BODY_TOO_LARGE: exceeds ${cap} bytes`);
         }
       }
+      const secretHeaderRefs = svc.secretHeaders !== void 0 && Object.keys(svc.secretHeaders).length > 0 ? svc.secretHeaders : void 0;
       let authHeaders;
       try {
         authHeaders = await resolveAuth({
           auth: svc.auth ?? { type: "none" },
           env: opts.env,
           resolver: opts.resolveAuth,
-          ctx: { serviceName: svc.name, method: input.method, path: input.path }
+          ctx: {
+            serviceName: svc.name,
+            method: input.method,
+            path: input.path,
+            ...secretHeaderRefs !== void 0 ? { secretHeaderRefs } : {}
+          },
+          forceResolve: secretHeaderRefs !== void 0
         });
       } catch (err) {
         const raw2 = err instanceof Error ? err.message : String(err);
@@ -8409,6 +8568,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;
 }
@@ -8430,22 +8610,27 @@ function sanitizeHeaders(user, auth) {
   return out;
 }
 async function resolveAuth(args) {
-  const { auth, env, resolver, ctx } = args;
+  const { auth, env, resolver, ctx, forceResolve } = args;
+  let primary;
   switch (auth.type) {
     case "none":
-      return {};
+      primary = {};
+      break;
     case "bearer": {
       const token = envLookup(env, auth.tokenRef);
-      return { Authorization: `Bearer ${token}` };
+      primary = { Authorization: `Bearer ${token}` };
+      break;
     }
     case "header": {
       const value = envLookup(env, auth.valueRef);
-      return { [auth.name]: value };
+      primary = { [auth.name]: value };
+      break;
     }
     case "basic": {
       const u = envLookup(env, auth.userRef);
       const p = envLookup(env, auth.passRef);
-      return { Authorization: `Basic ${base64(`${u}:${p}`)}` };
+      primary = { Authorization: `Basic ${base64(`${u}:${p}`)}` };
+      break;
     }
     case "custom":
       if (resolver === void 0) {
@@ -8453,6 +8638,14 @@ async function resolveAuth(args) {
       }
       return resolver(auth, ctx);
   }
+  if (forceResolve === true) {
+    if (resolver === void 0) {
+      throw new Error("secretHeaders require a resolveAuth callback (host did not supply one)");
+    }
+    const extra = await resolver(auth, ctx);
+    return { ...primary, ...extra };
+  }
+  return primary;
 }
 function envLookup(env, ref) {
   if (env === void 0 || env[ref] === void 0) {
@@ -8474,12 +8667,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 +9031,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 +9138,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 +9250,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 +10854,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 +11058,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 +12355,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 +12456,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 +12569,7 @@ function resolveApiKey(config) {
   canSpawnProcesses,
   capabilityStub,
   createApiCallTool,
+  createDescribeServiceTool,
   createFetchDataTool,
   createLogger,
   createModelAdapter,
@@ -12303,6 +12586,7 @@ function resolveApiKey(config) {
   getCoordinatorBasePrompt,
   getCoordinatorSystemPrompt,
   getExtractor,
+  hasDescribableEndpoints,
   hasProcessLifecycle,
   initEngine,
   isCoordinatorMode,