@agentforge-io/core 0.2.0

package/dist/services/tenant.service.js

@@ -0,0 +1,96 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TenantService = exports.TenantError = void 0;
+const crypto_1 = require("crypto");
+class TenantError extends Error {
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.status = code === 'forbidden' ? 403 : 404;
+    }
+}
+exports.TenantError = TenantError;
+class TenantService {
+    constructor(tenants, externalUsers, users) {
+        this.tenants = tenants;
+        this.externalUsers = externalUsers;
+        this.users = users;
+    }
+    // ─── Tenant CRUD (admin) ─────────────────────────────────────────────────
+    async create(input) {
+        const tenant = await this.tenants.create({
+            id: (0, crypto_1.randomUUID)(),
+            name: input.name,
+            ownerUserId: input.ownerUserId,
+            planId: input.planId ?? 'free',
+            isActive: true,
+        });
+        return tenant;
+    }
+    async findById(id) {
+        return this.tenants.findById(id);
+    }
+    async listForOwner(ownerUserId, opts = {}) {
+        return this.tenants.listForOwner(ownerUserId, opts);
+    }
+    /**
+     * List every tenant in the system. Controllers MUST gate this behind a
+     * platform-admin check before calling — the service intentionally doesn't,
+     * so it stays usable from contexts that have already authorized the call.
+     */
+    async listAll(opts = {}) {
+        return this.tenants.listAll(opts);
+    }
+    /**
+     * Throws if the user isn't the owner. Used by admin endpoints.
+     *
+     * Pass `allowAnyOwner: true` to skip the owner check — controllers should
+     * set this when the caller is a platform admin, so super-admins can manage
+     * any tenant. The not-found path still fires when the tenantId is bogus.
+     */
+    async assertOwner(tenantId, userId, opts = {}) {
+        const tenant = await this.tenants.findById(tenantId);
+        if (!tenant)
+            throw new TenantError('not_found', 'Tenant not found');
+        if (!opts.allowAnyOwner && tenant.ownerUserId !== userId) {
+            // Don't reveal existence — return not_found rather than forbidden.
+            throw new TenantError('not_found', 'Tenant not found');
+        }
+        return tenant;
+    }
+    // ─── External user mapping (B2B request path) ────────────────────────────
+    /**
+     * Look up (tenantId, externalId) → internal User. Creates the linkage on
+     * first use. Also creates a placeholder User row so the rest of the system
+     * (conversations, usage, billing) can reference it.
+     */
+    async ensureExternalUser(input) {
+        const existing = await this.externalUsers.findByExternalId(input.tenantId, input.externalId);
+        if (existing)
+            return existing;
+        const internalId = (0, crypto_1.randomUUID)();
+        // Create a User row so conversations/messages/usage can FK to it. The
+        // user is "owned" by the tenant — we store metadata for traceability.
+        await this.users.create({
+            id: internalId,
+            email: input.email,
+            name: input.name,
+            authProvider: `tenant:${input.tenantId}`,
+            currentPlanId: 'free',
+            creditsBalance: 0,
+            isActive: true,
+            failedLoginCount: 0,
+            metadata: {
+                tenantId: input.tenantId,
+                externalId: input.externalId,
+            },
+        });
+        return this.externalUsers.create({
+            id: internalId,
+            tenantId: input.tenantId,
+            externalId: input.externalId,
+            email: input.email,
+        });
+    }
+}
+exports.TenantService = TenantService;

package/dist/services/tool-registry.service.d.ts

