@agentforge-io/core 0.2.0

package/dist/services/index.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InMemoryAuthorizeStateStore = exports.ConnectorError = exports.ConnectorRegistryService = exports.OAuth2Service = exports.McpServerError = exports.McpServerService = exports.McpClientError = exports.McpClientService = exports.ChatTokenError = exports.ChatTokenService = exports.AgentJobWorker = exports.OrchestratorError = exports.OrchestratorService = exports.AgentForbiddenError = exports.AgentService = exports.ConversationNotFoundError = exports.ConversationService = exports.InMemoryPreparedStreamStore = exports.PreparedStreamError = exports.PreparedStreamService = exports.AgentRunnerService = exports.ToolRegistryService = void 0;
+// Public service surface of @agentforge-io/core. AI runtime only — auth,
+// identity, billing, infra, etc. have all moved to the host server.
+var tool_registry_service_1 = require("./tool-registry.service");
+Object.defineProperty(exports, "ToolRegistryService", { enumerable: true, get: function () { return tool_registry_service_1.ToolRegistryService; } });
+var agent_runner_service_1 = require("./agent-runner.service");
+Object.defineProperty(exports, "AgentRunnerService", { enumerable: true, get: function () { return agent_runner_service_1.AgentRunnerService; } });
+var prepared_stream_service_1 = require("./prepared-stream.service");
+Object.defineProperty(exports, "PreparedStreamService", { enumerable: true, get: function () { return prepared_stream_service_1.PreparedStreamService; } });
+Object.defineProperty(exports, "PreparedStreamError", { enumerable: true, get: function () { return prepared_stream_service_1.PreparedStreamError; } });
+var in_memory_prepared_stream_store_1 = require("./in-memory-prepared-stream.store");
+Object.defineProperty(exports, "InMemoryPreparedStreamStore", { enumerable: true, get: function () { return in_memory_prepared_stream_store_1.InMemoryPreparedStreamStore; } });
+var conversation_service_1 = require("./conversation.service");
+Object.defineProperty(exports, "ConversationService", { enumerable: true, get: function () { return conversation_service_1.ConversationService; } });
+Object.defineProperty(exports, "ConversationNotFoundError", { enumerable: true, get: function () { return conversation_service_1.ConversationNotFoundError; } });
+var agent_service_1 = require("./agent.service");
+Object.defineProperty(exports, "AgentService", { enumerable: true, get: function () { return agent_service_1.AgentService; } });
+Object.defineProperty(exports, "AgentForbiddenError", { enumerable: true, get: function () { return agent_service_1.AgentForbiddenError; } });
+var orchestrator_service_1 = require("./orchestrator.service");
+Object.defineProperty(exports, "OrchestratorService", { enumerable: true, get: function () { return orchestrator_service_1.OrchestratorService; } });
+Object.defineProperty(exports, "OrchestratorError", { enumerable: true, get: function () { return orchestrator_service_1.OrchestratorError; } });
+var agent_job_worker_1 = require("./agent-job.worker");
+Object.defineProperty(exports, "AgentJobWorker", { enumerable: true, get: function () { return agent_job_worker_1.AgentJobWorker; } });
+var chat_token_service_1 = require("./chat-token.service");
+Object.defineProperty(exports, "ChatTokenService", { enumerable: true, get: function () { return chat_token_service_1.ChatTokenService; } });
+Object.defineProperty(exports, "ChatTokenError", { enumerable: true, get: function () { return chat_token_service_1.ChatTokenError; } });
+var mcp_client_service_1 = require("./mcp-client.service");
+Object.defineProperty(exports, "McpClientService", { enumerable: true, get: function () { return mcp_client_service_1.McpClientService; } });
+Object.defineProperty(exports, "McpClientError", { enumerable: true, get: function () { return mcp_client_service_1.McpClientError; } });
+var mcp_server_service_1 = require("./mcp-server.service");
+Object.defineProperty(exports, "McpServerService", { enumerable: true, get: function () { return mcp_server_service_1.McpServerService; } });
+Object.defineProperty(exports, "McpServerError", { enumerable: true, get: function () { return mcp_server_service_1.McpServerError; } });
+var oauth2_service_1 = require("./oauth2.service");
+Object.defineProperty(exports, "OAuth2Service", { enumerable: true, get: function () { return oauth2_service_1.OAuth2Service; } });
+var connector_registry_service_1 = require("./connector-registry.service");
+Object.defineProperty(exports, "ConnectorRegistryService", { enumerable: true, get: function () { return connector_registry_service_1.ConnectorRegistryService; } });
+Object.defineProperty(exports, "ConnectorError", { enumerable: true, get: function () { return connector_registry_service_1.ConnectorError; } });
+Object.defineProperty(exports, "InMemoryAuthorizeStateStore", { enumerable: true, get: function () { return connector_registry_service_1.InMemoryAuthorizeStateStore; } });

