@agentforge-io/core 0.2.0

package/dist/adapters/billing/billing-adapter.interface.d.ts

@@ -0,0 +1,41 @@
+import type { CheckoutSession, CreateCheckoutParams, CreateCustomerParams, CreateSubscriptionParams, SubscriptionResult, WebhookEvent } from '../../types';
+/**
+ * IBillingAdapter defines the contract for payment providers.
+ * Implement this interface to support any payment gateway (Stripe, Paddle, LemonSqueezy, etc.)
+ */
+export interface IBillingAdapter {
+    /**
+     * Create a Stripe Checkout (or equivalent) session for a subscription or one-time payment.
+     */
+    createCheckoutSession(params: CreateCheckoutParams): Promise<CheckoutSession>;
+    /**
+     * Programmatically create a subscription (without hosted checkout).
+     */
+    createSubscription(params: CreateSubscriptionParams): Promise<SubscriptionResult>;
+    /**
+     * Cancel a subscription (optionally at period end).
+     */
+    cancelSubscription(subscriptionId: string, atPeriodEnd?: boolean): Promise<void>;
+    /**
+     * Handle an incoming webhook from the payment provider.
+     * Returns a normalized WebhookEvent.
+     */
+    handleWebhook(payload: Buffer, signature: string): Promise<WebhookEvent>;
+    /**
+     * Generate a customer portal URL where users can manage their subscription.
+     */
+    getPortalUrl(customerId: string, returnUrl: string): Promise<string>;
+    /**
+     * Create a customer record in the payment provider.
+     * Returns the provider-specific customer ID.
+     */
+    createCustomer(params: CreateCustomerParams): Promise<string>;
+    /**
+     * Get the current subscription status from the provider.
+     */
+    getSubscription(subscriptionId: string): Promise<SubscriptionResult & {
+        status: string;
+    }>;
+}
+/** Token to inject the billing adapter via NestJS DI */
+export declare const BILLING_ADAPTER = "BILLING_ADAPTER";

package/dist/adapters/billing/billing-adapter.interface.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BILLING_ADAPTER = void 0;
+/** Token to inject the billing adapter via NestJS DI */
+exports.BILLING_ADAPTER = 'BILLING_ADAPTER';

package/dist/adapters/billing/stripe/stripe.adapter.d.ts

@@ -0,0 +1,30 @@
+import Stripe from 'stripe';
+import type { IBillingAdapter } from '../billing-adapter.interface';
+import type { CheckoutSession, CreateCheckoutParams, CreateCustomerParams, CreateSubscriptionParams, PlanDefinition, StripeConfig, SubscriptionResult, WebhookEvent } from '../../../types';
+interface MiniLogger {
+    debug?: (m: string) => void;
+    warn?: (m: string) => void;
+    log?: (m: string) => void;
+}
+/**
+ * StripeAdapter implements IBillingAdapter using the Stripe API.
+ * Handles subscriptions, pay-per-use checkouts, webhooks, and customer portal.
+ */
+export declare class StripeAdapter implements IBillingAdapter {
+    private readonly logger;
+    private readonly stripe;
+    private readonly plans;
+    private readonly webhookSecret;
+    constructor(config: StripeConfig, plans?: PlanDefinition[], logger?: MiniLogger);
+    createCustomer(params: CreateCustomerParams): Promise<string>;
+    createCheckoutSession(params: CreateCheckoutParams): Promise<CheckoutSession>;
+    createSubscription(params: CreateSubscriptionParams): Promise<SubscriptionResult>;
+    cancelSubscription(subscriptionId: string, atPeriodEnd?: boolean): Promise<void>;
+    getSubscription(subscriptionId: string): Promise<SubscriptionResult & {
+        status: string;
+    }>;
+    getPortalUrl(customerId: string, returnUrl: string): Promise<string>;
+    handleWebhook(payload: Buffer, signature: string): Promise<WebhookEvent>;
+    getStripeInstance(): Stripe;
+}
+export {};

package/dist/adapters/billing/stripe/stripe.adapter.js