@@ -0,0 +1,42 @@
+import type { AgentToolDefinition, AnthropicTool, ToolExecutionContext } from '../types/agent.types';
+export interface Logger {
+    log: (msg: string) => void;
+    warn: (msg: string) => void;
+    debug: (msg: string) => void;
+    error: (msg: string) => void;
+}
+/**
+ * Framework-free tool registry. Holds the catalog of tools an agent can call
+ * and exposes them in Anthropic's tool-schema shape. @agentforge-io/nest wraps
+ * a single instance of this class.
+ */
+export declare class ToolRegistryService {
+    private readonly tools;
+    private readonly logger;
+    constructor(opts?: {
+        logger?: Logger;
+        initialTools?: AgentToolDefinition[];
+    });
+    register(tool: AgentToolDefinition): void;
+    registerMany(tools: AgentToolDefinition[]): void;
+    /** Remove a tool from the registry. Returns true when something was
+     *  actually removed — false when the name was unknown. Used by
+     *  McpClientService to clean up tools when an MCP server is unregistered. */
+    unregister(name: string): boolean;
+    getToolsForAgent(agentId: string, toolNames: string[]): AnthropicTool[];
+    execute(toolName: string, input: Record<string, unknown>, context: ToolExecutionContext): Promise<string>;
+    has(name: string): boolean;
+    list(): string[];
+    /**
+     * Public catalog suitable for a "/tools" discovery endpoint. Excludes the
+     * `execute` function (not serializable) and surfaces the per-tool agent
+     * allowlist so a UI can show "this tool is only usable by agent X".
+     */
+    describe(): ToolDescription[];
+}
+export interface ToolDescription {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    agents?: string[];
+}

package/dist/services/tool-registry.service.js

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ToolRegistryService = void 0;
+const noopLogger = {
+    log: () => { },
+    warn: () => { },
+    debug: () => { },
+    error: () => { },
+};
+/**
+ * Framework-free tool registry. Holds the catalog of tools an agent can call
+ * and exposes them in Anthropic's tool-schema shape. @agentforge-io/nest wraps
+ * a single instance of this class.
+ */
+class ToolRegistryService {
+    constructor(opts = {}) {
+        this.tools = new Map();
+        this.logger = opts.logger ?? noopLogger;
+        if (opts.initialTools)
+            this.registerMany(opts.initialTools);
+    }
+    register(tool) {
+        if (this.tools.has(tool.name)) {
+            this.logger.warn(`Tool "${tool.name}" is already registered — overwriting`);
+        }
+        this.tools.set(tool.name, tool);
+        this.logger.debug(`Registered tool: ${tool.name}`);
+    }
+    registerMany(tools) {
+        tools.forEach((t) => this.register(t));
+    }
+    /** Remove a tool from the registry. Returns true when something was
+     *  actually removed — false when the name was unknown. Used by
+     *  McpClientService to clean up tools when an MCP server is unregistered. */
+    unregister(name) {
+        const existed = this.tools.delete(name);
+        if (existed)
+            this.logger.debug(`Unregistered tool: ${name}`);
+        return existed;
+    }
+    getToolsForAgent(agentId, toolNames) {
+        return toolNames
+            .filter((name) => {
+            const tool = this.tools.get(name);
+            if (!tool) {
+                this.logger.warn(`Tool "${name}" requested by agent "${agentId}" is not registered`);
+                return false;
+            }
+            if (tool.agents && tool.agents.length > 0 && !tool.agents.includes(agentId)) {
+                this.logger.warn(`Tool "${name}" is not allowed for agent "${agentId}"`);
+                return false;
+            }
+            return true;
+        })
+            .map((name) => {
+            const tool = this.tools.get(name);
+            return {
+                name: tool.name,
+                description: tool.description,
+                input_schema: tool.inputSchema,
+            };
+        });
+    }
+    async execute(toolName, input, context) {
+        const tool = this.tools.get(toolName);
+        if (!tool)
+            throw new Error(`Tool "${toolName}" not found in registry`);
+        const start = Date.now();
+        try {
+            this.logger.debug(`Executing tool "${toolName}" for user ${context.userId}`);
+            const result = await tool.execute(input, context);
+            this.logger.debug(`Tool "${toolName}" completed in ${Date.now() - start}ms`);
+            return result;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            this.logger.error(`Tool "${toolName}" failed: ${message}`);
+            throw error;
+        }
+    }
+    has(name) {
+        return this.tools.has(name);
+    }
+    list() {
+        return Array.from(this.tools.keys());
+    }
+    /**
+     * Public catalog suitable for a "/tools" discovery endpoint. Excludes the
+     * `execute` function (not serializable) and surfaces the per-tool agent
+     * allowlist so a UI can show "this tool is only usable by agent X".
+     */
+    describe() {
+        return Array.from(this.tools.values()).map((t) => ({
+            name: t.name,
+            description: t.description,
+            inputSchema: t.inputSchema,
+            agents: t.agents,
+        }));
+    }
+}
+exports.ToolRegistryService = ToolRegistryService;

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