package/dist/services/mcp-client.service.d.ts

@@ -0,0 +1,64 @@
+import type { Logger } from './tool-registry.service';
+import type { ToolRegistryService } from './tool-registry.service';
+import type { McpServerConfig } from '../types/config.types';
+/**
+ * Lifecycle owner for connections to remote MCP servers.
+ *
+ * Boot path:
+ *   for each McpServerConfig
+ *     1. connect (StreamableHTTP first, SSE as opt-in)
+ *     2. listTools() — pull the catalog the server publishes
+ *     3. wrap each tool into an AgentToolDefinition prefixed with `<name>__`
+ *     4. register them all in the ToolRegistryService alongside built-ins
+ *
+ * The wrapped tools never expose the MCP transport details to the LLM: they
+ * look identical to a hand-written tool from the model's perspective. When
+ * the LLM invokes one, we route the call through `client.callTool` and hand
+ * back whatever the server returned (text, JSON, etc., flattened to string).
+ *
+ * Connection model is "connect at register time, keep the socket warm".
+ * A future revision can swap to lazy-connect-on-first-use if the cost of
+ * idle connections matters; for v1, eager connect makes debugging trivial
+ * (you see the failure at boot, not at the first agent message).
+ */
+export interface McpToolHandle {
+    /** Server name (the `name` field of McpServerConfig). */
+    serverName: string;
+    /** Original tool name as the MCP server announced it. */
+    toolName: string;
+    /** Prefixed name as registered in the ToolRegistry. */
+    registeredName: string;
+}
+export declare class McpClientError extends Error {
+    status: number;
+    code: 'connect_failed' | 'list_failed' | 'call_failed';
+    constructor(code: McpClientError['code'], message: string);
+}
+export declare class McpClientService {
+    private readonly registry;
+    private readonly clients;
+    private readonly registered;
+    private readonly logger;
+    constructor(registry: ToolRegistryService, opts?: {
+        logger?: Logger;
+    });
+    /**
+     * Connect, list tools, and register them. Idempotent for a given `name` —
+     * a second `register` for the same server tears down the previous client
+     * and replaces it. Useful for "edit server settings" flows.
+     */
+    register(config: McpServerConfig): Promise<McpToolHandle[]>;
+    /**
+     * Tear down a server's connection and unregister its tools. Returns the
+     * number of tools removed. Safe to call for unknown names — no-ops.
+     */
+    unregister(name: string): Promise<number>;
+    /** Best-effort shutdown of every connected MCP. Called on app shutdown. */
+    shutdown(): Promise<void>;
+    list(): {
+        name: string;
+        tools: McpToolHandle[];
+    }[];
+    isConnected(name: string): boolean;
+    private callTool;
+}

package/dist/services/mcp-client.service.js

