@agentforge-io/core 0.2.0

package/dist/types/billing.types.d.ts

@@ -0,0 +1,82 @@
+export type SubscriptionStatus = 'active' | 'trialing' | 'past_due' | 'canceled' | 'unpaid' | 'incomplete' | 'paused';
+export type PaymentStatus = 'succeeded' | 'failed' | 'pending' | 'refunded';
+export interface UserSubscription {
+    id: string;
+    userId: string;
+    planId: string;
+    status: SubscriptionStatus;
+    /** Provider-specific subscription ID (e.g., Stripe sub_xxx) */
+    providerSubscriptionId?: string;
+    /** Provider-specific customer ID (e.g., Stripe cus_xxx) */
+    providerCustomerId?: string;
+    currentPeriodStart: Date;
+    currentPeriodEnd: Date;
+    trialEnd?: Date;
+    cancelAtPeriodEnd: boolean;
+    createdAt: Date;
+    updatedAt: Date;
+}
+export interface UsageSummary {
+    userId: string;
+    planId: string;
+    periodStart: Date;
+    periodEnd: Date;
+    requestsUsed: number;
+    tokensUsed: number;
+    creditsUsed?: number;
+    requestsLimit: number;
+    tokensLimit: number;
+    creditsBalance?: number;
+    percentUsed: {
+        requests: number;
+        tokens: number;
+    };
+    isOverLimit: boolean;
+}
+export interface UsageRecord {
+    id: string;
+    userId: string;
+    conversationId: string;
+    messageId: string;
+    agentId: string;
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    requestCount: number;
+    creditsConsumed?: number;
+    costInCents?: number;
+    billingPeriod: string;
+    recordedAt: Date;
+}
+export interface CheckoutResult {
+    sessionId: string;
+    url: string;
+    planId: string;
+    userId: string;
+}
+export interface PortalResult {
+    url: string;
+}
+export interface BillingOverviewResult {
+    subscription: UserSubscription | null;
+    usage: UsageSummary;
+    plan: {
+        id: string;
+        name: string;
+        features: string[];
+        limits: {
+            requestsPerMonth: number;
+            tokensPerMonth: number;
+        };
+    };
+    invoiceHistory?: InvoiceRecord[];
+}
+export interface InvoiceRecord {
+    id: string;
+    amount: number;
+    currency: string;
+    status: string;
+    createdAt: Date;
+    pdfUrl?: string;
+    hostedUrl?: string;
+}

package/dist/types/billing.types.js

@@ -0,0 +1,3 @@
+"use strict";
+// ─── Billing Runtime Types ────────────────────────────────────────────────────
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/config.types.d.ts

