@almadar/integrations 2.41.0 → 2.42.0

package/dist/{BaseIntegration-CWdas-N_.d.ts → BaseIntegration-D_iNTesu.d.ts}

@@ -1,4 +1,4 @@
-import { LogMeta } from '@almadar/core';
+import { LogMeta, ServiceHostPorts } from '@almadar/core';
 
 /**
  * Core types for Almadar integrations
@@ -138,6 +138,8 @@ interface IntegrationCallContext {
     principal?: string;
     /** The caller's roster role, from the same identity entity-ACL enforces against. */
     role?: string;
+    /** The running app, lent for this call as the caller (`llm call-tools`). */
+    host?: ServiceHostPorts;
 }
 /**
  * Factory for creating and managing integration instances

package/dist/index.d.ts

@@ -1,8 +1,9 @@
-import { e as IntegrationLogger, c as IntegrationErrorCode, a as IntegrationConfig, B as BaseIntegration, d as IntegrationFactory, g as IntegrationParams, h as IntegrationResult, I as IntegrationCallContext } from './BaseIntegration-CWdas-N_.js';
-export { b as IntegrationError, f as IntegrationParamValue, U as UnknownActionError, V as ValidationError, i as ValidationResult, j as getIntegrationFactory, r as resetIntegrationFactory, v as validateParams } from './BaseIntegration-CWdas-N_.js';
-import { e as CredentialStore, d as CredentialPersistence, H as HookDeclaration } from './store-DG5OGiuQ.js';
-export { A as ArxivActions, C as CLIActions, a as CREDENTIAL_ENTITY_TYPE, b as CREDENTIAL_MASTER_KEY_ENV, c as CredentialEntry, D as DatabaseActions, f as DatabaseDriver, g as DatabaseQueryParamValue, h as DatabaseQueryParams, i as DatabaseQueryResult, j as DatabaseRow, k as DeepAgentActions, l as DockerActions, E as EmailActions, G as GitHubActions, I as IconifyActions, m as IntegrationActionName, n as IntegrationContracts, o as IntegrationName, L as LLMIntegrationActions, M as MLActions, O as OAuthActions, p as OtelActions, Q as QueueActions, R as RedisActions, S as StorageActions, q as StripeActions, T as TwilioActions, W as WebhookActions, r as WikimediaActions, Y as YouTubeActions, s as allCredentialEnvVars, t as declaredCredentialEnvVars, u as serviceHooks } from './store-DG5OGiuQ.js';
-import { LogMeta, EntityRow, EventPayload } from '@almadar/core';
+import { e as IntegrationLogger, c as IntegrationErrorCode, a as IntegrationConfig, B as BaseIntegration, d as IntegrationFactory, g as IntegrationParams, h as IntegrationResult, I as IntegrationCallContext } from './BaseIntegration-D_iNTesu.js';
+export { b as IntegrationError, f as IntegrationParamValue, U as UnknownActionError, V as ValidationError, i as ValidationResult, j as getIntegrationFactory, r as resetIntegrationFactory, v as validateParams } from './BaseIntegration-D_iNTesu.js';
+import { e as CredentialStore, d as CredentialPersistence, H as HookDeclaration } from './store-DcennSSh.js';
+export { A as ArxivActions, C as CLIActions, a as CREDENTIAL_ENTITY_TYPE, b as CREDENTIAL_MASTER_KEY_ENV, c as CredentialEntry, D as DatabaseActions, f as DatabaseDriver, g as DatabaseQueryParamValue, h as DatabaseQueryParams, i as DatabaseQueryResult, j as DatabaseRow, k as DeepAgentActions, l as DockerActions, E as EmailActions, G as GitHubActions, I as IconifyActions, m as IntegrationActionName, n as IntegrationContracts, o as IntegrationName, L as LLMIntegrationActions, M as MLActions, O as OAuthActions, p as OtelActions, Q as QueueActions, R as RedisActions, S as StorageActions, q as StripeActions, T as TwilioActions, W as WebhookActions, r as WikimediaActions, Y as YouTubeActions, s as allCredentialEnvVars, t as declaredCredentialEnvVars, u as serviceHooks } from './store-DcennSSh.js';
+import { LogMeta, EntityRow, EventPayload, ServiceHostPorts } from '@almadar/core';
+import { AgentChatMessage, AgentTool, AgentStep, ToolCallingClient } from '@almadar/llm';
 export { GitHubIntegration } from './integrations/github/index.js';
 
 /**
@@ -620,16 +621,6 @@ declare class EsignIntegration extends BaseIntegration {
     private downloadDocument;
 }
 
-/**
- * LLM integration using @almadar/llm
- *
- * Provides 5 actions:
- * - generate: Generate text content from a prompt
- * - classify: Classify text into predefined categories
- * - extract: Extract structured data from text using a schema
- * - summarize: Summarize long text content
- * - embed: Generate embeddings for an array of texts
- */
 declare class LLMIntegration extends BaseIntegration {
     private client;
     private embeddings;
@@ -648,14 +639,41 @@ declare class LLMIntegration extends BaseIntegration {
      * `EMBEDDING_PROVIDER` / `EMBEDDING_MODEL` / `EMBEDDING_API_KEY`.
      */
     private getEmbeddings;
-    execute(action: string, params: IntegrationParams): Promise<IntegrationResult>;
+    execute(action: string, params: IntegrationParams, context?: IntegrationCallContext): Promise<IntegrationResult>;
     private generate;
     private classify;
     private extract;
     private summarize;
+    private callTools;
     private embed;
 }
 
+/**
+ * `llm call-tools`: the model operates the running app AS THE CALLER through the
+ * host's ports. Each allowlisted input is one tool (its declared payload is the
+ * schema, its `@description` the text); each allowlisted entity is one read tool.
+ * Every tool call is an ordinary dispatch on the host (guards, policies and
+ * listens all apply) whose response goes back to the model, until it replies.
+ */
+
+interface ToolLoopRequest {
+    messages: readonly AgentChatMessage[];
+    tools: readonly AgentTool[];
+    instructions?: string;
+    maxSteps?: number;
+}
+interface ToolLoopResult {
+    reply: string;
+    steps: AgentStep[];
+    usage: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+        modelCalls: number;
+    };
+}
+declare function runToolLoop(client: ToolCallingClient, host: ServiceHostPorts, request: ToolLoopRequest): Promise<ToolLoopResult>;
+
 declare class MLIntegration extends BaseIntegration {
     private readonly eventsUrl;
     private readonly timeoutMs;
@@ -1085,4 +1103,4 @@ declare class RiggerIntegration extends BaseIntegration {
     private generate;
 }
 
-export { AccountingIntegration, type AlmadarCheckoutSession, type AlmadarCustomer, type AlmadarInvoiceFailure, type AlmadarInvoicePayment, type AlmadarPortalSession, type AlmadarStripeEvent, type AlmadarStripeEventOk, type AlmadarSubscription, type AlmadarSubscriptionStatus, type AlmadarTier, ArxivIntegration, type ArxivResult, BankingIntegration, BaseIntegration, CLIIntegration, CREDENTIALS_FILE_ENV, CalendarIntegration, type CancelSubscriptionInput, ConsoleLogger, type CreateCheckoutInput, type CreateCustomerInput, type CreatePortalInput, CredentialPersistence, CredentialStore, CredentialsIntegration, DatabaseIntegration, DeepAgentIntegration, DockerIntegration, DriveIntegration, EmailIntegration, EsignIntegration, FileCredentialPersistence, HookDeclaration, type HookProviderInput, type HookProviderResult, IconifyIntegration, InMemoryPendingGrantStore, IntegrationCallContext, IntegrationConfig, type IntegrationConstructor, IntegrationErrorCode, IntegrationFactory, IntegrationLogger, IntegrationParams, IntegrationResult, LLMIntegration, MLIntegration, MetaAdsIntegration, type OAuthAuthorizeInput, OAuthGrantNotFoundError, OAuthIntegration, type OAuthProvider, OAuthSubjectMismatchError, type OAuthTokenInput, type OAuthTokenResult, OtelIntegration, type PendingAuthorization, type PendingGrantStore, PushIntegration, QueueIntegration, RedisIntegration, type RegisteredHookProvider, type RetryConfig, RiggerIntegration, type SqlGuardResult, StorageIntegration, StripeIntegration, type StripePriceMap, TwilioIntegration, type UpdateSubscriptionInput, type VerifyAndParseInput, WebhookIntegration, WikimediaIntegration, YouTubeIntegration, allHookDeclarations, assertReadOnlySelect, getActiveFactory, getInstalledCredentialStore, getIntegration, getRegisteredIntegrations, googleCalendarHookProvider, installActiveFactory, installCredentialStore, installPendingGrantStore, isKnownIntegration, parseCalendarPushNotification, registerIntegration, registeredHookProviders, resolveCredentialRef, runWithCredentialScope, uninstallCredentialStore, verifyAndParseStripeEvent, withRetry };
+export { AccountingIntegration, type AlmadarCheckoutSession, type AlmadarCustomer, type AlmadarInvoiceFailure, type AlmadarInvoicePayment, type AlmadarPortalSession, type AlmadarStripeEvent, type AlmadarStripeEventOk, type AlmadarSubscription, type AlmadarSubscriptionStatus, type AlmadarTier, ArxivIntegration, type ArxivResult, BankingIntegration, BaseIntegration, CLIIntegration, CREDENTIALS_FILE_ENV, CalendarIntegration, type CancelSubscriptionInput, ConsoleLogger, type CreateCheckoutInput, type CreateCustomerInput, type CreatePortalInput, CredentialPersistence, CredentialStore, CredentialsIntegration, DatabaseIntegration, DeepAgentIntegration, DockerIntegration, DriveIntegration, EmailIntegration, EsignIntegration, FileCredentialPersistence, HookDeclaration, type HookProviderInput, type HookProviderResult, IconifyIntegration, InMemoryPendingGrantStore, IntegrationCallContext, IntegrationConfig, type IntegrationConstructor, IntegrationErrorCode, IntegrationFactory, IntegrationLogger, IntegrationParams, IntegrationResult, LLMIntegration, MLIntegration, MetaAdsIntegration, type OAuthAuthorizeInput, OAuthGrantNotFoundError, OAuthIntegration, type OAuthProvider, OAuthSubjectMismatchError, type OAuthTokenInput, type OAuthTokenResult, OtelIntegration, type PendingAuthorization, type PendingGrantStore, PushIntegration, QueueIntegration, RedisIntegration, type RegisteredHookProvider, type RetryConfig, RiggerIntegration, type SqlGuardResult, StorageIntegration, StripeIntegration, type StripePriceMap, type ToolLoopRequest, type ToolLoopResult, TwilioIntegration, type UpdateSubscriptionInput, type VerifyAndParseInput, WebhookIntegration, WikimediaIntegration, YouTubeIntegration, allHookDeclarations, assertReadOnlySelect, getActiveFactory, getInstalledCredentialStore, getIntegration, getRegisteredIntegrations, googleCalendarHookProvider, installActiveFactory, installCredentialStore, installPendingGrantStore, isKnownIntegration, parseCalendarPushNotification, registerIntegration, registeredHookProviders, resolveCredentialRef, runToolLoop, runWithCredentialScope, uninstallCredentialStore, verifyAndParseStripeEvent, withRetry };

package/dist/index.js

@@ -13,6 +13,7 @@ import webpush from 'web-push';
 import { Readable } from 'stream';
 import { getAvailableProvider, LLMClient, EmbeddingClient } from '@almadar/llm';
 import { z } from 'zod';
+import { findInputByAddress, payloadSchemaToJsonSchema, EventPayloadSchema } from '@almadar/core';
 import { execSync, spawn } from 'child_process';
 import { tmpdir } from 'os';
 import * as oidc from 'openid-client';
@@ -2458,6 +2459,123 @@ var EsignIntegration = class extends BaseIntegration {
   }
 };
 registerIntegration("esign", EsignIntegration);