@@ -0,0 +1,157 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.McpClientService = exports.McpClientError = void 0;
+const index_js_1 = require("@modelcontextprotocol/sdk/client/index.js");
+const sse_js_1 = require("@modelcontextprotocol/sdk/client/sse.js");
+const streamableHttp_js_1 = require("@modelcontextprotocol/sdk/client/streamableHttp.js");
+class McpClientError extends Error {
+    constructor(code, message) {
+        super(message);
+        this.status = 502;
+        this.code = code;
+    }
+}
+exports.McpClientError = McpClientError;
+class McpClientService {
+    constructor(registry, opts = {}) {
+        this.registry = registry;
+        this.clients = new Map();
+        this.registered = new Map();
+        this.logger = opts.logger ?? {
+            // eslint-disable-next-line no-console
+            log: (m) => console.log(`[mcp] ${m}`),
+            // eslint-disable-next-line no-console
+            warn: (m) => console.warn(`[mcp] ${m}`),
+            // eslint-disable-next-line no-console
+            debug: (m) => console.debug(`[mcp] ${m}`),
+            // eslint-disable-next-line no-console
+            error: (m) => console.error(`[mcp] ${m}`),
+        };
+    }
+    // ─── Lifecycle ─────────────────────────────────────────────────────────
+    /**
+     * Connect, list tools, and register them. Idempotent for a given `name` —
+     * a second `register` for the same server tears down the previous client
+     * and replaces it. Useful for "edit server settings" flows.
+     */
+    async register(config) {
+        await this.unregister(config.name);
+        const client = new index_js_1.Client({ name: 'agentforge', version: '0.2.0' }, { capabilities: {} });
+        const transport = buildTransport(config);
+        try {
+            await client.connect(transport);
+        }
+        catch (err) {
+            throw new McpClientError('connect_failed', `Failed to connect to MCP server "${config.name}": ${err.message}`);
+        }
+        this.clients.set(config.name, client);
+        let toolsResult;
+        try {
+            toolsResult = await client.listTools();
+        }
+        catch (err) {
+            throw new McpClientError('list_failed', `Failed to list tools from "${config.name}": ${err.message}`);
+        }
+        const handles = [];
+        for (const tool of toolsResult.tools) {
+            const registeredName = `${config.name}__${tool.name}`;
+            const wrapped = {
+                name: registeredName,
+                description: (tool.description ?? '') +
+                    ` (via MCP server "${config.name}")`,
+                // MCP servers publish JSON Schema directly under inputSchema.
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                inputSchema: tool.inputSchema ?? {
+                    type: 'object',
+                    properties: {},
+                },
+                execute: async (input) => {
+                    return this.callTool(config.name, tool.name, input);
+                },
+            };
+            this.registry.register(wrapped);
+            handles.push({
+                serverName: config.name,
+                toolName: tool.name,
+                registeredName,
+            });
+        }
+        this.registered.set(config.name, handles);
+        this.logger.log(`[mcp] connected "${config.name}" — registered ${handles.length} tool(s)`);
+        return handles;
+    }
+    /**
+     * Tear down a server's connection and unregister its tools. Returns the
+     * number of tools removed. Safe to call for unknown names — no-ops.
+     */
+    async unregister(name) {
+        const handles = this.registered.get(name);
+        if (handles) {
+            for (const h of handles) {
+                this.registry.unregister?.(h.registeredName);
+            }
+            this.registered.delete(name);
+        }
+        const client = this.clients.get(name);
+        if (client) {
+            try {
+                await client.close();
+            }
+            catch (err) {
+                this.logger.warn(`[mcp] error closing client "${name}": ${err.message}`);
+            }
+            this.clients.delete(name);
+        }
+        return handles?.length ?? 0;
+    }
+    /** Best-effort shutdown of every connected MCP. Called on app shutdown. */
+    async shutdown() {
+        const names = Array.from(this.clients.keys());
+        await Promise.all(names.map((n) => this.unregister(n)));
+    }
+    // ─── Introspection (for the admin UI) ──────────────────────────────────
+    list() {
+        return Array.from(this.registered.entries()).map(([name, tools]) => ({
+            name,
+            tools,
+        }));
+    }
+    isConnected(name) {
+        return this.clients.has(name);
+    }
+    // ─── Execution ─────────────────────────────────────────────────────────
+    async callTool(serverName, toolName, args) {
+        const client = this.clients.get(serverName);
+        if (!client) {
+            throw new McpClientError('call_failed', `MCP server "${serverName}" is not connected.`);
+        }
+        try {
+            const result = await client.callTool({ name: toolName, arguments: args });
+            // MCP returns `content` as an array of typed blocks; we flatten to a
+            // string the agent can read. Anything non-text becomes "[type omitted]"
+            // — the agent can ask the server for follow-up if it cares.
+            const content = (result.content ?? []);
+            return content
+                .map((c) => (c.type === 'text' ? c.text ?? '' : `[${c.type} omitted]`))
+                .join('\n');
+        }
+        catch (err) {
+            throw new McpClientError('call_failed', `MCP "${serverName}/${toolName}" failed: ${err.message}`);
+        }
+    }
+}
+exports.McpClientService = McpClientService;
+// ─── Transport factory ────────────────────────────────────────────────────
+function buildTransport(config) {
+    const url = new URL(config.url);
+    const requestInit = config.headers
+        ? { headers: config.headers }
+        : undefined;
+    if (config.transport === 'http') {
+        return new streamableHttp_js_1.StreamableHTTPClientTransport(url, { requestInit });
+    }
+    if (config.transport === 'sse') {
+        return new sse_js_1.SSEClientTransport(url, { requestInit });
+    }
+    throw new McpClientError('connect_failed', `Unsupported MCP transport: ${config.transport}`);
+}