@@ -0,0 +1,37 @@
+import type { SignedUploadTarget, UploadAdapter } from '../adapters/upload/upload-adapter.interface';
+export declare class UploadError extends Error {
+    status: number;
+    code: 'unsupported_type' | 'too_large' | 'invalid' | 'not_configured';
+    constructor(code: UploadError['code'], message: string);
+}
+export interface AvatarSignInput {
+    tenantId: string;
+    agentId: string;
+    contentType: string;
+    /** Declared size in bytes (best-effort — client computes from File.size).
+     *  We reject before signing if it exceeds the limit. */
+    contentLength?: number;
+}
+/**
+ * Thin application service over the UploadAdapter. Owns:
+ *   - MIME / size validation (so we don't sign URLs for forbidden uploads)
+ *   - Key construction (keeps adapter ignorant of domain conventions)
+ *   - Error shaping for the HTTP layer
+ *
+ * Adapter swapping (S3 → R2 → MinIO) doesn't ripple into the controller
+ * because everything HTTP-flavored happens here.
+ */
+export declare class UploadService {
+    private readonly adapter;
+    constructor(adapter: UploadAdapter);
+    /**
+     * Sign a PUT URL for an agent's avatar. Key shape:
+     *   agents/<tenantId>/<agentId>/avatar-<uuid>.<ext>
+     * The UUID makes a fresh upload not collide with the previous avatar —
+     * we keep the old object around (cleanup is a future improvement) so we
+     * don't 404 anyone who already had the old URL loaded.
+     */
+    signAgentAvatar(input: AvatarSignInput): Promise<SignedUploadTarget>;
+}
+export declare const ALLOWED_AVATAR_MIME_TYPES: string[];
+export declare const MAX_AVATAR_BYTES: number;

package/dist/services/upload.service.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_AVATAR_BYTES = exports.ALLOWED_AVATAR_MIME_TYPES = exports.UploadService = exports.UploadError = void 0;
+const crypto_1 = require("crypto");
+class UploadError extends Error {
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.status =
+            code === 'not_configured' ? 501 :
+                code === 'too_large' ? 413 :
+                    code === 'unsupported_type' ? 415 : 400;
+    }
+}
+exports.UploadError = UploadError;
+const IMAGE_MIME_WHITELIST = new Set([
+    'image/png',
+    'image/jpeg',
+    'image/webp',
+    'image/gif',
+]);
+const MIME_TO_EXT = {
+    'image/png': 'png',
+    'image/jpeg': 'jpg',
+    'image/webp': 'webp',
+    'image/gif': 'gif',
+};
+/** Max image upload size (bytes). Avatars are tiny; this catches an upload
+ *  the user thinks is a 1MB photo but is actually a 30MB original. */
+const MAX_IMAGE_BYTES = 2 * 1024 * 1024;
+/**
+ * Thin application service over the UploadAdapter. Owns:
+ *   - MIME / size validation (so we don't sign URLs for forbidden uploads)
+ *   - Key construction (keeps adapter ignorant of domain conventions)
+ *   - Error shaping for the HTTP layer
+ *
+ * Adapter swapping (S3 → R2 → MinIO) doesn't ripple into the controller
+ * because everything HTTP-flavored happens here.
+ */
+class UploadService {
+    constructor(adapter) {
+        this.adapter = adapter;
+    }
+    /**
+     * Sign a PUT URL for an agent's avatar. Key shape:
+     *   agents/<tenantId>/<agentId>/avatar-<uuid>.<ext>
+     * The UUID makes a fresh upload not collide with the previous avatar —
+     * we keep the old object around (cleanup is a future improvement) so we
+     * don't 404 anyone who already had the old URL loaded.
+     */
+    async signAgentAvatar(input) {
+        if (!input.tenantId || !input.agentId) {
+            throw new UploadError('invalid', 'tenantId and agentId are required');
+        }
+        const ct = input.contentType?.toLowerCase().trim();
+        if (!ct || !IMAGE_MIME_WHITELIST.has(ct)) {
+            throw new UploadError('unsupported_type', `Unsupported image type "${input.contentType}". Allowed: ${[...IMAGE_MIME_WHITELIST].join(', ')}.`);
+        }
+        if (input.contentLength !== undefined && input.contentLength > MAX_IMAGE_BYTES) {
+            throw new UploadError('too_large', `Avatar must be ${(MAX_IMAGE_BYTES / 1024 / 1024).toFixed(1)} MB or smaller.`);
+        }
+        const ext = MIME_TO_EXT[ct] ?? 'bin';
+        const key = `agents/${input.tenantId}/${input.agentId}/avatar-${(0, crypto_1.randomUUID)()}.${ext}`;
+        try {
+            return await this.adapter.signUpload({
+                key,
+                contentType: ct,
+                maxSizeBytes: MAX_IMAGE_BYTES,
+            });
+        }
+        catch (err) {
+            // NoopUploadAdapter throws this exact message — map it to a sensible
+            // 501 instead of leaking the adapter shape to the client.
+            const msg = err instanceof Error ? err.message : String(err);
+            if (msg.includes('Uploads are not configured')) {
+                throw new UploadError('not_configured', msg);
+            }
+            throw err;
+        }
+    }
+}
+exports.UploadService = UploadService;
+exports.ALLOWED_AVATAR_MIME_TYPES = [...IMAGE_MIME_WHITELIST];
+exports.MAX_AVATAR_BYTES = MAX_IMAGE_BYTES;

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