@@ -0,0 +1,122 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StripeAdapter = void 0;
+const stripe_1 = __importDefault(require("stripe"));
+/**
+ * StripeAdapter implements IBillingAdapter using the Stripe API.
+ * Handles subscriptions, pay-per-use checkouts, webhooks, and customer portal.
+ */
+class StripeAdapter {
+    constructor(config, plans = [], logger) {
+        this.logger = logger ?? {};
+        this.stripe = new stripe_1.default(config.secretKey, {
+            apiVersion: '2023-10-16',
+        });
+        this.plans = plans;
+        this.webhookSecret = config.webhookSecret;
+    }
+    // ─── Customer ─────────────────────────────────────────────────────────────
+    async createCustomer(params) {
+        const customer = await this.stripe.customers.create({
+            email: params.email,
+            name: params.name,
+            metadata: params.metadata ?? {},
+        });
+        this.logger.debug?.(`Created Stripe customer: ${customer.id}`);
+        return customer.id;
+    }
+    // ─── Checkout ─────────────────────────────────────────────────────────────
+    async createCheckoutSession(params) {
+        // Prefer the caller-provided stripePriceId (DB-backed plans flow).
+        // Fall back to looking it up in the static plan list passed to the
+        // constructor (legacy / single-tenant flow).
+        const fallbackPlan = this.plans.find((p) => p.id === params.planId);
+        const stripePriceId = params.stripePriceId ?? fallbackPlan?.stripePriceId;
+        const interval = fallbackPlan?.interval ?? 'month';
+        if (!stripePriceId) {
+            throw new Error(`Plan "${params.planId}" has no Stripe price ID configured`);
+        }
+        const session = await this.stripe.checkout.sessions.create({
+            mode: interval ? 'subscription' : 'payment',
+            payment_method_types: ['card'],
+            line_items: [{ price: stripePriceId, quantity: 1 }],
+            success_url: params.successUrl,
+            cancel_url: params.cancelUrl,
+            metadata: {
+                userId: params.userId,
+                planId: params.planId,
+                ...params.metadata,
+            },
+            subscription_data: interval
+                ? { metadata: { userId: params.userId, planId: params.planId } }
+                : undefined,
+        });
+        return { sessionId: session.id, url: session.url };
+    }
+    // ─── Subscription ─────────────────────────────────────────────────────────
+    async createSubscription(params) {
+        const subscription = await this.stripe.subscriptions.create({
+            customer: params.customerId,
+            items: [{ price: params.priceId }],
+            trial_period_days: params.trialDays,
+            payment_behavior: 'default_incomplete',
+            expand: ['latest_invoice.payment_intent'],
+        });
+        return {
+            subscriptionId: subscription.id,
+            status: subscription.status,
+            currentPeriodEnd: new Date(subscription.current_period_end * 1000),
+        };
+    }
+    async cancelSubscription(subscriptionId, atPeriodEnd = true) {
+        if (atPeriodEnd) {
+            await this.stripe.subscriptions.update(subscriptionId, {
+                cancel_at_period_end: true,
+            });
+        }
+        else {
+            await this.stripe.subscriptions.cancel(subscriptionId);
+        }
+        this.logger.log?.(`Subscription ${subscriptionId} cancelled (atPeriodEnd=${atPeriodEnd})`);
+    }
+    async getSubscription(subscriptionId) {
+        const sub = await this.stripe.subscriptions.retrieve(subscriptionId);
+        return {
+            subscriptionId: sub.id,
+            status: sub.status,
+            currentPeriodEnd: new Date(sub.current_period_end * 1000),
+        };
+    }
+    // ─── Customer Portal ──────────────────────────────────────────────────────
+    async getPortalUrl(customerId, returnUrl) {
+        const session = await this.stripe.billingPortal.sessions.create({
+            customer: customerId,
+            return_url: returnUrl,
+        });
+        return session.url;
+    }
+    // ─── Webhooks ─────────────────────────────────────────────────────────────
+    async handleWebhook(payload, signature) {
+        let event;
+        try {
+            event = this.stripe.webhooks.constructEvent(payload, signature, this.webhookSecret);
+        }
+        catch (err) {
+            throw new Error(`Stripe webhook verification failed: ${err}`);
+        }
+        this.logger.debug?.(`Stripe webhook received: ${event.type}`);
+        // Normalize to a generic WebhookEvent
+        return {
+            type: event.type,
+            data: event.data.object,
+        };
+    }
+    // ─── Helpers ──────────────────────────────────────────────────────────────
+    getStripeInstance() {
+        return this.stripe;
+    }
+}
+exports.StripeAdapter = StripeAdapter;

