@agentforge-io/core 0.2.0

package/dist/services/oauth.service.js

@@ -0,0 +1,174 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GITHUB_OAUTH_SPEC = exports.GOOGLE_OAUTH_SPEC = exports.OAuthCallbackError = exports.OAUTH_STATE_TTL_MS = exports.OAUTH_STATE_COOKIE_PREFIX = void 0;
+exports.buildAuthorizeUrl = buildAuthorizeUrl;
+exports.completeAuthorization = completeAuthorization;
+exports.getOAuthProviderSpec = getOAuthProviderSpec;
+const crypto_1 = require("crypto");
+/**
+ * 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.
+ */
+exports.OAUTH_STATE_COOKIE_PREFIX = 'af_oauth_state_';
+exports.OAUTH_STATE_TTL_MS = 10 * 60 * 1000; // 10 min
+/** Build the authorize URL + a fresh random state for the cookie/store. */
+function buildAuthorizeUrl(spec, cfg) {
+    const state = (0, crypto_1.randomBytes)(16).toString('hex');
+    const params = new URLSearchParams({
+        client_id: cfg.clientId,
+        redirect_uri: cfg.callbackURL,
+        response_type: 'code',
+        state,
+        ...spec.authorizeExtras(),
+    });
+    return {
+        authorizeUrl: `${spec.authorizeUrl}?${params.toString()}`,
+        state,
+    };
+}
+/**
+ * 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.
+ */
+async function completeAuthorization(input) {
+    if (input.providerError) {
+        throw new OAuthCallbackError(input.providerError, 'Provider returned an error');
+    }
+    if (!input.code) {
+        throw new OAuthCallbackError('missing_code', 'authorization code missing');
+    }
+    if (!input.expectedState || input.expectedState !== input.returnedState) {
+        throw new OAuthCallbackError('invalid_state', 'state mismatch');
+    }
+    let accessToken;
+    try {
+        accessToken = await exchangeCodeForToken({
+            tokenUrl: input.spec.tokenUrl,
+            clientId: input.cfg.clientId,
+            clientSecret: input.cfg.clientSecret,
+            code: input.code,
+            redirectUri: input.cfg.callbackURL,
+        });
+    }
+    catch (err) {
+        throw new OAuthCallbackError('token_exchange_failed', err.message);
+    }
+    try {
+        return await input.spec.fetchProfile(accessToken);
+    }
+    catch (err) {
+        throw new OAuthCallbackError('profile_fetch_failed', err.message);
+    }
+}
+/** Stable error shape adapters can pattern-match on for the failure redirect. */
+class OAuthCallbackError extends Error {
+    constructor(code, message) {
+        super(message);
+        this.name = 'OAuthCallbackError';
+        this.code = code;
+    }
+}
+exports.OAuthCallbackError = OAuthCallbackError;
+// ─── Token exchange ────────────────────────────────────────────────────────
+async function exchangeCodeForToken(input) {
+    const body = new URLSearchParams({
+        grant_type: 'authorization_code',
+        client_id: input.clientId,
+        client_secret: input.clientSecret,
+        code: input.code,
+        redirect_uri: input.redirectUri,
+    });
+    const res = await fetch(input.tokenUrl, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/x-www-form-urlencoded',
+            Accept: 'application/json',
+        },
+        body: body.toString(),
+    });
+    if (!res.ok)
+        throw new Error(`token endpoint returned ${res.status}`);
+    const json = (await res.json());
+    if (!json.access_token)
+        throw new Error('no access_token in response');
+    return json.access_token;
+}
+// ─── Provider specs ────────────────────────────────────────────────────────
+exports.GOOGLE_OAUTH_SPEC = {
+    name: 'google',
+    authorizeUrl: 'https://accounts.google.com/o/oauth2/v2/auth',
+    tokenUrl: 'https://oauth2.googleapis.com/token',
+    authorizeExtras: () => ({
+        scope: 'openid email profile',
+        access_type: 'offline',
+        prompt: 'select_account',
+    }),
+    async fetchProfile(accessToken) {
+        const r = await fetch('https://openidconnect.googleapis.com/v1/userinfo', {
+            headers: { Authorization: `Bearer ${accessToken}` },
+        });
+        if (!r.ok)
+            throw new Error(`userinfo ${r.status}`);
+        const p = (await r.json());
+        return {
+            provider: 'google',
+            providerId: p.sub,
+            email: p.email,
+            emailVerified: p.email_verified === true,
+            name: p.name,
+            metadata: { avatar: p.picture, locale: p.locale },
+        };
+    },
+};
+exports.GITHUB_OAUTH_SPEC = {
+    name: 'github',
+    authorizeUrl: 'https://github.com/login/oauth/authorize',
+    tokenUrl: 'https://github.com/login/oauth/access_token',
+    authorizeExtras: () => ({ scope: 'user:email' }),
+    async fetchProfile(accessToken) {
+        const headers = {
+            Authorization: `Bearer ${accessToken}`,
+            Accept: 'application/vnd.github+json',
+            'User-Agent': 'agentforge',
+        };
+        const userRes = await fetch('https://api.github.com/user', { headers });
+        if (!userRes.ok)
+            throw new Error(`/user ${userRes.status}`);
+        const u = (await userRes.json());
+        // /user.email is null when private. Fetch /user/emails to get the verified primary.
+        let email = u.email ?? undefined;
+        if (!email) {
+            const emailsRes = await fetch('https://api.github.com/user/emails', { headers });
+            if (emailsRes.ok) {
+                const emails = (await emailsRes.json());
+                email =
+                    emails.find((e) => e.primary && e.verified)?.email ??
+                        emails.find((e) => e.verified)?.email;
+            }
+        }
+        return {
+            provider: 'github',
+            providerId: String(u.id),
+            email,
+            emailVerified: !!email, // GitHub only returns verified emails through /user/emails
+            name: u.name || u.login,
+            metadata: {
+                username: u.login,
+                avatar: u.avatar_url,
+                profileUrl: u.html_url,
+            },
+        };
+    },
+};
+/** Look up a built-in spec by name. Returns undefined for unknown names. */
+function getOAuthProviderSpec(name) {
+    if (name === 'google')
+        return exports.GOOGLE_OAUTH_SPEC;
+    if (name === 'github')
+        return exports.GITHUB_OAUTH_SPEC;
+    return undefined;
+}

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