package/dist/services/mcp-server.service.d.ts

@@ -0,0 +1,44 @@
+import type { McpServerRecord, McpServerRecordPatch } from '../domain/mcp-server';
+import type { McpServerRepository } from '../repositories';
+import type { McpClientService } from './mcp-client.service';
+export declare class McpServerError extends Error {
+    status: number;
+    code: 'invalid' | 'not_found' | 'duplicate_name';
+    constructor(code: McpServerError['code'], message: string);
+}
+export interface CreateMcpServerInput {
+    tenantId: string;
+    name: string;
+    transport: 'http' | 'sse';
+    url: string;
+    description?: string;
+    headers?: Record<string, string>;
+    isActive?: boolean;
+    createdByUserId?: string;
+}
+/**
+ * Application-level CRUD over `McpServerRecord`. The HTTP controllers
+ * (admin endpoints) call this — they don't touch the repository directly so
+ * validation (name format, uniqueness per tenant) lives in one place.
+ *
+ * Side effects on the live MCP catalog (connect / disconnect / re-register)
+ * are routed through the optional `client` dependency. When omitted (e.g.
+ * unit tests), the service is pure persistence.
+ */
+export declare class McpServerService {
+    private readonly repo;
+    private readonly client?;
+    constructor(repo: McpServerRepository, client?: McpClientService | undefined);
+    create(input: CreateMcpServerInput): Promise<McpServerRecord>;
+    listForTenant(tenantId: string): Promise<McpServerRecord[]>;
+    getById(id: string): Promise<McpServerRecord>;
+    getByIdForTenant(id: string, tenantId: string): Promise<McpServerRecord>;
+    update(id: string, tenantId: string, patch: McpServerRecordPatch): Promise<McpServerRecord>;
+    delete(id: string, tenantId: string): Promise<void>;
+    /** Boot path: connect to every active server across tenants. Failures
+     *  are logged but don't abort boot — a broken Notion key shouldn't keep
+     *  the rest of the platform from coming up. */
+    registerAllActive(): Promise<void>;
+    private assertName;
+    private assertUrl;
+}

package/dist/services/mcp-server.service.js