package/dist/adapters/email/email-adapter.interface.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Transport-agnostic contract for sending email.
+ *
+ * Default implementation is Resend. Plug in SES/SendGrid/SMTP/Mailgun/etc.
+ * via `auth.email.provider = 'custom'` + `customAdapter` in config, or by
+ * overriding the EMAIL_ADAPTER provider in the consuming app's module.
+ */
+export interface EmailAdapter {
+    send(message: EmailMessage): Promise<EmailSendResult>;
+}
+export interface EmailMessage {
+    to: string;
+    subject: string;
+    html?: string;
+    text?: string;
+    /** Override the default `from` for this single send. */
+    from?: string;
+    /** Tags / metadata for analytics — adapter may ignore. */
+    tags?: Record<string, string>;
+}
+export interface EmailSendResult {
+    /** Provider's message id, when available. */
+    id?: string;
+}
+export declare const EMAIL_ADAPTER = "AGENTFORGE_EMAIL_ADAPTER";

package/dist/adapters/email/email-adapter.interface.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EMAIL_ADAPTER = void 0;
+// String token (not Symbol) so it survives duplicate package instances and
+// works as a NestJS string-based DI provider out of the box.
+exports.EMAIL_ADAPTER = 'AGENTFORGE_EMAIL_ADAPTER';

package/dist/adapters/email/noop.adapter.d.ts

@@ -0,0 +1,10 @@
+import type { EmailAdapter, EmailMessage, EmailSendResult } from './email-adapter.interface';
+/**
+ * Used when no email config is provided. Throws on send so callers (verify,
+ * password-reset) fail loudly instead of silently dropping. AuthService wraps
+ * the call in try/catch where appropriate (e.g. password-reset to preserve
+ * the always-200 anti-enumeration guarantee).
+ */
+export declare class NoopEmailAdapter implements EmailAdapter {
+    send(_message: EmailMessage): Promise<EmailSendResult>;
+}

package/dist/adapters/email/noop.adapter.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NoopEmailAdapter = void 0;
+/**
+ * Used when no email config is provided. Throws on send so callers (verify,
+ * password-reset) fail loudly instead of silently dropping. AuthService wraps
+ * the call in try/catch where appropriate (e.g. password-reset to preserve
+ * the always-200 anti-enumeration guarantee).
+ */
+class NoopEmailAdapter {
+    async send(_message) {
+        throw new Error('Email features are not configured. Pass an EmailAdapter (e.g. ResendAdapter) when creating AgentForge.');
+    }
+}
+exports.NoopEmailAdapter = NoopEmailAdapter;

package/dist/adapters/email/resend.adapter.d.ts

@@ -0,0 +1,8 @@
+import type { EmailAdapter, EmailMessage, EmailSendResult } from './email-adapter.interface';
+export declare class ResendAdapter implements EmailAdapter {
+    private readonly apiKey;
+    private readonly defaultFrom;
+    private readonly client;
+    constructor(apiKey: string, defaultFrom: string);
+    send(message: EmailMessage): Promise<EmailSendResult>;
+}

package/dist/adapters/email/resend.adapter.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ResendAdapter = void 0;
+const resend_1 = require("resend");
+class ResendAdapter {
+    constructor(apiKey, defaultFrom) {
+        this.apiKey = apiKey;
+        this.defaultFrom = defaultFrom;
+        if (!apiKey)
+            throw new Error('ResendAdapter: apiKey is required');
+        if (!defaultFrom) {
+            throw new Error('ResendAdapter: defaultFrom is required (e.g. "App <noreply@yourdomain.com>")');
+        }
+        this.client = new resend_1.Resend(apiKey);
+    }
+    async send(message) {
+        const payload = {
+            from: message.from ?? this.defaultFrom,
+            to: [message.to],
+            subject: message.subject,
+        };
+        if (message.html)
+            payload.html = message.html;
+        if (message.text)
+            payload.text = message.text;
+        if (message.tags) {
+            payload.tags = Object.entries(message.tags).map(([name, value]) => ({ name, value }));
+        }
+        if (!payload.html && !payload.text) {
+            throw new Error('ResendAdapter: html or text is required');
+        }
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const { data, error } = await this.client.emails.send(payload);
+        if (error)
+            throw new Error(`Resend: ${error.message}`);
+        return { id: data?.id };
+    }
+}
+exports.ResendAdapter = ResendAdapter;

package/dist/adapters/job-queue/in-memory.d.ts