@@ -0,0 +1,57 @@
+/**
+ * Endpoint + scope configuration for a single OAuth2 provider. The
+ * ConnectorRegistry holds one of these per registered connector.
+ *
+ * Why per-connector and not global: each provider has different scopes,
+ * different authorize/token URLs, and may require provider-specific extras
+ * like Google's `access_type=offline` for refresh tokens.
+ */
+export interface OAuth2ProviderConfig {
+    authorizeUrl: string;
+    tokenUrl: string;
+    clientId: string;
+    clientSecret: string;
+    /** Space-delimited scopes when building the authorize URL. */
+    scopes: string[];
+    /** Extra query params merged into the authorize URL (e.g. Google's
+     *  `access_type=offline`, `prompt=consent`). */
+    authorizeExtras?: Record<string, string>;
+    /** PKCE: defaults to true for security, but providers that don't support
+     *  it (rare in 2026) can opt out. */
+    usePkce?: boolean;
+}
+export interface AuthorizeUrlResult {
+    url: string;
+    state: string;
+    /** Opaque payload the caller must persist (e.g. in a cookie/session) and
+     *  hand back to `exchangeCode` so PKCE verification can complete. */
+    pkceVerifier?: string;
+}
+export interface TokenSet {
+    accessToken: string;
+    refreshToken?: string;
+    /** Seconds remaining when issued; absolute expiry is computed by the
+     *  caller against `Date.now()` to avoid clock drift inside this service. */
+    expiresIn?: number;
+    scope?: string;
+    tokenType?: string;
+}
+interface OAuth2ServiceDeps {
+    /** Override for tests. */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Provider-agnostic OAuth2 dance. Holds zero per-user state — callers are
+ * responsible for storing the issued tokens. Designed so that the same
+ * instance can serve every connector (Google, Slack, Notion, …); the
+ * provider config is passed in on each call.
+ */
+export declare class OAuth2Service {
+    private readonly fetchImpl;
+    constructor(deps?: OAuth2ServiceDeps);
+    buildAuthorizeUrl(cfg: OAuth2ProviderConfig, redirectUri: string): AuthorizeUrlResult;
+    exchangeCode(cfg: OAuth2ProviderConfig, code: string, redirectUri: string, pkceVerifier?: string): Promise<TokenSet>;
+    refresh(cfg: OAuth2ProviderConfig, refreshToken: string): Promise<TokenSet>;
+    private postToken;
+}
+export {};

package/dist/services/oauth2.service.js

@@ -0,0 +1,82 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OAuth2Service = void 0;
+const crypto_1 = require("crypto");
+/**
+ * Provider-agnostic OAuth2 dance. Holds zero per-user state — callers are
+ * responsible for storing the issued tokens. Designed so that the same
+ * instance can serve every connector (Google, Slack, Notion, …); the
+ * provider config is passed in on each call.
+ */
+class OAuth2Service {
+    constructor(deps = {}) {
+        this.fetchImpl = deps.fetchImpl ?? fetch;
+    }
+    buildAuthorizeUrl(cfg, redirectUri) {
+        const state = (0, crypto_1.randomBytes)(16).toString('hex');
+        const usePkce = cfg.usePkce !== false;
+        const params = {
+            response_type: 'code',
+            client_id: cfg.clientId,
+            redirect_uri: redirectUri,
+            scope: cfg.scopes.join(' '),
+            state,
+            ...(cfg.authorizeExtras ?? {}),
+        };
+        let pkceVerifier;
+        if (usePkce) {
+            pkceVerifier = (0, crypto_1.randomBytes)(32).toString('base64url');
+            const challenge = (0, crypto_1.createHash)('sha256').update(pkceVerifier).digest('base64url');
+            params.code_challenge = challenge;
+            params.code_challenge_method = 'S256';
+        }
+        const url = new URL(cfg.authorizeUrl);
+        for (const [k, v] of Object.entries(params))
+            url.searchParams.set(k, v);
+        return { url: url.toString(), state, pkceVerifier };
+    }
+    async exchangeCode(cfg, code, redirectUri, pkceVerifier) {
+        const body = new URLSearchParams({
+            grant_type: 'authorization_code',
+            code,
+            redirect_uri: redirectUri,
+            client_id: cfg.clientId,
+            client_secret: cfg.clientSecret,
+        });
+        if (pkceVerifier)
+            body.set('code_verifier', pkceVerifier);
+        return this.postToken(cfg.tokenUrl, body);
+    }
+    async refresh(cfg, refreshToken) {
+        const body = new URLSearchParams({
+            grant_type: 'refresh_token',
+            refresh_token: refreshToken,
+            client_id: cfg.clientId,
+            client_secret: cfg.clientSecret,
+        });
+        return this.postToken(cfg.tokenUrl, body);
+    }
+    async postToken(tokenUrl, body) {
+        const res = await this.fetchImpl(tokenUrl, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/x-www-form-urlencoded',
+                accept: 'application/json',
+            },
+            body: body.toString(),
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => '');
+            throw new Error(`OAuth2 token endpoint ${tokenUrl} returned ${res.status}: ${text}`);
+        }
+        const json = (await res.json());
+        return {
+            accessToken: json.access_token,
+            refreshToken: json.refresh_token,
+            expiresIn: json.expires_in,
+            scope: json.scope,
+            tokenType: json.token_type,
+        };
+    }
+}
+exports.OAuth2Service = OAuth2Service;

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