@@ -0,0 +1,34 @@
+import type { UserRepository, UsageRecordRepository } from '../repositories';
+import type { CreditsConfig, UsageLimits } from '../types/config.types';
+import type { PlanService } from './plan.service';
+import type { UsageSummary } from '../types/billing.types';
+import type { TokenUsage } from '../types/agent.types';
+export interface UsageServiceOptions {
+    plans: PlanService;
+    defaultLimits?: UsageLimits;
+    credits?: CreditsConfig;
+}
+export declare class UsageService {
+    private readonly users;
+    private readonly usage;
+    private readonly opts;
+    constructor(users: UserRepository, usage: UsageRecordRepository, opts: UsageServiceOptions);
+    record(params: {
+        userId: string;
+        conversationId: string;
+        messageId: string;
+        agentId: string;
+        usage: TokenUsage;
+    }): Promise<void>;
+    checkLimits(userId: string): Promise<{
+        allowed: boolean;
+        reason?: string;
+        usage: UsageSummary;
+    }>;
+    getSummary(userId: string): Promise<UsageSummary>;
+    /** Idempotent: create a user row if missing. Used by the agent flow. */
+    ensureUser(userId: string): Promise<void>;
+    private currentBillingPeriod;
+    private periodDates;
+    private getUserPlan;
+}