@@ -0,0 +1,43 @@
+import type { EnqueueOptions, JobProcessor, JobQueue, JobStatus, QueueMetrics } from './job-queue.types';
+export interface InMemoryJobQueueOptions {
+    /** Max concurrent jobs. Default: 1 (sequential). */
+    concurrency?: number;
+    /** Default retry attempts on failure. Default: 3. */
+    defaultAttempts?: number;
+    /** Avg wait estimate per pending job in ms. Default: 5000. */
+    estimatedWaitPerJobMs?: number;
+}
+/**
+ * Process-local JobQueue. Holds jobs in a Map, drains them with a small
+ * scheduler (default concurrency=1, sequential). Pending jobs are lost on
+ * restart — use a persistent adapter (BullMQ etc.) for production.
+ *
+ * Designed to be a drop-in default so Express adapters can offer /jobs/*
+ * endpoints without forcing operators to stand up Redis.
+ */
+export declare class InMemoryJobQueue<P, R> implements JobQueue<P, R> {
+    private readonly processor;
+    private readonly jobs;
+    /** Insertion-order list of waiting jobIds; used to drain FIFO within a priority. */
+    private readonly waitingIds;
+    private readonly concurrency;
+    private readonly defaultAttempts;
+    private readonly estimatedWaitPerJobMs;
+    private activeCount;
+    /** Completed and failed counters, kept separately from `jobs` so the Map
+     *  can be pruned over time without losing aggregate metrics. */
+    private completedCount;
+    private failedCount;
+    constructor(processor: JobProcessor<P, R>, opts?: InMemoryJobQueueOptions);
+    enqueue(payload: P, opts?: EnqueueOptions): Promise<{
+        jobId: string;
+        estimatedWait: number;
+    }>;
+    getJobStatus(jobId: string): Promise<JobStatus<R>>;
+    cancelJob(jobId: string): Promise<boolean>;
+    getMetrics(): Promise<QueueMetrics>;
+    private insertByPriority;
+    private estimateWait;
+    private drain;
+    private run;
+}

package/dist/adapters/job-queue/in-memory.js