@@ -0,0 +1,147 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.McpServerService = exports.McpServerError = void 0;
+const crypto_1 = require("crypto");
+class McpServerError extends Error {
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.status =
+            code === 'not_found' ? 404 : code === 'duplicate_name' ? 409 : 400;
+    }
+}
+exports.McpServerError = McpServerError;
+// Match the McpClientService prefix rule: lowercase alphanumeric + underscore,
+// 2..32 chars. The name becomes a tool-name prefix so we want it cheap to read.
+const NAME_RE = /^[a-z][a-z0-9_]{1,31}$/;
+/**
+ * Application-level CRUD over `McpServerRecord`. The HTTP controllers
+ * (admin endpoints) call this — they don't touch the repository directly so
+ * validation (name format, uniqueness per tenant) lives in one place.
+ *
+ * Side effects on the live MCP catalog (connect / disconnect / re-register)
+ * are routed through the optional `client` dependency. When omitted (e.g.
+ * unit tests), the service is pure persistence.
+ */
+class McpServerService {
+    constructor(repo, client) {
+        this.repo = repo;
+        this.client = client;
+    }
+    async create(input) {
+        this.assertName(input.name);
+        this.assertUrl(input.url);
+        const existing = (await this.repo.listForTenant(input.tenantId)).find((r) => r.name === input.name);
+        if (existing) {
+            throw new McpServerError('duplicate_name', `An MCP server named "${input.name}" already exists for this tenant.`);
+        }
+        const record = {
+            id: (0, crypto_1.randomUUID)(),
+            tenantId: input.tenantId,
+            name: input.name,
+            transport: input.transport,
+            url: input.url,
+            description: input.description?.trim() || undefined,
+            headers: input.headers,
+            isActive: input.isActive ?? true,
+            createdByUserId: input.createdByUserId,
+        };
+        const saved = await this.repo.create(record);
+        if (saved.isActive && this.client) {
+            // Connect eagerly — if it fails we still keep the record so the admin
+            // can fix headers/URL and retry, but we surface the error.
+            await this.client.register(toClientConfig(saved));
+        }
+        return saved;
+    }
+    async listForTenant(tenantId) {
+        return this.repo.listForTenant(tenantId);
+    }
+    async getById(id) {
+        const r = await this.repo.findById(id);
+        if (!r)
+            throw new McpServerError('not_found', 'MCP server not found');
+        return r;
+    }
+    async getByIdForTenant(id, tenantId) {
+        const r = await this.getById(id);
+        if (r.tenantId !== tenantId) {
+            throw new McpServerError('not_found', 'MCP server not found');
+        }
+        return r;
+    }
+    async update(id, tenantId, patch) {
+        const current = await this.getByIdForTenant(id, tenantId);
+        if (patch.name !== undefined && patch.name !== current.name) {
+            this.assertName(patch.name);
+            const dup = (await this.repo.listForTenant(tenantId)).find((r) => r.name === patch.name && r.id !== id);
+            if (dup) {
+                throw new McpServerError('duplicate_name', `An MCP server named "${patch.name}" already exists for this tenant.`);
+            }
+        }
+        if (patch.url !== undefined)
+            this.assertUrl(patch.url);
+        await this.repo.update(id, patch);
+        const updated = await this.getById(id);
+        // Re-register on the live client. The McpClientService's `register` is
+        // idempotent — it tears down the previous client first.
+        if (this.client) {
+            if (updated.isActive) {
+                await this.client.register(toClientConfig(updated));
+            }
+            else {
+                await this.client.unregister(updated.name);
+            }
+        }
+        return updated;
+    }
+    async delete(id, tenantId) {
+        const record = await this.getByIdForTenant(id, tenantId);
+        if (this.client) {
+            await this.client.unregister(record.name);
+        }
+        await this.repo.delete(id);
+    }
+    /** Boot path: connect to every active server across tenants. Failures
+     *  are logged but don't abort boot — a broken Notion key shouldn't keep
+     *  the rest of the platform from coming up. */
+    async registerAllActive() {
+        if (!this.client)
+            return;
+        const active = await this.repo.listActive();
+        for (const record of active) {
+            try {
+                await this.client.register(toClientConfig(record));
+            }
+            catch {
+                // McpClientService already logs the connect_failed reason; keep going.
+            }
+        }
+    }
+    // ─── Internals ────────────────────────────────────────────────────────
+    assertName(name) {
+        if (!NAME_RE.test(name)) {
+            throw new McpServerError('invalid', 'name must be 2–32 chars, lowercase letters/digits/underscore, start with a letter');
+        }
+    }
+    assertUrl(url) {
+        try {
+            const u = new URL(url);
+            if (u.protocol !== 'http:' && u.protocol !== 'https:') {
+                throw new Error('protocol must be http or https');
+            }
+        }
+        catch (err) {
+            throw new McpServerError('invalid', `Invalid URL: ${err.message}`);
+        }
+    }
+}
+exports.McpServerService = McpServerService;
+function toClientConfig(r) {
+    return {
+        name: r.name,
+        transport: r.transport,
+        url: r.url,
+        headers: r.headers,
+    };
+}

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