package/dist/services/usage.service.js

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UsageService = void 0;
+class UsageService {
+    constructor(users, usage, opts) {
+        this.users = users;
+        this.usage = usage;
+        this.opts = opts;
+    }
+    async record(params) {
+        const period = this.currentBillingPeriod();
+        const credits = this.opts.credits;
+        const creditsConsumed = credits
+            ? params.usage.totalTokens / credits.tokensPerCredit + (credits.creditsPerRequest ?? 0)
+            : undefined;
+        await this.usage.create({
+            userId: params.userId,
+            conversationId: params.conversationId,
+            messageId: params.messageId,
+            agentId: params.agentId,
+            inputTokens: params.usage.inputTokens,
+            outputTokens: params.usage.outputTokens,
+            totalTokens: params.usage.totalTokens,
+            requestCount: 1,
+            creditsConsumed,
+            billingPeriod: period,
+        });
+    }
+    async checkLimits(userId) {
+        const summary = await this.getSummary(userId);
+        if (summary.isOverLimit) {
+            const reasons = [];
+            const { requestsLimit, tokensLimit } = summary;
+            if (requestsLimit > 0 && summary.requestsUsed >= requestsLimit) {
+                reasons.push(`Monthly request limit reached (${requestsLimit} requests)`);
+            }
+            if (tokensLimit > 0 && summary.tokensUsed >= tokensLimit) {
+                reasons.push(`Monthly token limit reached (${tokensLimit} tokens)`);
+            }
+            return { allowed: false, reason: reasons.join('; '), usage: summary };
+        }
+        if (this.opts.credits) {
+            const user = await this.users.findById(userId);
+            if (user && user.creditsBalance <= 0) {
+                return { allowed: false, reason: 'Insufficient credits', usage: summary };
+            }
+        }
+        return { allowed: true, usage: summary };
+    }
+    async getSummary(userId) {
+        const period = this.currentBillingPeriod();
+        const plan = await this.getUserPlan(userId);
+        const limits = plan?.limits ?? this.opts.defaultLimits ?? {};
+        const summed = await this.usage.sumForPeriod(userId, period);
+        const requestsUsed = summed.requestCount;
+        const tokensUsed = summed.totalTokens;
+        const requestsLimit = limits.requestsPerMonth ?? -1;
+        const tokensLimit = limits.tokensPerMonth ?? -1;
+        const [periodStart, periodEnd] = this.periodDates(period);
+        return {
+            userId,
+            planId: plan?.id ?? 'free',
+            periodStart,
+            periodEnd,
+            requestsUsed,
+            tokensUsed,
+            requestsLimit,
+            tokensLimit,
+            percentUsed: {
+                requests: requestsLimit > 0 ? (requestsUsed / requestsLimit) * 100 : 0,
+                tokens: tokensLimit > 0 ? (tokensUsed / tokensLimit) * 100 : 0,
+            },
+            isOverLimit: (requestsLimit > 0 && requestsUsed >= requestsLimit) ||
+                (tokensLimit > 0 && tokensUsed >= tokensLimit),
+        };
+    }
+    /** Idempotent: create a user row if missing. Used by the agent flow. */
+    async ensureUser(userId) {
+        const existing = await this.users.findById(userId);
+        if (existing)
+            return;
+        const defaultPlanId = await this.opts.plans.getDefaultId();
+        await this.users.create({
+            id: userId,
+            currentPlanId: defaultPlanId,
+            creditsBalance: this.opts.credits?.initialCredits ?? 0,
+            isActive: true,
+            failedLoginCount: 0,
+        });
+    }
+    currentBillingPeriod() {
+        const now = new Date();
+        return `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, '0')}`;
+    }
+    periodDates(period) {
+        const [year, month] = period.split('-').map(Number);
+        const start = new Date(year, month - 1, 1);
+        const end = new Date(year, month, 0, 23, 59, 59);
+        return [start, end];
+    }
+    async getUserPlan(userId) {
+        const user = await this.users.findById(userId);
+        if (!user)
+            return undefined;
+        return this.opts.plans.getPlan(user.currentPlanId);
+    }
+}
+exports.UsageService = UsageService;

package/dist/types/agent.types.d.ts