@@ -0,0 +1,154 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InMemoryJobQueue = void 0;
+const crypto_1 = require("crypto");
+/**
+ * Process-local JobQueue. Holds jobs in a Map, drains them with a small
+ * scheduler (default concurrency=1, sequential). Pending jobs are lost on
+ * restart — use a persistent adapter (BullMQ etc.) for production.
+ *
+ * Designed to be a drop-in default so Express adapters can offer /jobs/*
+ * endpoints without forcing operators to stand up Redis.
+ */
+class InMemoryJobQueue {
+    constructor(processor, opts = {}) {
+        this.processor = processor;
+        this.jobs = new Map();
+        /** Insertion-order list of waiting jobIds; used to drain FIFO within a priority. */
+        this.waitingIds = [];
+        this.activeCount = 0;
+        /** Completed and failed counters, kept separately from `jobs` so the Map
+         *  can be pruned over time without losing aggregate metrics. */
+        this.completedCount = 0;
+        this.failedCount = 0;
+        this.concurrency = Math.max(1, opts.concurrency ?? 1);
+        this.defaultAttempts = Math.max(1, opts.defaultAttempts ?? 3);
+        this.estimatedWaitPerJobMs = opts.estimatedWaitPerJobMs ?? 5000;
+    }
+    async enqueue(payload, opts = {}) {
+        const jobId = opts.jobId ?? (0, crypto_1.randomUUID)();
+        if (this.jobs.has(jobId)) {
+            // Idempotent: a re-enqueue of the same id returns the existing entry.
+            const existing = this.jobs.get(jobId);
+            return { jobId, estimatedWait: this.estimateWait(existing.priority) };
+        }
+        const attempts = Math.max(1, opts.attempts ?? this.defaultAttempts);
+        const job = {
+            jobId,
+            payload,
+            priority: opts.priority ?? 0,
+            attempts,
+            remainingAttempts: attempts,
+            enqueuedAt: Date.now(),
+            state: 'waiting',
+            progress: 0,
+        };
+        this.jobs.set(jobId, job);
+        this.insertByPriority(jobId, job.priority);
+        // Schedule the next drain on the microtask queue so callers see the
+        // jobId before any work happens.
+        queueMicrotask(() => this.drain());
+        return { jobId, estimatedWait: this.estimateWait(job.priority) };
+    }
+    async getJobStatus(jobId) {
+        const job = this.jobs.get(jobId);
+        if (!job)
+            return { status: 'not_found' };
+        if (job.state === 'completed') {
+            return { status: 'completed', progress: 100, result: job.result };
+        }
+        if (job.state === 'failed') {
+            return { status: 'failed', progress: job.progress, error: job.error };
+        }
+        return { status: job.state, progress: job.progress };
+    }
+    async cancelJob(jobId) {
+        const job = this.jobs.get(jobId);
+        if (!job || job.state !== 'waiting')
+            return false;
+        const idx = this.waitingIds.indexOf(jobId);
+        if (idx >= 0)
+            this.waitingIds.splice(idx, 1);
+        this.jobs.delete(jobId);
+        return true;
+    }
+    async getMetrics() {
+        return {
+            waiting: this.waitingIds.length,
+            active: this.activeCount,
+            completed: this.completedCount,
+            failed: this.failedCount,
+        };
+    }
+    // ─── Internal scheduling ───────────────────────────────────────────────
+    insertByPriority(jobId, priority) {
+        // Higher priority runs first. Stable: within a priority we preserve
+        // enqueue order. Linear insert is fine — queues with thousands of
+        // pending jobs should use a real backing store anyway.
+        const insertAt = this.waitingIds.findIndex((id) => {
+            const j = this.jobs.get(id);
+            return j ? j.priority < priority : true;
+        });
+        if (insertAt === -1)
+            this.waitingIds.push(jobId);
+        else
+            this.waitingIds.splice(insertAt, 0, jobId);
+    }
+    estimateWait(priority) {
+        const ahead = this.waitingIds.filter((id) => {
+            const j = this.jobs.get(id);
+            return j ? j.priority >= priority : false;
+        }).length;
+        return ahead * this.estimatedWaitPerJobMs;
+    }
+    drain() {
+        while (this.activeCount < this.concurrency && this.waitingIds.length > 0) {
+            const jobId = this.waitingIds.shift();
+            const job = this.jobs.get(jobId);
+            if (!job)
+                continue;
+            this.activeCount += 1;
+            job.state = 'active';
+            this.run(job);
+        }
+    }
+    async run(job) {
+        const ctx = {
+            jobId: job.jobId,
+            updateProgress: async (percent) => {
+                job.progress = Math.max(0, Math.min(100, percent));
+            },
+        };
+        try {
+            const result = await this.processor(job.payload, ctx);
+            job.result = result;
+            job.progress = 100;
+            job.state = 'completed';
+            this.completedCount += 1;
+        }
+        catch (err) {
+            job.remainingAttempts -= 1;
+            if (job.remainingAttempts > 0) {
+                // Exponential backoff: 2s, 4s, 8s … per attempt index.
+                const attemptIdx = job.attempts - job.remainingAttempts;
+                const delay = Math.min(60_000, 2000 * 2 ** (attemptIdx - 1));
+                job.state = 'waiting';
+                setTimeout(() => {
+                    this.insertByPriority(job.jobId, job.priority);
+                    this.drain();
+                }, delay).unref?.();
+            }
+            else {
+                job.error = err instanceof Error ? err.message : String(err);
+                job.state = 'failed';
+                this.failedCount += 1;
+            }
+        }
+        finally {
+            this.activeCount -= 1;
+            // Drain anything that became eligible while we ran.
+            this.drain();
+        }
+    }
+}
+exports.InMemoryJobQueue = InMemoryJobQueue;

package/dist/adapters/job-queue/job-queue.types.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Generic background-job queue contract. AgentForge uses it for the agent-turn
+ * pipeline (enqueue an agent run, return immediately, poll for status) but the
+ * interface is intentionally domain-agnostic so other long-running operations
+ * can reuse it.
+ *
+ * Two implementations ship with `@agentforge-io/core`:
+ *   - InMemoryJobQueue — single-process, runs the worker on the same node.
+ *     Default. Counters and pending jobs are lost on restart.
+ *   - (BullMQ adapter lives in @agentforge-io/nest, since BullMQ depends on
+ *     Redis + ioredis which we don't want in framework-free core.)
+ *
+ * Custom adapters: implement this interface with whatever backing store you
+ * want (SQS, Postgres, Cloud Tasks) and pass it as `adapters.jobQueue` to
+ * `createAgentForge`.
+ */
+export type JobState = 'waiting' | 'active' | 'completed' | 'failed';
+export interface JobStatus<R> {
+    status: JobState | 'not_found';
+    /** 0-100. Workers report this via the `ctx.updateProgress` callback. */
+    progress?: number;
+    /** Set when status === 'completed'. */
+    result?: R;
+    /** Set when status === 'failed'. */
+    error?: string;
+}
+export interface EnqueueOptions {
+    /** Override the auto-generated jobId. Adapters MUST treat this as idempotent. */
+    jobId?: string;
+    /** Higher value = earlier execution. Default: 0. */
+    priority?: number;
+    /** Maximum retry attempts on failure. Adapter chooses the backoff strategy. */
+    attempts?: number;
+}
+export interface QueueMetrics {
+    waiting: number;
+    active: number;
+    completed: number;
+    failed: number;
+}
+export interface JobQueue<P, R> {
+    /**
+     * Submit a payload for background processing. Returns the assigned jobId
+     * and a rough wait estimate. Implementations are free to estimate based on
+     * queue depth or to return 0 when no estimate is possible.
+     */
+    enqueue(payload: P, opts?: EnqueueOptions): Promise<{
+        jobId: string;
+        estimatedWait: number;
+    }>;
+    /** Look up a job's current state. Returns 'not_found' for unknown ids. */
+    getJobStatus(jobId: string): Promise<JobStatus<R>>;
+    /**
+     * Remove a still-pending job. Returns true if the job was waiting or
+     * delayed and got removed; false if it had already started, finished,
+     * or was unknown.
+     */
+    cancelJob(jobId: string): Promise<boolean>;
+    /** Aggregate counts for monitoring/health checks. */
+    getMetrics(): Promise<QueueMetrics>;
+}
+/**
+ * Context passed to a worker's process function — lets the worker report
+ * progress without coupling to a particular queue implementation.
+ */
+export interface JobContext {
+    jobId: string;
+    updateProgress(percent: number): Promise<void>;
+}
+/**
+ * The worker function signature every JobQueue impl drives internally.
+ * `ctx` lets the worker emit progress updates the queue can surface via
+ * `getJobStatus`.
+ */
+export type JobProcessor<P, R> = (payload: P, ctx: JobContext) => Promise<R>;
+export declare const JOB_QUEUE = "AGENTFORGE_JOB_QUEUE";

package/dist/adapters/job-queue/job-queue.types.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JOB_QUEUE = void 0;
+// String token (not Symbol) so it survives duplicate package instances.
+exports.JOB_QUEUE = 'AGENTFORGE_JOB_QUEUE';

package/dist/adapters/prepared-stream/prepared-stream.types.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Pluggable storage for short-lived "prepared" stream messages.
+ *
+ * Default implementation is in-memory (`InMemoryPreparedStreamStore`). For
+ * multi-instance deploys swap in a Redis-backed implementation that uses
+ * `SETEX` + `GETDEL` so the same atomic take-once semantics hold across nodes.
+ */
+export interface PreparedStreamPayload {
+    userId: string;
+    conversationId: string;
+    content: string;
+    expiresAt: Date;
+}
+export interface PreparedStreamStore {
+    /** Persist a prepared payload under `streamId` with the given TTL. */
+    put(streamId: string, payload: PreparedStreamPayload, ttlMs: number): Promise<void>;
+    /**
+     * Atomically read the payload AND delete it. Returns null if the streamId
+     * was not found or expired. The same streamId can never be consumed twice.
+     */
+    takeOnce(streamId: string): Promise<PreparedStreamPayload | null>;
+}
+export declare const PREPARED_STREAM_STORE = "AGENTFORGE_PREPARED_STREAM_STORE";

package/dist/adapters/prepared-stream/prepared-stream.types.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PREPARED_STREAM_STORE = void 0;
+// String token (not Symbol) so it survives duplicate package instances.
+exports.PREPARED_STREAM_STORE = 'AGENTFORGE_PREPARED_STREAM_STORE';

package/dist/adapters/rate-limiter/in-memory.d.ts

@@ -0,0 +1,19 @@
+import type { RateLimitOptions, RateLimitResult, RateLimiter } from './rate-limiter.types';
+/**
+ * Fixed-window counter. Each key gets a bucket holding the current count and
+ * the window-start timestamp; the bucket resets when the window expires.
+ *
+ * Single-instance only — counters live in process memory. For multi-instance
+ * deploys use `RedisRateLimiter`, which shares counters across nodes via INCR.
+ */
+export declare class InMemoryRateLimiter implements RateLimiter {
+    private readonly buckets;
+    private readonly cleanupInterval;
+    constructor(opts?: {
+        cleanupIntervalMs?: number;
+    });
+    consume(key: string, opts: RateLimitOptions): Promise<RateLimitResult>;
+    /** Stops the periodic cleanup. Call when shutting down a test or worker. */
+    close(): void;
+    private evictExpired;
+}