@@ -0,0 +1,73 @@
+import type { OAuthProviderConfig } from '../types/config.types';
+/**
+ * Framework-free OAuth 2.0 helper. Provider specs + token exchange +
+ * profile normalization live here so every transport (Express, Nest,
+ * Fastify, …) drives the same code path. Adapters bring the HTTP shell:
+ *   - render an authorize redirect with the state we hand back
+ *   - persist that state (cookie, KV, whatever) until the callback
+ *   - call validateCallback on the way back in
+ *
+ * CSRF: the state must round-trip through the user-agent in a way the
+ * server can verify. The Express adapter uses an httpOnly cookie scoped
+ * to the callback path. The Nest adapter does the same. Custom adapters
+ * are free to pick a different mechanism as long as `state` is opaque,
+ * single-use, and tied to the originating browser.
+ */
+export interface NormalizedOAuthProfile {
+    provider: string;
+    providerId: string;
+    email?: string;
+    emailVerified?: boolean;
+    name?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface OAuthProviderSpec {
+    /** Identifier used in the URL: `/auth/{name}`. */
+    name: string;
+    authorizeUrl: string;
+    tokenUrl: string;
+    /** Optional second fetch — useful for GitHub where /user may not include email. */
+    fetchProfile: (accessToken: string) => Promise<NormalizedOAuthProfile>;
+    /** Extra params for the authorize redirect (scopes, prompts, etc.). */
+    authorizeExtras: () => Record<string, string>;
+}
+/**
+ * Public name of the state cookie/header per provider. Adapters share the
+ * convention so a session started under one transport could (in theory) be
+ * resumed under another — and so the operations docs are consistent.
+ */
+export declare const OAUTH_STATE_COOKIE_PREFIX = "af_oauth_state_";
+export declare const OAUTH_STATE_TTL_MS: number;
+/** Build the authorize URL + a fresh random state for the cookie/store. */
+export declare function buildAuthorizeUrl(spec: OAuthProviderSpec, cfg: OAuthProviderConfig): {
+    authorizeUrl: string;
+    state: string;
+};
+/**
+ * Validate the callback against the expected state and exchange the
+ * authorization code for an access token + normalized profile.
+ *
+ * Returns the profile on success. Throws OAuthCallbackError with a stable
+ * `.code` on failure — adapters surface the code in the failure redirect.
+ */
+export declare function completeAuthorization(input: {
+    spec: OAuthProviderSpec;
+    cfg: OAuthProviderConfig;
+    /** Querystring `state` sent back by the provider. */
+    returnedState: string | undefined;
+    /** State we persisted before redirecting to the provider. */
+    expectedState: string | undefined;
+    /** Querystring `code` from the provider. */
+    code: string | undefined;
+    /** Querystring `error` from the provider, if any. */
+    providerError: string | undefined;
+}): Promise<NormalizedOAuthProfile>;
+/** Stable error shape adapters can pattern-match on for the failure redirect. */
+export declare class OAuthCallbackError extends Error {
+    code: string;
+    constructor(code: string, message: string);
+}
+export declare const GOOGLE_OAUTH_SPEC: OAuthProviderSpec;
+export declare const GITHUB_OAUTH_SPEC: OAuthProviderSpec;
+/** Look up a built-in spec by name. Returns undefined for unknown names. */
+export declare function getOAuthProviderSpec(name: string): OAuthProviderSpec | undefined;