@@ -0,0 +1,160 @@
+import type Anthropic from '@anthropic-ai/sdk';
+export type MessageRole = 'user' | 'assistant' | 'system';
+export type ConversationStatus = 'active' | 'completed' | 'error' | 'paused';
+export type JobStatus = 'pending' | 'processing' | 'completed' | 'failed' | 'cancelled';
+export interface CreateConversationOptions {
+    userId: string;
+    agentId: string;
+    title?: string;
+    metadata?: Record<string, unknown>;
+    /** Run conversation in background queue */
+    async?: boolean;
+}
+export interface SendMessageOptions {
+    conversationId: string;
+    userId: string;
+    content: string;
+    /** Attach files / images */
+    attachments?: MessageAttachment[];
+    /** Override agent config for this message */
+    overrides?: AgentOverrides;
+    /** Run in background queue */
+    async?: boolean;
+    /** Stream the response */
+    stream?: boolean;
+}
+export interface MessageAttachment {
+    type: 'image' | 'document' | 'text';
+    /** For images: base64 or URL */
+    data: string;
+    mediaType?: 'image/jpeg' | 'image/png' | 'image/gif' | 'image/webp' | 'application/pdf' | 'text/plain';
+    filename?: string;
+}
+export interface AgentOverrides {
+    model?: string;
+    temperature?: number;
+    maxTokens?: number;
+    systemPromptSuffix?: string;
+    /**
+     * Per-call tool injection. Used by `AgentService.streamMessage` to attach
+     * the requesting user's connector tools (Gmail, Drive, Calendar …) for
+     * this turn only — they are NOT registered on the global ToolRegistry so
+     * one user's auth never leaks to another's.
+     *
+     * Tools listed here are appended to `agent.tools[]` for this call and
+     * routed through a per-call map (the registry doesn't see them).
+     */
+    extraTools?: AgentToolDefinition[];
+}
+export interface AgentResponse {
+    messageId: string;
+    conversationId: string;
+    content: string;
+    role: 'assistant';
+    /** Tool calls made during this turn */
+    toolCalls?: ToolCallRecord[];
+    /** Subagent delegations made by orchestrator */
+    delegations?: SubAgentDelegation[];
+    usage: TokenUsage;
+    model: string;
+    stopReason: string;
+    createdAt: Date;
+}
+export interface TokenUsage {
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    cacheCreationInputTokens?: number;
+    cacheReadInputTokens?: number;
+}
+export interface ToolCallRecord {
+    toolName: string;
+    toolUseId: string;
+    input: Record<string, unknown>;
+    output?: string;
+    error?: string;
+    durationMs?: number;
+}
+export interface SubAgentDelegation {
+    subAgentId: string;
+    task: string;
+    result: string;
+    usage: TokenUsage;
+}
+export interface AgentToolDefinition {
+    name: string;
+    description: string;
+    /** JSON Schema for the input */
+    inputSchema: Record<string, unknown>;
+    /** The actual function to execute */
+    execute: (input: Record<string, unknown>, context: ToolExecutionContext) => Promise<string>;
+    /** Restrict to specific agents */
+    agents?: string[];
+}
+export interface ToolExecutionContext {
+    userId: string;
+    conversationId: string;
+    agentId: string;
+    messageId: string;
+}
+export type AnthropicMessage = Anthropic.MessageParam;
+export type AnthropicTool = Anthropic.Tool;
+export type AnthropicContentBlock = Anthropic.ContentBlock;
+export type StreamChunk = {
+    type: 'text_delta';
+    delta: string;
+} | {
+    type: 'tool_use_start';
+    toolName: string;
+    toolUseId: string;
+} | {
+    type: 'tool_result';
+    toolName: string;
+    result: string;
+} | {
+    type: 'delegation_start';
+    subAgentId: string;
+    task: string;
+} | {
+    type: 'delegation_result';
+    subAgentId: string;
+    result: string;
+} | {
+    type: 'usage';
+    usage: TokenUsage;
+} | {
+    type: 'done';
+    messageId: string;
+};
+export interface AgentJobPayload {
+    jobId: string;
+    userId: string;
+    conversationId: string;
+    messageId: string;
+    agentId: string;
+    messages: AnthropicMessage[];
+    overrides?: AgentOverrides;
+}
+export interface AgentJobResult {
+    jobId: string;
+    response: AgentResponse;
+    completedAt: Date;
+}
+export interface ConversationHistory {
+    conversationId: string;
+    agentId: string;
+    userId: string;
+    title?: string;
+    status: ConversationStatus;
+    messages: MessageRecord[];
+    createdAt: Date;
+    updatedAt: Date;
+}
+export interface MessageRecord {
+    id: string;
+    role: MessageRole;
+    content: string;
+    toolCalls?: ToolCallRecord[];
+    usage?: TokenUsage;
+    createdAt: Date;
+}

package/dist/types/agent.types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });