@agentforge-io/core 0.2.0

package/dist/services/agent-runner.service.js

@@ -0,0 +1,224 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentRunnerService = void 0;
+const sdk_1 = __importDefault(require("@anthropic-ai/sdk"));
+const crypto_1 = require("crypto");
+const noopLogger = {
+    log: () => { }, warn: () => { }, debug: () => { }, error: () => { },
+};
+/**
+ * Framework-free runner for Claude. Handles the agentic loop (tool calls) for
+ * sync runs and exposes streaming as an `AsyncGenerator<StreamChunk>` so any
+ * transport (SSE, fetch+ReadableStream, WebSocket, etc.) can consume it.
+ */
+class AgentRunnerService {
+    constructor(anthropicConfig, toolRegistry, opts = {}) {
+        this.anthropicConfig = anthropicConfig;
+        this.toolRegistry = toolRegistry;
+        this.client = new sdk_1.default({
+            apiKey: anthropicConfig.apiKey,
+            baseURL: anthropicConfig.baseURL,
+        });
+        this.logger = opts.logger ?? noopLogger;
+    }
+    // ─── Run (non-streaming) ──────────────────────────────────────────────────
+    async run(agent, messages, context, overrides) {
+        const messageId = (0, crypto_1.randomUUID)();
+        const model = overrides?.model ?? agent.model ?? this.anthropicConfig.defaultModel ?? 'claude-opus-4-6';
+        const maxTokens = overrides?.maxTokens ?? agent.maxTokens ?? this.anthropicConfig.defaultMaxTokens ?? 4096;
+        const temperature = overrides?.temperature ?? agent.temperature ?? 1;
+        const systemPrompt = overrides?.systemPromptSuffix
+            ? `${agent.systemPrompt}\n\n${overrides.systemPromptSuffix}`
+            : agent.systemPrompt;
+        const { tools, extras } = this.buildToolList(agent, overrides);
+        const toolCalls = [];
+        let currentMessages = [...messages];
+        let totalUsage = { inputTokens: 0, outputTokens: 0, totalTokens: 0 };
+        let finalContent = '';
+        let stopReason = 'end_turn';
+        while (true) {
+            const response = await this.client.messages.create({
+                model,
+                max_tokens: maxTokens,
+                temperature,
+                system: systemPrompt,
+                messages: currentMessages,
+                tools: tools,
+            });
+            totalUsage = {
+                inputTokens: totalUsage.inputTokens + response.usage.input_tokens,
+                outputTokens: totalUsage.outputTokens + response.usage.output_tokens,
+                totalTokens: totalUsage.totalTokens + response.usage.input_tokens + response.usage.output_tokens,
+                cacheCreationInputTokens: (totalUsage.cacheCreationInputTokens ?? 0) +
+                    (response.usage.cache_creation_input_tokens ?? 0),
+                cacheReadInputTokens: (totalUsage.cacheReadInputTokens ?? 0) +
+                    (response.usage.cache_read_input_tokens ?? 0),
+            };
+            stopReason = response.stop_reason ?? 'end_turn';
+            if (response.stop_reason === 'tool_use') {
+                currentMessages = [...currentMessages, { role: 'assistant', content: response.content }];
+                const toolResults = [];
+                for (const block of response.content) {
+                    if (block.type === 'tool_use') {
+                        const start = Date.now();
+                        let output = '';
+                        let error;
+                        try {
+                            output = await this.dispatchTool(block.name, block.input, context, extras);
+                        }
+                        catch (err) {
+                            error = err instanceof Error ? err.message : String(err);
+                            output = `Error executing tool ${block.name}: ${error}`;
+                        }
+                        toolCalls.push({
+                            toolName: block.name,
+                            toolUseId: block.id,
+                            input: block.input,
+                            output,
+                            error,
+                            durationMs: Date.now() - start,
+                        });
+                        toolResults.push({
+                            type: 'tool_result',
+                            tool_use_id: block.id,
+                            content: output,
+                            is_error: !!error,
+                        });
+                    }
+                }
+                currentMessages = [...currentMessages, { role: 'user', content: toolResults }];
+            }
+            else {
+                finalContent = response.content
+                    .filter((b) => b.type === 'text')
+                    .map((b) => b.text)
+                    .join('');
+                break;
+            }
+        }
+        return {
+            messageId,
+            conversationId: context.conversationId,
+            content: finalContent,
+            role: 'assistant',
+            toolCalls: toolCalls.length > 0 ? toolCalls : undefined,
+            usage: totalUsage,
+            model,
+            stopReason,
+            createdAt: new Date(),
+        };
+    }
+    // ─── Run (streaming) ──────────────────────────────────────────────────────
+    async *stream(agent, messages, context, overrides) {
+        const messageId = (0, crypto_1.randomUUID)();
+        const model = overrides?.model ?? agent.model ?? this.anthropicConfig.defaultModel ?? 'claude-opus-4-6';
+        const maxTokens = overrides?.maxTokens ?? agent.maxTokens ?? this.anthropicConfig.defaultMaxTokens ?? 4096;
+        const temperature = overrides?.temperature ?? agent.temperature ?? 1;
+        const systemPrompt = overrides?.systemPromptSuffix
+            ? `${agent.systemPrompt}\n\n${overrides.systemPromptSuffix}`
+            : agent.systemPrompt;
+        const { tools, extras } = this.buildToolList(agent, overrides);
+        let currentMessages = [...messages];
+        let totalUsage = { inputTokens: 0, outputTokens: 0, totalTokens: 0 };
+        while (true) {
+            const stream = this.client.messages.stream({
+                model,
+                max_tokens: maxTokens,
+                temperature,
+                system: systemPrompt,
+                messages: currentMessages,
+                tools: tools,
+            });
+            for await (const event of stream) {
+                if (event.type === 'content_block_start') {
+                    if (event.content_block.type === 'tool_use') {
+                        yield {
+                            type: 'tool_use_start',
+                            toolName: event.content_block.name,
+                            toolUseId: event.content_block.id,
+                        };
+                    }
+                }
+                else if (event.type === 'content_block_delta') {
+                    if (event.delta.type === 'text_delta') {
+                        yield { type: 'text_delta', delta: event.delta.text };
+                    }
+                }
+                else if (event.type === 'message_delta') {
+                    const deltaUsage = event.usage;
+                    totalUsage = {
+                        inputTokens: totalUsage.inputTokens + (deltaUsage?.input_tokens ?? 0),
+                        outputTokens: totalUsage.outputTokens + (deltaUsage?.output_tokens ?? 0),
+                        totalTokens: totalUsage.totalTokens +
+                            (deltaUsage?.input_tokens ?? 0) +
+                            (deltaUsage?.output_tokens ?? 0),
+                    };
+                }
+            }
+            const finalMessage = await stream.finalMessage();
+            if (finalMessage.stop_reason === 'tool_use') {
+                currentMessages = [...currentMessages, { role: 'assistant', content: finalMessage.content }];
+                const toolResults = [];
+                for (const block of finalMessage.content) {
+                    if (block.type === 'tool_use') {
+                        let output = '';
+                        try {
+                            output = await this.dispatchTool(block.name, block.input, context, extras);
+                        }
+                        catch (err) {
+                            output = `Error: ${err instanceof Error ? err.message : String(err)}`;
+                        }
+                        yield { type: 'tool_result', toolName: block.name, result: output };
+                        toolResults.push({ type: 'tool_result', tool_use_id: block.id, content: output });
+                    }
+                }
+                currentMessages = [...currentMessages, { role: 'user', content: toolResults }];
+            }
+            else {
+                break;
+            }
+        }
+        yield { type: 'usage', usage: totalUsage };
+        yield { type: 'done', messageId };
+    }
+    /**
+     * Merge `agent.tools[]` (resolved via the global registry) with any
+     * per-call extras (e.g. the user's connector tools).
+     *
+     * Returns:
+     *   - `tools`: the Anthropic-shaped array sent to the LLM
+     *   - `extras`: a name→definition map so `dispatchTool` can route execution
+     *     for tools that aren't in the global registry
+     *
+     * Extras with the same name as a global tool shadow the global one — useful
+     * when a connector wants to override the built-in `http_request`, for
+     * example. The shadowing only lasts for this call.
+     */
+    buildToolList(agent, overrides) {
+        const fromRegistry = agent.tools?.length
+            ? this.toolRegistry.getToolsForAgent(agent.id, agent.tools)
+            : [];
+        const extras = new Map();
+        const extrasSchema = [];
+        for (const t of overrides?.extraTools ?? []) {
+            extras.set(t.name, t);
+            extrasSchema.push({
+                name: t.name,
+                description: t.description,
+                input_schema: t.inputSchema,
+            });
+        }
+        const tools = [...fromRegistry, ...extrasSchema];
+        return { tools: tools.length ? tools : undefined, extras };
+    }
+    async dispatchTool(name, input, context, extras) {
+        const extra = extras.get(name);
+        if (extra)
+            return extra.execute(input, context);
+        return this.toolRegistry.execute(name, input, context);
+    }
+}
+exports.AgentRunnerService = AgentRunnerService;

package/dist/services/agent.service.d.ts

@@ -0,0 +1,171 @@
+import type { AgentDefinition, McpServerConfig } from '../types/config.types';
+import type { AgentResponse, AgentOverrides, StreamChunk } from '../types/agent.types';
+import type { SdkHooks } from '../types/hooks';
+import type { AgentRunnerService } from './agent-runner.service';
+import type { ConversationService } from './conversation.service';
+import type { ConnectorRegistryService } from './connector-registry.service';
+/**
+ * Minimal record the host's agent-config layer must supply to resolve
+ * agents by `(tenantId, slug)` or by id. The SDK doesn't care where this
+ * data comes from — DB, in-memory, JSON file — only that the resolver
+ * implements this contract.
+ *
+ * Fields are intentionally a strict subset of `AgentDefinition`; the SDK
+ * maps them via `toAgentDefinition` below.
+ */
+export interface AgentRecord {
+    id: string;
+    tenantId?: string;
+    slug?: string;
+    name: string;
+    description?: string;
+    model?: string;
+    systemPrompt: string;
+    context?: string;
+    temperature?: number;
+    topP?: number;
+    maxTokens?: number;
+    tools?: string[];
+    mcpServers?: McpServerConfig[];
+    metadata?: Record<string, unknown>;
+    isActive?: boolean;
+}
+/**
+ * Host-supplied resolver for per-tenant agent configurations. The SDK never
+ * persists agents itself; the host owns that. Inject an implementation when
+ * the host wants slug-based lookups; otherwise the SDK falls back to the
+ * `config.agents` array.
+ */
+export interface AgentResolver {
+    findBySlug(tenantId: string, slug: string): Promise<AgentRecord | null>;
+    findByIdForTenant(id: string, tenantId: string): Promise<AgentRecord | null>;
+    findById(id: string): Promise<AgentRecord | null>;
+}
+export interface AgentNotFoundError extends Error {
+    status: 404;
+}
+export declare class AgentForbiddenError extends Error {
+    status: number;
+    code: string;
+    constructor(reason: string);
+}
+/**
+ * Resolve params for agent lookup. Either an `agentId` (UUID — comes from
+ * either the DB or the hardcoded `config.agents` array) or a tenant-scoped
+ * `slug` (only meaningful in B2B requests). Both can be present; slug wins
+ * because that's the only form a tenant's API-key caller can guess.
+ */
+export interface AgentResolveParams {
+    agentId?: string;
+    agentSlug?: string;
+    /** Required when resolving by slug. Pass `req.user.tenantId` from B2B paths. */
+    tenantId?: string;
+}
+export declare class AgentService {
+    private readonly agents;
+    private readonly runner;
+    private readonly conversations;
+    /** When wired, agents created via the admin UI are looked up here first;
+     *  the hardcoded `agents` array remains a fallback for legacy installs. */
+    private readonly resolver?;
+    /** Host-supplied hooks for observing runtime events. The host owns
+     *  persistence of usage/audit; the SDK only emits. */
+    private readonly hooks?;
+    /** When wired, every streamMessage / sendMessage call attaches the
+     *  authenticated user's connector tools (Gmail, Drive, …) on the fly
+     *  via `overrides.extraTools`. Optional — connectors are opt-in. */
+    private readonly connectorRegistry?;
+    constructor(agents: AgentDefinition[], runner: AgentRunnerService, conversations: ConversationService, 
+    /** When wired, agents created via the admin UI are looked up here first;
+     *  the hardcoded `agents` array remains a fallback for legacy installs. */
+    resolver?: AgentResolver | undefined, 
+    /** Host-supplied hooks for observing runtime events. The host owns
+     *  persistence of usage/audit; the SDK only emits. */
+    hooks?: SdkHooks | undefined, 
+    /** When wired, every streamMessage / sendMessage call attaches the
+     *  authenticated user's connector tools (Gmail, Drive, …) on the fly
+     *  via `overrides.extraTools`. Optional — connectors are opt-in. */
+    connectorRegistry?: ConnectorRegistryService | undefined);
+    /**
+     * Fetch the connector tools the user has authorized, swallowing failures.
+     * The agent loop must keep working even if a connector's refresh token is
+     * dead — the toolbelt just shrinks. Specific tools may still surface their
+     * own auth errors when actually invoked.
+     */
+    private resolveExtraTools;
+    private dispatchUsage;
+    private dispatchTurnComplete;
+    listAgents(_userId?: string): AgentDefinition[];
+    /**
+     * Legacy synchronous lookup against the hardcoded `config.agents` array.
+     * Kept for backwards compat (existing callers like the orchestrator still
+     * use it). New code paths should call `resolveAgent` which also hits the DB.
+     */
+    getAgent(agentId: string): AgentDefinition;
+    /**
+     * Resolve an agent from any combination of id/slug. Order:
+     *   1. `agentSlug` + `tenantId` against the DB. This is the SDK path.
+     *   2. `agentId` against the DB (UI may store agentId in conversations).
+     *   3. `agentId` against the hardcoded `config.agents` array (fallback).
+     *
+     * Returns the runtime `AgentDefinition` ready to feed the runner.
+     */
+    resolveAgent(params: AgentResolveParams): Promise<AgentDefinition>;
+    createConversation(params: {
+        userId: string;
+        agentId?: string;
+        agentSlug?: string;
+        tenantId?: string;
+        title?: string;
+        metadata?: Record<string, unknown>;
+        initialMessage?: string;
+    }): Promise<{
+        conversation: import("..").Conversation;
+        firstResponse: AgentResponse;
+    } | {
+        conversation: import("..").Conversation;
+        firstResponse?: undefined;
+    }>;
+    sendMessage(params: {
+        conversationId: string;
+        userId: string;
+        content: string;
+        overrides?: AgentOverrides;
+    }): Promise<AgentResponse>;
+    streamMessage(params: {
+        conversationId: string;
+        userId: string;
+        content: string;
+        overrides?: AgentOverrides;
+    }): AsyncGenerator<StreamChunk>;
+    getConversation(conversationId: string, userId: string): Promise<import("../types/agent.types").ConversationHistory>;
+    listConversations(userId: string, options?: {
+        agentId?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<import("..").Conversation[]>;
+    /**
+     * Create a conversation and stream the first assistant reply in one go.
+     *
+     * Designed for the public chat surface: the widget POSTs a single endpoint
+     * and expects a `conversation` SSE event followed by the streamed chunks.
+     * The caller (PublicChatController) is responsible for surfacing the
+     * conversation id via a custom SSE event before the chunks start flowing.
+     */
+    streamCreateConversation(params: {
+        userId: string;
+        agentId?: string;
+        agentSlug?: string;
+        tenantId?: string;
+        title?: string;
+        metadata?: Record<string, unknown>;
+        content: string;
+        overrides?: AgentOverrides;
+    }): AsyncGenerator<{
+        kind: 'conversation';
+        conversationId: string;
+    } | {
+        kind: 'chunk';
+        chunk: StreamChunk;
+    }>;
+}