@@ -0,0 +1,45 @@
+import type { AgentResponse, AnthropicMessage, SubAgentDelegation, ToolExecutionContext } from '../types/agent.types';
+import type { AgentDefinition, AnthropicConfig } from '../types/config.types';
+import type { AgentRunnerService } from './agent-runner.service';
+import type { Logger } from './tool-registry.service';
+/**
+ * Operational error. Adapters map `.status` to an HTTP code.
+ */
+export declare class OrchestratorError extends Error {
+    status: number;
+    code: 'agent_not_found';
+    constructor(code: 'agent_not_found', message: string);
+}
+export interface OrchestratorServiceOptions {
+    agents: AgentDefinition[];
+    logger?: Logger;
+}
+/**
+ * Multi-agent workflows. Orchestrator agents can delegate tasks to specialized
+ * subagents via auto-generated delegation tools that Claude sees as ordinary
+ * tools. The orchestrator runs the loop, invokes the subagent through the
+ * AgentRunnerService, and accumulates token usage across both layers.
+ *
+ * Framework-free; the Nest binding wraps this in a factory provider, the
+ * Express binding constructs it directly via createAgentForge().
+ */
+export declare class OrchestratorService {
+    private readonly anthropicConfig;
+    private readonly runner;
+    private readonly agentsMap;
+    private readonly client;
+    private readonly logger;
+    constructor(anthropicConfig: AnthropicConfig, runner: AgentRunnerService, opts: OrchestratorServiceOptions);
+    /**
+     * Run an agent. Orchestrators automatically get delegation tools injected.
+     * Non-orchestrator agents fall straight through to the runner.
+     */
+    run(agentId: string, messages: AnthropicMessage[], context: ToolExecutionContext): Promise<AgentResponse & {
+        delegations?: SubAgentDelegation[];
+    }>;
+    private runOrchestratorLoop;
+    private buildDelegationTools;
+    private getAgent;
+    listAgents(): AgentDefinition[];
+    getAgentById(id: string): AgentDefinition | undefined;
+}