+var DEFAULT_MAX_STEPS = 8;
+var TOOL_NAME = /^[a-zA-Z0-9_-]{1,64}$/;
+function toolName(raw) {
+  if (!TOOL_NAME.test(raw)) {
+    throw new Error(`call-tools: tool name '${raw}' is not a valid tool name (letters, digits, _ and -, at most 64)`);
+  }
+  return raw;
+}
+function buildTools(host, tools) {
+  const inputs = host.inputs();
+  const out = /* @__PURE__ */ new Map();
+  for (const tool of tools) {
+    if (tool.event !== void 0) {
+      const input = findInputByAddress(inputs, tool.event, host.caller);
+      if (!input) throw new Error(`call-tools: '${tool.event}' is not a declared external input`);
+      const name = toolName(tool.event.split(".").join("__"));
+      out.set(name, {
+        def: {
+          type: "function",
+          function: { name, description: input.description ?? tool.event, parameters: payloadSchemaToJsonSchema(input.payloadSchema) }
+        },
+        target: { kind: "input", address: tool.event, input }
+      });
+    } else if (tool.read !== void 0) {
+      const name = toolName(`read__${tool.read}`);
+      out.set(name, {
+        def: {
+          type: "function",
+          function: { name, description: `Read the ${tool.read} rows you may see`, parameters: { type: "object", properties: {} } }
+        },
+        target: { kind: "read", entity: tool.read }
+      });
+    }
+  }
+  return out;
+}
+function dispatchFailure(response) {
+  if (response.rejections && response.rejections.length > 0) return response.rejections.map((r) => r.code).join(", ");
+  if (response.guardFailed !== void 0) return `guard failed: ${response.guardFailed}`;
+  if (!response.success) return response.error ?? "dispatch failed";
+  const failed = (response.effectResults ?? []).find((r) => !r.success);
+  if (failed) return failed.error ?? `${failed.effect} failed`;
+  if (!response.transitioned) return "no transition";
+  return void 0;
+}
+function parseArgs(args) {
+  let value;
+  try {
+    value = JSON.parse(args === "" ? "{}" : args);
+  } catch {
+    value = void 0;
+  }
+  return EventPayloadSchema.safeParse(value);
+}
+async function runToolLoop(client, host, request) {
+  const tools = buildTools(host, request.tools);
+  const defs = [...tools.values()].map((t) => t.def);
+  const maxSteps = request.maxSteps ?? DEFAULT_MAX_STEPS;
+  const conversation = [
+    ...request.instructions !== void 0 ? [{ role: "system", content: request.instructions }] : [],
+    ...request.messages.map((m) => ({ role: m.role, content: m.content }))
+  ];
+  const steps = [];
+  const usage = { promptTokens: 0, completionTokens: 0, totalTokens: 0, modelCalls: 0 };
+  while (usage.modelCalls < maxSteps) {
+    const turn = await client.callWithTools({ messages: conversation, tools: defs });
+    usage.modelCalls += 1;
+    if (turn.usage) {
+      usage.promptTokens += turn.usage.promptTokens;
+      usage.completionTokens += turn.usage.completionTokens;
+      usage.totalTokens += turn.usage.totalTokens;
+    }
+    conversation.push(turn.message);
+    const calls = turn.message.tool_calls ?? [];
+    if (calls.length === 0) return { reply: turn.message.content ?? "", steps, usage };
+    for (const call of calls) {
+      const args = call.function.arguments;
+      const tool = tools.get(call.function.name);
+      let content;
+      if (!tool) {
+        steps.push({ kind: "invalid", target: call.function.name, args, ok: false, detail: "not an allowed tool" });
+        content = JSON.stringify({ error: `'${call.function.name}' is not one of your tools` });
+      } else if (tool.target.kind === "read") {
+        const rows = await host.read(tool.target.entity);
+        steps.push({ kind: "read", target: tool.target.entity, args, ok: true });
+        content = JSON.stringify({ rows });
+      } else {
+        const parsed = parseArgs(args);
+        if (!parsed.success) {
+          steps.push({ kind: "input", target: tool.target.address, args, ok: false, detail: "arguments are not a JSON object" });
+          content = JSON.stringify({ error: "arguments must be a JSON object" });
+        } else {
+          const { input } = tool.target;
+          const response = await host.dispatchInput(input.orbital, {
+            targetTrait: input.trait,
+            event: input.event,
+            payload: parsed.data
+          });
+          const detail = dispatchFailure(response);
+          steps.push({ kind: "input", target: tool.target.address, args, ok: detail === void 0, ...detail !== void 0 ? { detail } : {} });
+          content = JSON.stringify(response);
+        }
+      }
+      conversation.push({ role: "tool", content, tool_call_id: call.id });
+    }
+  }
+  throw new Error(`call-tools: no reply after ${maxSteps} model calls`);
+}
+
+// src/integrations/llm/index.ts
+var CallToolsParamsSchema = z.object({
+  messages: z.array(z.object({ role: z.enum(["user", "assistant"]), content: z.string() })),
+  tools: z.array(z.object({ event: z.string().optional(), read: z.string().optional() })),
+  instructions: z.string().optional(),
+  maxSteps: z.number().int().positive().optional(),
+  model: z.string().optional()
+});
 var LLMIntegration = class extends BaseIntegration {
   constructor(config) {
     super(config);
@@ -2498,7 +2616,7 @@ var LLMIntegration = class extends BaseIntegration {
     }
     return this.embeddings;
   }
-  async execute(action, params) {
+  async execute(action, params, context) {
     const validation = this.validateParams(action, params);
     if (!validation.valid) return this.validationFailure(action, validation.errors);
     const startTime = Date.now();
@@ -2520,6 +2638,10 @@ var LLMIntegration = class extends BaseIntegration {
         case "embed":
           data = await this.executeWithRetry(() => this.embed(params));
           break;
+        // Never retried: a retry would re-fire inputs the first attempt already fired.
+        case "call-tools":
+          data = await this.callTools(params, context);
+          break;
         default:
           throw new UnknownActionError(this.config.name, action);
       }
@@ -2610,6 +2732,14 @@ Return ONLY valid JSON matching the schema.`,
     });
     return result;
   }
+  async callTools(params, context) {
+    if (!context?.host) {
+      throw new Error("llm.call-tools needs host ports: run it from a host that lends the running app (call-service on a server)");
+    }
+    const request = CallToolsParamsSchema.parse(params);
+    const client = request.model !== void 0 ? new LLMClient({ provider: this.provider, model: request.model }) : this.getClient();
+    return runToolLoop(client, context.host, request);
+  }
   async embed(params) {
     const { texts } = params;
     if (!Array.isArray(texts)) {
@@ -5837,6 +5967,6 @@ var RiggerIntegration = class extends BaseIntegration {
 };
 registerIntegration("rigger", RiggerIntegration);
 
-export { AccountingIntegration, ArxivIntegration, BankingIntegration, BaseIntegration, CLIIntegration, CREDENTIALS_FILE_ENV, CREDENTIAL_ENTITY_TYPE, CREDENTIAL_MASTER_KEY_ENV, CalendarIntegration, ConsoleLogger, CredentialStore, CredentialsIntegration, DatabaseIntegration, DeepAgentIntegration, DockerIntegration, DriveIntegration, EmailIntegration, EsignIntegration, FileCredentialPersistence, GitHubIntegration, IconifyIntegration, InMemoryPendingGrantStore, IntegrationError, IntegrationFactory, LLMIntegration, MLIntegration, MetaAdsIntegration, OAuthGrantNotFoundError, OAuthIntegration, OAuthSubjectMismatchError, OtelIntegration, PushIntegration, QueueIntegration, RedisIntegration, RiggerIntegration, StorageIntegration, StripeIntegration, TwilioIntegration, UnknownActionError, WebhookIntegration, WikimediaIntegration, YouTubeIntegration, allCredentialEnvVars, allHookDeclarations, assertReadOnlySelect, declaredCredentialEnvVars, getActiveFactory, getInstalledCredentialStore, getIntegration, getIntegrationFactory, getRegisteredIntegrations, googleCalendarHookProvider, installActiveFactory, installCredentialStore, installPendingGrantStore, isKnownIntegration, parseCalendarPushNotification, registerIntegration, registeredHookProviders, resetIntegrationFactory, resolveCredentialRef, runWithCredentialScope, serviceHooks, uninstallCredentialStore, validateParams, verifyAndParseStripeEvent, withRetry };
+export { AccountingIntegration, ArxivIntegration, BankingIntegration, BaseIntegration, CLIIntegration, CREDENTIALS_FILE_ENV, CREDENTIAL_ENTITY_TYPE, CREDENTIAL_MASTER_KEY_ENV, CalendarIntegration, ConsoleLogger, CredentialStore, CredentialsIntegration, DatabaseIntegration, DeepAgentIntegration, DockerIntegration, DriveIntegration, EmailIntegration, EsignIntegration, FileCredentialPersistence, GitHubIntegration, IconifyIntegration, InMemoryPendingGrantStore, IntegrationError, IntegrationFactory, LLMIntegration, MLIntegration, MetaAdsIntegration, OAuthGrantNotFoundError, OAuthIntegration, OAuthSubjectMismatchError, OtelIntegration, PushIntegration, QueueIntegration, RedisIntegration, RiggerIntegration, StorageIntegration, StripeIntegration, TwilioIntegration, UnknownActionError, WebhookIntegration, WikimediaIntegration, YouTubeIntegration, allCredentialEnvVars, allHookDeclarations, assertReadOnlySelect, declaredCredentialEnvVars, getActiveFactory, getInstalledCredentialStore, getIntegration, getIntegrationFactory, getRegisteredIntegrations, googleCalendarHookProvider, installActiveFactory, installCredentialStore, installPendingGrantStore, isKnownIntegration, parseCalendarPushNotification, registerIntegration, registeredHookProviders, resetIntegrationFactory, resolveCredentialRef, runToolLoop, runWithCredentialScope, serviceHooks, uninstallCredentialStore, validateParams, verifyAndParseStripeEvent, withRetry };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map