@@ -0,0 +1,127 @@
+export interface AgentForgeConfig {
+    /** Anthropic API configuration */
+    anthropic: AnthropicConfig;
+    /** PostgreSQL database configuration */
+    database: DatabaseConfig;
+    /** Redis configuration for BullMQ queue */
+    redis?: RedisConfig;
+    /** Agent definitions */
+    agents: AgentDefinition[];
+    /** Queue configuration */
+    queue?: QueueConfig;
+}
+export interface AnthropicConfig {
+    apiKey: string;
+    /** Default model to use across all agents (can be overridden per agent) */
+    defaultModel?: string;
+    /** Default max tokens per response */
+    defaultMaxTokens?: number;
+    /** Base URL override (useful for proxies) */
+    baseURL?: string;
+}
+export interface DatabaseConfig {
+    url: string;
+    /** Run migrations on startup (default: true) */
+    autoMigrate?: boolean;
+    /** SSL configuration */
+    ssl?: boolean | {
+        rejectUnauthorized: boolean;
+    };
+    /** Connection pool size */
+    poolSize?: number;
+    /** Log SQL queries (default: false) */
+    logging?: boolean;
+}
+export interface RedisConfig {
+    /**
+     * Connection URL — `redis://[:password@]host:port[/db]` or `rediss://...`.
+     * Plain `host:port` is also accepted (we'll prepend `redis://`).
+     * If provided, takes precedence over the structured fields below.
+     */
+    url?: string;
+    host?: string;
+    port?: number;
+    password?: string;
+    db?: number;
+    tls?: boolean;
+}
+export interface QueueConfig {
+    /** Enable background job queue (requires Redis) */
+    enabled: boolean;
+    /** Max concurrent jobs per worker */
+    concurrency?: number;
+    /** Default job options */
+    defaultJobOptions?: {
+        attempts?: number;
+        backoff?: {
+            type: 'exponential' | 'fixed';
+            delay: number;
+        };
+        removeOnComplete?: boolean | number;
+        removeOnFail?: boolean | number;
+    };
+}
+export interface JwtConfig {
+    secret: string;
+    expiresIn?: string;
+}
+export interface AgentDefinition {
+    /** Unique identifier for the agent */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Agent description (shown to users) */
+    description?: string;
+    /** Claude model to use */
+    model?: string;
+    /** System prompt */
+    systemPrompt: string;
+    /** Max tokens per response */
+    maxTokens?: number;
+    /** Temperature (0-1) */
+    temperature?: number;
+    /** Top-p sampling */
+    topP?: number;
+    /** Tools available to this agent */
+    tools?: string[];
+    /** MCP servers this agent can connect to */
+    mcpServers?: McpServerConfig[];
+    /** Whether this agent can spawn subagents */
+    canOrchestrate?: boolean;
+    /** Subagents this orchestrator can delegate to */
+    subAgents?: string[];
+    /** Restrict to specific plans */
+    requiredPlan?: string[];
+    /** Custom metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Configuration for an MCP server the runtime should connect to.
+ *
+ * v1 supports remote MCP servers only (HTTP/SSE). Stdio transport is
+ * deliberately out of scope — it requires spawning a subprocess and managing
+ * its lifecycle, which is harder to deploy in serverless / container setups.
+ *
+ * The `name` is the human-friendly identifier the admin UI shows. It also
+ * prefixes every tool the server exposes (`<name>__<tool>`) so multiple MCPs
+ * can register tools with overlapping names without colliding in the
+ * ToolRegistry.
+ */
+export interface McpServerConfig {
+    /** Stable identifier — also used as a tool-name prefix. */
+    name: string;
+    /**
+     * Wire protocol. `http` = Streamable HTTP (current standard); `sse` =
+     * legacy Server-Sent Events transport, still common in older servers.
+     * Stdio not supported in v1.
+     */
+    transport: 'http' | 'sse';
+    /** Base URL of the MCP server (the `/mcp` or `/sse` endpoint). */
+    url: string;
+    /**
+     * Static headers attached to every outbound request — typically used for
+     * `Authorization: Bearer <token>` or vendor-specific API keys. Resolve
+     * secrets via the host's SecretsService before passing them here.
+     */
+    headers?: Record<string, string>;
+}

package/dist/types/config.types.js

@@ -0,0 +1,9 @@
+"use strict";
+// ─── AgentForge Configuration Types ──────────────────────────────────────────
+//
+// The runtime SDK's config carries only what the agent loop needs to run:
+// Anthropic credentials, DB connection, Redis (optional), the agent catalog,
+// and queue settings. Auth, billing, email, secrets — those live in the host
+// and are NEVER part of AgentForgeConfig. The host wires them through its
+// own modules (e.g. AuthModule reads ConfigService, AUTH_CONFIG token, etc.).
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/hooks.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Host-supplied hooks for observing SDK runtime events.
+ *
+ * The control plane (server/host) registers these to react to what the
+ * AI runtime does — record usage, append audit logs, push to analytics.
+ *
+ * Failures inside a hook are logged and swallowed; they do NOT interrupt
+ * the agent. The SDK is a runtime, not a guard.
+ *
+ * Phase 1: observation only. No abort, no payload mutation.
+ */
+export interface SdkHooks {
+    /**
+     * Fired once per agent turn (user message → final agent reply) with
+     * the aggregated token usage of that turn. Multiple internal LLM
+     * calls inside one turn are summed before dispatch.
+     *
+     * Typical host handler: persist a UsageRecord, kick off async
+     * rate-limit checks, emit to analytics.
+     */
+    onUsage?: (event: UsageEvent) => Promise<void>;
+    /**
+     * Fired when an agent turn completes — successfully, with an error,
+     * or aborted (e.g. client SSE disconnect). Useful for audit trails,
+     * latency metrics, "last activity" stamping.
+     */
+    onTurnComplete?: (event: TurnCompleteEvent) => Promise<void>;
+    /**
+     * Fired once per tool invocation by an agent. Sub-agent delegations
+     * are surfaced as nested `onTurnComplete` events, not as tool calls.
+     */
+    onToolCall?: (event: ToolCallEvent) => Promise<void>;
+}
+/** Payload for `onUsage`. */
+export interface UsageEvent {
+    version: 1;
+    /** Stable id for this turn (1:1 with an agent reply). */
+    turnId: string;
+    conversationId: string;
+    /** Agent slug or uuid. */
+    agentId: string;
+    /** If the host is multi-tenant, the tenant that owns the turn. */
+    tenantId?: string;
+    /** End-user that triggered the turn (host-internal). */
+    userId?: string;
+    provider: 'anthropic' | 'openai' | 'google' | 'other';
+    modelId: string;
+    /** Sum across all LLM calls inside the turn. */
+    inputTokens: number;
+    outputTokens: number;
+    /** Wall-clock duration of the turn in ms. */
+    durationMs: number;
+    /** Server-side timestamp when the turn ended. */
+    at: Date;
+}
+/** Payload for `onTurnComplete`. */
+export interface TurnCompleteEvent {
+    version: 1;
+    turnId: string;
+    conversationId: string;
+    agentId: string;
+    tenantId?: string;
+    userId?: string;
+    status: 'ok' | 'error' | 'aborted';
+    errorMessage?: string;
+    /** Count of tool calls executed during this turn (0..N). */
+    toolCallCount: number;
+    durationMs: number;
+    at: Date;
+}
+/** Payload for `onToolCall`. */
+export interface ToolCallEvent {
+    version: 1;
+    turnId: string;
+    conversationId: string;
+    agentId: string;
+    tenantId?: string;
+    toolName: string;
+    /** Raw args the tool was invoked with — useful for debugging/audit. */
+    args: Record<string, unknown>;
+    /** Set when the tool execution threw. */
+    error?: string;
+    durationMs: number;
+    at: Date;
+}

package/dist/types/hooks.js

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

package/dist/types/index.d.ts

@@ -0,0 +1,3 @@
+export * from './agent.types';
+export * from './config.types';
+export * from './hooks';

package/dist/types/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./agent.types"), exports);
+__exportStar(require("./config.types"), exports);
+__exportStar(require("./hooks"), exports);

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@agentforge-io/core",
+  "version": "0.2.0",
+  "description": "Framework-free AI runtime SDK. Owns: agent loop (Anthropic), conversations, tools, streaming, agent-job queue, SdkHooks. Identity, billing, infra (email/uploads/secrets) live in the host's modules — not here.",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./ai": {
+      "types": "./dist/ai/index.d.ts",
+      "default": "./dist/ai/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "build:watch": "tsc -p tsconfig.build.json --watch",
+    "clean": "rm -rf dist *.tgz",
+    "test": "node --test --import tsx --test-reporter=spec tests/*.test.ts"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.32.0",
+    "@modelcontextprotocol/sdk": "^1.29.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.0.0"
+  }
+}