package/dist/services/orchestrator.service.js

@@ -0,0 +1,180 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OrchestratorService = exports.OrchestratorError = void 0;
+const sdk_1 = __importDefault(require("@anthropic-ai/sdk"));
+const crypto_1 = require("crypto");
+const noopLogger = {
+    log: () => { }, warn: () => { }, debug: () => { }, error: () => { },
+};
+/**
+ * Operational error. Adapters map `.status` to an HTTP code.
+ */
+class OrchestratorError extends Error {
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.status = 404;
+    }
+}
+exports.OrchestratorError = OrchestratorError;
+/**
+ * Multi-agent workflows. Orchestrator agents can delegate tasks to specialized
+ * subagents via auto-generated delegation tools that Claude sees as ordinary
+ * tools. The orchestrator runs the loop, invokes the subagent through the
+ * AgentRunnerService, and accumulates token usage across both layers.
+ *
+ * Framework-free; the Nest binding wraps this in a factory provider, the
+ * Express binding constructs it directly via createAgentForge().
+ */
+class OrchestratorService {
+    constructor(anthropicConfig, runner, opts) {
+        this.anthropicConfig = anthropicConfig;
+        this.runner = runner;
+        this.agentsMap = new Map();
+        this.client = new sdk_1.default({
+            apiKey: anthropicConfig.apiKey,
+            baseURL: anthropicConfig.baseURL,
+        });
+        this.logger = opts.logger ?? noopLogger;
+        for (const agent of opts.agents) {
+            this.agentsMap.set(agent.id, agent);
+        }
+    }
+    /**
+     * Run an agent. Orchestrators automatically get delegation tools injected.
+     * Non-orchestrator agents fall straight through to the runner.
+     */
+    async run(agentId, messages, context) {
+        const agent = this.getAgent(agentId);
+        if (!agent.canOrchestrate || !agent.subAgents?.length) {
+            return this.runner.run(agent, messages, context);
+        }
+        this.logger.debug(`Running orchestrator "${agentId}" with subagents: ${agent.subAgents.join(', ')}`);
+        return this.runOrchestratorLoop(agent, messages, context);
+    }
+    async runOrchestratorLoop(orchestrator, messages, context) {
+        const delegations = [];
+        const delegationTools = this.buildDelegationTools(orchestrator);
+        const model = orchestrator.model ?? this.anthropicConfig.defaultModel ?? 'claude-opus-4-6';
+        const maxTokens = orchestrator.maxTokens ?? this.anthropicConfig.defaultMaxTokens ?? 4096;
+        const anthropicTools = delegationTools.map((t) => ({
+            name: t.name,
+            description: t.description,
+            input_schema: t.inputSchema,
+        }));
+        let currentMessages = [...messages];
+        let totalUsage = { inputTokens: 0, outputTokens: 0, totalTokens: 0 };
+        let finalContent = '';
+        // ─── Agentic loop ──────────────────────────────────────────────────────
+        while (true) {
+            const response = await this.client.messages.create({
+                model,
+                max_tokens: maxTokens,
+                system: orchestrator.systemPrompt,
+                messages: currentMessages,
+                tools: anthropicTools,
+            });
+            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,
+            };
+            if (response.stop_reason === 'tool_use') {
+                const assistantMsg = { role: 'assistant', content: response.content };
+                currentMessages = [...currentMessages, assistantMsg];
+                const toolResults = [];
+                for (const block of response.content) {
+                    if (block.type !== 'tool_use')
+                        continue;
+                    const delegateTool = delegationTools.find((t) => t.name === block.name);
+                    if (!delegateTool)
+                        continue;
+                    const { task } = block.input;
+                    const { subAgentId } = delegateTool;
+                    this.logger.log(`Orchestrator "${orchestrator.id}" → "${subAgentId}": ${task.slice(0, 80)}...`);
+                    const subAgent = this.getAgent(subAgentId);
+                    const subMessages = [{ role: 'user', content: task }];
+                    const subResult = await this.runner.run(subAgent, subMessages, {
+                        ...context,
+                        agentId: subAgentId,
+                    });
+                    totalUsage.inputTokens += subResult.usage.inputTokens;
+                    totalUsage.outputTokens += subResult.usage.outputTokens;
+                    totalUsage.totalTokens += subResult.usage.totalTokens;
+                    delegations.push({
+                        subAgentId,
+                        task,
+                        result: subResult.content,
+                        usage: subResult.usage,
+                    });
+                    toolResults.push({
+                        type: 'tool_result',
+                        tool_use_id: block.id,
+                        content: subResult.content,
+                    });
+                }
+                currentMessages = [...currentMessages, { role: 'user', content: toolResults }];
+            }
+            else {
+                finalContent = response.content
+                    .filter((b) => b.type === 'text')
+                    .map((b) => b.text)
+                    .join('');
+                break;
+            }
+        }
+        return {
+            messageId: (0, crypto_1.randomUUID)(),
+            conversationId: context.conversationId,
+            content: finalContent,
+            role: 'assistant',
+            delegations: delegations.length > 0 ? delegations : undefined,
+            usage: totalUsage,
+            model,
+            stopReason: 'end_turn',
+            createdAt: new Date(),
+        };
+    }
+    // ─── Helpers ───────────────────────────────────────────────────────────────
+    buildDelegationTools(orchestrator) {
+        return (orchestrator.subAgents ?? []).map((subAgentId) => {
+            const sub = this.agentsMap.get(subAgentId);
+            const description = sub
+                ? `Delegate a task to the "${sub.name}" specialist agent. ${sub.description ?? ''}`
+                : `Delegate a task to subagent "${subAgentId}"`;
+            return {
+                name: `delegate_to_${subAgentId.replace(/[^a-zA-Z0-9]/g, '_')}`,
+                description,
+                subAgentId,
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        task: {
+                            type: 'string',
+                            description: 'The specific task or question to send to this specialist',
+                        },
+                    },
+                    required: ['task'],
+                },
+            };
+        });
+    }
+    getAgent(agentId) {
+        const agent = this.agentsMap.get(agentId);
+        if (!agent)
+            throw new OrchestratorError('agent_not_found', `Agent "${agentId}" not found`);
+        return agent;
+    }
+    listAgents() {
+        return Array.from(this.agentsMap.values());
+    }
+    getAgentById(id) {
+        return this.agentsMap.get(id);
+    }
+}
+exports.OrchestratorService = OrchestratorService;

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

