@agentforge-io/core 0.2.0

package/dist/services/agent.service.js

@@ -0,0 +1,329 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentService = exports.AgentForbiddenError = void 0;
+class AgentForbiddenError extends Error {
+    constructor(reason) {
+        super(`Usage limit exceeded: ${reason}`);
+        this.status = 403;
+        this.code = 'usage_limit';
+    }
+}
+exports.AgentForbiddenError = AgentForbiddenError;
+class AgentService {
+    constructor(agents, runner, conversations, 
+    /** When wired, agents created via the admin UI are looked up here first;
+     *  the hardcoded `agents` array remains a fallback for legacy installs. */
+    resolver, 
+    /** Host-supplied hooks for observing runtime events. The host owns
+     *  persistence of usage/audit; the SDK only emits. */
+    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. */
+    connectorRegistry) {
+        this.agents = agents;
+        this.runner = runner;
+        this.conversations = conversations;
+        this.resolver = resolver;
+        this.hooks = hooks;
+        this.connectorRegistry = connectorRegistry;
+    }
+    /**
+     * 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.
+     */
+    async resolveExtraTools(userId) {
+        if (!this.connectorRegistry)
+            return undefined;
+        try {
+            const tools = await this.connectorRegistry.toolsForUser(userId);
+            return tools.length ? tools : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async dispatchUsage(event) {
+        if (!this.hooks?.onUsage)
+            return;
+        try {
+            await this.hooks.onUsage(event);
+        }
+        catch (err) {
+            // Hooks observe, they don't control. Failures are logged and swallowed.
+            // eslint-disable-next-line no-console
+            console.warn('[agentforge] onUsage hook threw:', err);
+        }
+    }
+    async dispatchTurnComplete(event) {
+        if (!this.hooks?.onTurnComplete)
+            return;
+        try {
+            await this.hooks.onTurnComplete(event);
+        }
+        catch (err) {
+            // eslint-disable-next-line no-console
+            console.warn('[agentforge] onTurnComplete hook threw:', err);
+        }
+    }
+    // ─── Agent catalog ────────────────────────────────────────────────────────
+    listAgents(_userId) {
+        return this.agents;
+    }
+    /**
+     * 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) {
+        const agent = this.agents.find((a) => a.id === agentId);
+        if (!agent) {
+            const err = Object.assign(new Error(`Agent "${agentId}" not found`), {
+                status: 404,
+            });
+            throw err;
+        }
+        return agent;
+    }
+    /**
+     * 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.
+     */
+    async resolveAgent(params) {
+        if (params.agentSlug && params.tenantId && this.resolver) {
+            const record = await this.resolver.findBySlug(params.tenantId, params.agentSlug);
+            if (record && record.isActive)
+                return toAgentDefinition(record);
+        }
+        if (params.agentId) {
+            if (this.resolver) {
+                const record = await this.resolver
+                    .findById(params.agentId)
+                    .catch(() => null);
+                if (record && record.isActive)
+                    return toAgentDefinition(record);
+            }
+            // Final fallback: hardcoded SDK array.
+            const hardcoded = this.agents.find((a) => a.id === params.agentId);
+            if (hardcoded)
+                return hardcoded;
+        }
+        const missing = params.agentSlug ?? params.agentId ?? '<unknown>';
+        const err = Object.assign(new Error(`Agent "${missing}" not found`), { status: 404 });
+        throw err;
+    }
+    // ─── Conversations ────────────────────────────────────────────────────────
+    async createConversation(params) {
+        const agent = await this.resolveAgent({
+            agentId: params.agentId,
+            agentSlug: params.agentSlug,
+            tenantId: params.tenantId,
+        });
+        const conversation = await this.conversations.create({
+            userId: params.userId,
+            agentId: agent.id,
+            title: params.title,
+            metadata: params.metadata,
+        });
+        if (params.initialMessage) {
+            const response = await this.sendMessage({
+                conversationId: conversation.id,
+                userId: params.userId,
+                content: params.initialMessage,
+            });
+            return { conversation, firstResponse: response };
+        }
+        return { conversation };
+    }
+    // ─── Sync send ────────────────────────────────────────────────────────────
+    async sendMessage(params) {
+        const history = await this.conversations.getAnthropicMessages(params.conversationId, params.userId);
+        const conv = await this.conversations.ensureOwned(params.conversationId, params.userId);
+        if (conv.status === 'completed') {
+            const err = Object.assign(new Error('Conversation has been ended'), { status: 410 });
+            throw err;
+        }
+        const agent = await this.resolveAgent({ agentId: conv.agentId });
+        const messages = [...history, { role: 'user', content: params.content }];
+        await this.conversations.addMessage({
+            conversationId: params.conversationId,
+            userId: params.userId,
+            role: 'user',
+            content: params.content,
+        });
+        const extraTools = await this.resolveExtraTools(params.userId);
+        const response = await this.runner.run(agent, messages, {
+            userId: params.userId,
+            conversationId: params.conversationId,
+            agentId: conv.agentId,
+            messageId: 'sync',
+        }, { ...(params.overrides ?? {}), extraTools });
+        await this.conversations.addMessage({
+            conversationId: params.conversationId,
+            userId: params.userId,
+            role: 'assistant',
+            content: response.content,
+            toolCalls: response.toolCalls,
+            usage: response.usage,
+        });
+        const now = new Date();
+        const usageEvent = {
+            version: 1,
+            turnId: response.messageId,
+            conversationId: params.conversationId,
+            agentId: conv.agentId,
+            userId: params.userId,
+            provider: 'anthropic',
+            modelId: agent.model ?? 'unknown',
+            inputTokens: response.usage.inputTokens,
+            outputTokens: response.usage.outputTokens,
+            durationMs: 0,
+            at: now,
+        };
+        await this.dispatchUsage(usageEvent);
+        await this.dispatchTurnComplete({
+            version: 1,
+            turnId: response.messageId,
+            conversationId: params.conversationId,
+            agentId: conv.agentId,
+            userId: params.userId,
+            status: 'ok',
+            toolCallCount: response.toolCalls?.length ?? 0,
+            durationMs: 0,
+            at: now,
+        });
+        return response;
+    }
+    // ─── Streaming ────────────────────────────────────────────────────────────
+    async *streamMessage(params) {
+        const history = await this.conversations.getAnthropicMessages(params.conversationId, params.userId);
+        const conv = await this.conversations.ensureOwned(params.conversationId, params.userId);
+        if (conv.status === 'completed') {
+            throw Object.assign(new Error('Conversation has been ended'), { status: 410 });
+        }
+        const agent = await this.resolveAgent({ agentId: conv.agentId });
+        const messages = [...history, { role: 'user', content: params.content }];
+        await this.conversations.addMessage({
+            conversationId: params.conversationId,
+            userId: params.userId,
+            role: 'user',
+            content: params.content,
+        });
+        let fullContent = '';
+        let finalUsage = { inputTokens: 0, outputTokens: 0, totalTokens: 0 };
+        const extraTools = await this.resolveExtraTools(params.userId);
+        for await (const chunk of this.runner.stream(agent, messages, {
+            userId: params.userId,
+            conversationId: params.conversationId,
+            agentId: conv.agentId,
+            messageId: 'streaming',
+        }, { ...(params.overrides ?? {}), extraTools })) {
+            if (chunk.type === 'text_delta')
+                fullContent += chunk.delta;
+            if (chunk.type === 'usage')
+                finalUsage = chunk.usage;
+            yield chunk;
+        }
+        if (fullContent) {
+            await this.conversations.addMessage({
+                conversationId: params.conversationId,
+                userId: params.userId,
+                role: 'assistant',
+                content: fullContent,
+                usage: finalUsage,
+            });
+            const now = new Date();
+            await this.dispatchUsage({
+                version: 1,
+                turnId: 'streamed',
+                conversationId: params.conversationId,
+                agentId: conv.agentId,
+                userId: params.userId,
+                provider: 'anthropic',
+                modelId: agent.model ?? 'unknown',
+                inputTokens: finalUsage.inputTokens,
+                outputTokens: finalUsage.outputTokens,
+                durationMs: 0,
+                at: now,
+            });
+            await this.dispatchTurnComplete({
+                version: 1,
+                turnId: 'streamed',
+                conversationId: params.conversationId,
+                agentId: conv.agentId,
+                userId: params.userId,
+                status: 'ok',
+                toolCallCount: 0,
+                durationMs: 0,
+                at: now,
+            });
+        }
+    }
+    // ─── Read-side ────────────────────────────────────────────────────────────
+    async getConversation(conversationId, userId) {
+        return this.conversations.getHistory(conversationId, userId);
+    }
+    async listConversations(userId, options) {
+        return this.conversations.listForUser(userId, options);
+    }
+    /**
+     * 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.
+     */
+    async *streamCreateConversation(params) {
+        const agent = await this.resolveAgent({
+            agentId: params.agentId,
+            agentSlug: params.agentSlug,
+            tenantId: params.tenantId,
+        });
+        const conversation = await this.conversations.create({
+            userId: params.userId,
+            agentId: agent.id,
+            title: params.title,
+            metadata: params.metadata,
+        });
+        yield { kind: 'conversation', conversationId: conversation.id };
+        for await (const chunk of this.streamMessage({
+            conversationId: conversation.id,
+            userId: params.userId,
+            content: params.content,
+            overrides: params.overrides,
+        })) {
+            yield { kind: 'chunk', chunk };
+        }
+    }
+}
+exports.AgentService = AgentService;
+/**
+ * Map a persisted `AgentRecord` to the runtime `AgentDefinition` the runner
+ * expects. The `context` column (plain-text knowledge) is prepended to the
+ * system prompt — the cheapest path before RAG is implemented.
+ */
+function toAgentDefinition(record) {
+    const systemPrompt = record.context
+        ? `${record.systemPrompt}\n\n--- Knowledge ---\n${record.context}`
+        : record.systemPrompt;
+    return {
+        id: record.id,
+        name: record.name,
+        description: record.description,
+        model: record.model,
+        systemPrompt,
+        maxTokens: record.maxTokens,
+        temperature: record.temperature,
+        topP: record.topP,
+        tools: record.tools,
+        mcpServers: record.mcpServers,
+        metadata: record.metadata,
+    };
+}

package/dist/services/api-key.service.d.ts

@@ -0,0 +1,41 @@
+import type { ApiKeyRepository } from '../repositories';
+import type { ApiKey } from '../domain/api-key';
+export interface MintedApiKey {
+    /** Plaintext key. Only available at creation time — never persisted. */
+    key: string;
+    entity: ApiKey;
+}
+/** Operational errors. Adapters map `.status` to an HTTP code. */
+export declare class ApiKeyError extends Error {
+    status: number;
+    code: 'invalid' | 'revoked' | 'expired';
+    constructor(code: 'invalid' | 'revoked' | 'expired', message: string);
+}
+export declare class ApiKeyService {
+    private readonly repo;
+    constructor(repo: ApiKeyRepository);
+    /** Mint a new API key for a tenant. Returns the plaintext key (one-time).
+     *  Pass `agentId` to scope the key to a specific agent in the tenant —
+     *  calls with that key only resolve when the requested agent matches. */
+    issue(input: {
+        tenantId: string;
+        agentId?: string;
+        name: string;
+        scopes?: string[];
+        expiresAt?: Date;
+    }): Promise<MintedApiKey>;
+    /**
+     * Validate a presented key. Returns the matching ApiKey row (without
+     * touching the plaintext) or throws ApiKeyError. Updates lastUsedAt as a
+     * best-effort side-effect (never blocks on the write).
+     */
+    validate(rawKey: string): Promise<ApiKey>;
+    listForTenant(tenantId: string): Promise<ApiKey[]>;
+    listForAgent(tenantId: string, agentId: string): Promise<ApiKey[]>;
+    revoke(id: string): Promise<void>;
+    /** Tells callers (HTTP middleware) whether a header value looks like an API key. */
+    static isApiKeyToken(token: string | undefined | null): boolean;
+    private hash;
+}
+/** Convenience for `randomUUID` access from external callers. */
+export declare const newApiKeyId: () => `${string}-${string}-${string}-${string}-${string}`;

package/dist/services/api-key.service.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.newApiKeyId = exports.ApiKeyService = exports.ApiKeyError = void 0;
+const crypto_1 = require("crypto");
+const API_KEY_PREFIX_LIVE = 'ak_live_';
+/** Operational errors. Adapters map `.status` to an HTTP code. */
+class ApiKeyError extends Error {
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.status = 401;
+    }
+}
+exports.ApiKeyError = ApiKeyError;
+class ApiKeyService {
+    constructor(repo) {
+        this.repo = repo;
+    }
+    /** Mint a new API key for a tenant. Returns the plaintext key (one-time).
+     *  Pass `agentId` to scope the key to a specific agent in the tenant —
+     *  calls with that key only resolve when the requested agent matches. */
+    async issue(input) {
+        const random = (0, crypto_1.randomBytes)(24).toString('hex'); // 192-bit
+        const key = `${API_KEY_PREFIX_LIVE}${random}`;
+        const keyHash = this.hash(key);
+        const keyPrefix = key.slice(0, 16); // "ak_live_a1b2c3d4"
+        const entity = await this.repo.create({
+            tenantId: input.tenantId,
+            agentId: input.agentId,
+            name: input.name,
+            keyHash,
+            keyPrefix,
+            scopes: input.scopes,
+            expiresAt: input.expiresAt,
+        });
+        return { key, entity };
+    }
+    /**
+     * Validate a presented key. Returns the matching ApiKey row (without
+     * touching the plaintext) or throws ApiKeyError. Updates lastUsedAt as a
+     * best-effort side-effect (never blocks on the write).
+     */
+    async validate(rawKey) {
+        if (!rawKey?.startsWith(API_KEY_PREFIX_LIVE)) {
+            throw new ApiKeyError('invalid', 'Invalid API key');
+        }
+        const keyHash = this.hash(rawKey);
+        const apiKey = await this.repo.findByHash(keyHash);
+        if (!apiKey)
+            throw new ApiKeyError('invalid', 'Invalid API key');
+        if (apiKey.revokedAt)
+            throw new ApiKeyError('revoked', 'API key has been revoked');
+        if (apiKey.expiresAt && apiKey.expiresAt <= new Date()) {
+            throw new ApiKeyError('expired', 'API key has expired');
+        }
+        // Best-effort lastUsedAt update — fire and forget.
+        this.repo.update(apiKey.id, { lastUsedAt: new Date() }).catch(() => { });
+        return apiKey;
+    }
+    async listForTenant(tenantId) {
+        return this.repo.listByTenant(tenantId);
+    }
+    async listForAgent(tenantId, agentId) {
+        return this.repo.listByAgent(tenantId, agentId);
+    }
+    async revoke(id) {
+        await this.repo.update(id, { revokedAt: new Date() });
+    }
+    /** Tells callers (HTTP middleware) whether a header value looks like an API key. */
+    static isApiKeyToken(token) {
+        return !!token && token.startsWith(API_KEY_PREFIX_LIVE);
+    }
+    hash(raw) {
+        return (0, crypto_1.createHash)('sha256').update(raw).digest('hex');
+    }
+}
+exports.ApiKeyService = ApiKeyService;
+/** Convenience for `randomUUID` access from external callers. */
+const newApiKeyId = () => (0, crypto_1.randomUUID)();
+exports.newApiKeyId = newApiKeyId;

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

@@ -0,0 +1,133 @@
+import type { UserRepository, UserListOptions, UserListResult, AuthIdentityRepository, EmailTokenRepository } from '../repositories';
+import type { User } from '../domain/user';
+import type { RefreshTokenService } from './refresh-token.service';
+import type { EmailService } from './email.service';
+import type { Logger } from './tool-registry.service';
+export interface AuthUser {
+    userId: string;
+    email?: string;
+    name?: string;
+    /** RBAC role from the `af_users.role` column. */
+    role?: 'user' | 'platform_admin';
+    /** Convenience boolean derived from `role === 'platform_admin'`. */
+    isPlatformAdmin?: boolean;
+}
+export interface AuthResult {
+    accessToken: string;
+    refreshToken: string;
+    user: {
+        id: string;
+        email?: string;
+        name?: string;
+    };
+}
+export interface SessionMeta {
+    userAgent?: string;
+    ip?: string;
+}
+export interface AuthServiceOptions {
+    jwtSecret: string;
+    /** Access-token TTL — string accepted by jsonwebtoken (e.g. '15m'). Default: '15m'. */
+    accessTokenTtl?: string;
+    /** Lock account after N consecutive failed logins. Default: 5. */
+    lockoutThreshold?: number;
+    /** Lockout duration in minutes. Default: 15. */
+    lockoutMinutes?: number;
+    /** When true, login is blocked until the user has clicked the verify link. Default: false. */
+    requireEmailVerification?: boolean;
+    /** Default plan id assigned at registration. */
+    defaultPlanId?: string;
+    /** Initial credit balance for newly-registered users. */
+    initialCredits?: number;
+    /** Verify-email token TTL in hours. Default: 24. */
+    verifyTokenTtlHours?: number;
+    /** Password-reset token TTL in minutes. Default: 60. */
+    resetTokenTtlMinutes?: number;
+    /** Hook fired after a user is created via any strategy. */
+    onUserCreated?: (user: {
+        id: string;
+        email?: string;
+        name?: string;
+    }) => void | Promise<void>;
+    logger?: Logger;
+}
+export declare class AuthService {
+    private readonly users;
+    private readonly identities;
+    private readonly emailTokens;
+    private readonly refreshTokens;
+    private readonly email;
+    private readonly opts;
+    private readonly logger;
+    constructor(users: UserRepository, identities: AuthIdentityRepository, emailTokens: EmailTokenRepository, refreshTokens: RefreshTokenService, email: EmailService, opts: AuthServiceOptions);
+    register(params: {
+        email: string;
+        password: string;
+        name?: string;
+    }, meta?: SessionMeta): Promise<AuthResult>;
+    validateCredentials(email: string, password: string): Promise<User>;
+    login(email: string, password: string, meta?: SessionMeta): Promise<AuthResult>;
+    refresh(rawToken: string, meta?: SessionMeta): Promise<AuthResult>;
+    logout(rawRefreshToken?: string): Promise<void>;
+    logoutEverywhere(userId: string): Promise<void>;
+    signInWithProvider(profile: {
+        provider: string;
+        providerId: string;
+        email?: string;
+        emailVerified?: boolean;
+        name?: string;
+        metadata?: Record<string, unknown>;
+    }, meta?: SessionMeta): Promise<AuthResult>;
+    sendVerificationEmail(user: User): Promise<void>;
+    resendVerificationEmail(userId: string): Promise<void>;
+    verifyEmail(rawToken: string): Promise<{
+        userId: string;
+    }>;
+    /** Always returns success — never reveals whether the email exists. */
+    requestPasswordReset(email: string): Promise<void>;
+    resetPassword(rawToken: string, newPassword: string): Promise<void>;
+    /**
+     * Verify a JWT and return the resolved user. Returns null if the token is
+     * invalid/expired or the user no longer exists / is disabled.
+     */
+    /**
+     * Resolve a user from their id. Used by adapter-level JWT strategies that
+     * receive the decoded token payload from passport-jwt and need to populate
+     * `req.user`.
+     */
+    getById(userId: string): Promise<AuthUser | null>;
+    verifyAccessToken(rawToken: string): Promise<AuthUser | null>;
+    private toAuthUser;
+    /**
+     * Update a user's role. Caller is responsible for authorization; this
+     * method only enforces invariants:
+     *   - Demoting a platform_admin is blocked if it would leave zero platform
+     *     admins, to prevent locking yourself out of admin operations.
+     */
+    setUserRole(userId: string, role: User['role']): Promise<User>;
+    listUsers(opts?: UserListOptions): Promise<UserListResult>;
+    /**
+     * Look up a user by id and return the full `User` row (role, plan, last
+     * login, etc.) — distinct from `getById` which returns the lightweight
+     * `AuthUser` projection used in request contexts. Used by admin detail
+     * pages. Returns null when not found.
+     */
+    getFullUserById(userId: string): Promise<User | null>;
+    /**
+     * Boot-time backfill for instances upgrading to RBAC. If no user holds the
+     * `platform_admin` role, the oldest user is promoted so the operator isn't
+     * locked out. Idempotent — no-op when at least one admin already exists.
+     *
+     * Call once from your server bootstrap after the DB is connected.
+     */
+    ensurePlatformAdminBootstrap(): Promise<void>;
+    issueSession(user: User, meta?: SessionMeta): Promise<AuthResult>;
+    private signAccess;
+    private recordFailedLogin;
+    private recordSuccessfulLogin;
+    private mintEmailToken;
+    private consumeEmailToken;
+    private hashToken;
+    cleanupExpiredEmailTokens(olderThan?: Date): Promise<number>;
+    private runCreatedHook;
+}