@@ -0,0 +1,54 @@
+import type { PlanRepository } from '../repositories';
+import type { Plan, NewPlan, PlanPatch } from '../domain/plan';
+import type { PlanDefinition } from '../types/config.types';
+export interface PlanServiceOptions {
+    /**
+     * Plans to seed the DB with on first boot (i.e. when `af_plans` is empty).
+     * After the table has at least one row, this seed is ignored — the DB is
+     * the source of truth. Pass your `config.billing.plans` here so existing
+     * deployments migrate transparently.
+     */
+    seedPlans?: PlanDefinition[];
+}
+/**
+ * Reads and writes plan rows from the DB, with an in-process cache invalidated
+ * on every mutation. Hot-path reads (`getPlan(id)`) are O(n) over a tiny set,
+ * which is fine for the few plans most apps need.
+ *
+ * Single-instance assumption: when running multiple API instances, mutations
+ * via admin endpoints invalidate only the local cache. The next read on other
+ * instances still serves stale data until their own TTL expires. For most B2B
+ * scenarios (plan edits are rare, eventually-consistent is OK) this is fine;
+ * if you need strict consistency, set `cacheTtlMs: 0`.
+ */
+export declare class PlanService {
+    private readonly repo;
+    private readonly opts;
+    private cache;
+    private cacheLoadedAt;
+    /** Default TTL: 60 seconds. */
+    private readonly cacheTtlMs;
+    constructor(repo: PlanRepository, opts?: PlanServiceOptions);
+    /**
+     * Call once at boot. Seeds the table from `opts.seedPlans` if empty, then
+     * warms the cache. Safe to call multiple times.
+     */
+    initialize(): Promise<void>;
+    list(): Promise<Plan[]>;
+    listAll(): Promise<Plan[]>;
+    getPlan(id: string): Promise<Plan | undefined>;
+    getDefault(): Promise<Plan | undefined>;
+    getDefaultId(): Promise<string>;
+    create(plan: NewPlan): Promise<Plan>;
+    update(id: string, patch: PlanPatch): Promise<Plan>;
+    deactivate(id: string): Promise<void>;
+    /** Force the next read to bypass the cache. Useful in tests. */
+    invalidate(): void;
+    private refresh;
+    private isCacheFresh;
+}
+export declare class PlanServiceError extends Error {
+    status: number;
+    code: 'plan_exists' | 'plan_not_found' | 'plan_is_default';
+    constructor(code: 'plan_exists' | 'plan_not_found' | 'plan_is_default', message: string);
+}