@combycode/llm-sdk 1.0.0-rc.0

package/dist/plugins/retrieval/index.d.ts

@@ -0,0 +1,70 @@
+/** Retrieval plugin — ergonomic entry helpers.
+ *
+ *  Usage (local, browser-safe):
+ *
+ *    const retrieval = localRetrieval({
+ *      embedAdapter: new OpenAIEmbeddingAdapter({ apiKey }),
+ *      fetch: engine.fetch,
+ *      embeddingModel: 'text-embedding-3-small',
+ *    });
+ *    const corpus = await retrieval.createCorpus({ name: 'my-docs' });
+ *    await retrieval.addDocument(corpus, { text: '...', label: 'doc.txt' });
+ *    const tool = retrieval.asTool([corpus]);          // AgentTool for any provider
+ *    const hits = await retrieval.search([corpus], 'query');
+ *
+ *  Usage (hosted OpenAI vector stores):
+ *
+ *    const retrieval = openaiRetrieval({ apiKey, fetch: engine.fetch });
+ *    const corpus = await retrieval.createCorpus({ name: 'my-store' });
+ *    await retrieval.addDocument(corpus, { text: '...', label: 'doc.txt' });
+ *    const toolSpec = retrieval.asTool([corpus]);      // ProviderToolSpec for Responses API
+ *
+ *  Usage (hosted Google Gemini File Search):
+ *
+ *    const retrieval = googleRetrieval({ apiKey, fetch: engine.fetch });
+ *    const corpus = await retrieval.createCorpus({ name: 'my-store' });
+ *    await retrieval.addDocument(corpus, { text: '...', label: 'doc.txt' });
+ *    const toolSpec = retrieval.asTool([corpus]);      // ProviderToolSpec for generateContent
+ *
+ *  Usage (hosted xAI Grok Collections):
+ *
+ *    const retrieval = xaiRetrieval({ apiKey, managementApiKey, fetch: engine.fetch });
+ *    const corpus = await retrieval.createCorpus({ name: 'my-collection' });
+ *    await retrieval.addDocument(corpus, { text: '...', label: 'doc.txt' });
+ *    const hits = await retrieval.search([corpus], 'query');  // direct search supported
+ *    const toolSpec = retrieval.asTool([corpus]);             // file_search for Responses API
+ */
+export { LocalRetrievalBackend } from './local';
+export type { LocalRetrievalConfig } from './local';
+export { HostedOpenAIRetrievalBackend } from './hosted-openai';
+export type { HostedOpenAIRetrievalConfig } from './hosted-openai';
+export { HostedGoogleRetrievalBackend } from './hosted-google';
+export type { HostedGoogleRetrievalConfig } from './hosted-google';
+export { HostedXaiRetrievalBackend } from './hosted-xai';
+export type { HostedXaiRetrievalConfig } from './hosted-xai';
+export { InMemoryVectorStore } from './vector-store';
+export type { VectorStore, VectorEntry, InMemoryVectorStoreConfig } from './vector-store';
+export { chunkText, DEFAULT_CHUNK_MAX_TOKENS, DEFAULT_CHUNK_OVERLAP_TOKENS } from './chunker';
+export type { ChunkOptions, TextChunk, EstimateTokensFn } from './chunker';
+export type { RetrievalBackend, RetrievalBackendName, RetrievalCapabilities, RetrievalHit, CorpusRef, DocumentRef, DocumentSource, IndexStatus, IndexState, IndexCounts, ProviderToolSpec, CreateCorpusOptions, AddDocumentOptions, RetrievalSearchOptions, AsToolOptions, ChunkingOptions, } from './types';
+import { LocalRetrievalBackend } from './local';
+import type { LocalRetrievalConfig } from './local';
+import { HostedOpenAIRetrievalBackend } from './hosted-openai';
+import type { HostedOpenAIRetrievalConfig } from './hosted-openai';
+import { HostedGoogleRetrievalBackend } from './hosted-google';
+import type { HostedGoogleRetrievalConfig } from './hosted-google';
+import { HostedXaiRetrievalBackend } from './hosted-xai';
+import type { HostedXaiRetrievalConfig } from './hosted-xai';
+/** Build a local (zero-dep, cross-env) retrieval backend. */
+export declare function localRetrieval(config: LocalRetrievalConfig): LocalRetrievalBackend;
+/** Build a hosted OpenAI Vector Stores retrieval backend. */
+export declare function openaiRetrieval(config: HostedOpenAIRetrievalConfig): HostedOpenAIRetrievalBackend;
+/** Build a hosted Google Gemini File Search retrieval backend. */
+export declare function googleRetrieval(config: HostedGoogleRetrievalConfig): HostedGoogleRetrievalBackend;
+/** Build a hosted xAI Grok Collections retrieval backend. */
+export declare function xaiRetrieval(config: HostedXaiRetrievalConfig): HostedXaiRetrievalBackend;
+/** Generic factory when the backend is selected at runtime. */
+export declare function createRetrieval(backend: 'local', config: LocalRetrievalConfig): LocalRetrievalBackend;
+export declare function createRetrieval(backend: 'hostedOpenAI', config: HostedOpenAIRetrievalConfig): HostedOpenAIRetrievalBackend;
+export declare function createRetrieval(backend: 'hostedGoogle', config: HostedGoogleRetrievalConfig): HostedGoogleRetrievalBackend;
+export declare function createRetrieval(backend: 'hostedXai', config: HostedXaiRetrievalConfig): HostedXaiRetrievalBackend;

package/dist/plugins/retrieval/local.d.ts

@@ -0,0 +1,50 @@
+/** Local retrieval backend — zero-dep, cross-env (including browser).
+ *
+ *  Uses OUR embed() helper for vectors and an in-memory VectorStore by default.
+ *  Callers can inject any VectorStore implementation (pgvector, Qdrant, etc.).
+ *
+ *  `asTool()` returns a real AgentTool so it works with Anthropic and every
+ *  other provider that runs tool calls client-side. */
+import type { AgentTool } from '../../agent/types';
+import type { EngineFetch } from '../../network/types';
+import type { EmbeddingProviderAdapter } from '../embeddings/types';
+import type { Persistence } from '../persistence/types';
+import type { AddDocumentOptions, AsToolOptions, CorpusRef, CreateCorpusOptions, DocumentRef, DocumentSource, IndexStatus, RetrievalBackend, RetrievalCapabilities, RetrievalHit, RetrievalSearchOptions } from './types';
+import { type VectorStore } from './vector-store';
+export interface LocalRetrievalConfig {
+    /** Embedding adapter — required for the local backend. */
+    embedAdapter: EmbeddingProviderAdapter;
+    /** Engine fetch function (NetworkEngine.fetch), passed to the embed adapter. */
+    fetch: EngineFetch;
+    /** Pluggable vector store. Defaults to InMemoryVectorStore.
+     *  // bring-your-own backend: pass your own VectorStore implementation here. */
+    vectorStore?: VectorStore;
+    /** Optional persistence for the default InMemoryVectorStore (ignored when
+     *  a custom vectorStore is provided). */
+    persistence?: Persistence;
+    /** Embedding model identifier (e.g. 'text-embedding-3-small'). */
+    embeddingModel: string;
+    /** Default chunk size in tokens. */
+    defaultMaxTokens?: number;
+    /** Default overlap in tokens. */
+    defaultOverlapTokens?: number;
+}
+export declare class LocalRetrievalBackend implements RetrievalBackend {
+    readonly capabilities: RetrievalCapabilities;
+    private readonly embedAdapter;
+    private readonly fetch;
+    private readonly vectorStore;
+    private readonly embeddingModel;
+    private readonly defaultMaxTokens;
+    private readonly defaultOverlapTokens;
+    private readonly corpora;
+    constructor(config: LocalRetrievalConfig);
+    createCorpus(opts: CreateCorpusOptions): Promise<CorpusRef>;
+    addDocument(corpus: CorpusRef, source: DocumentSource, opts?: AddDocumentOptions): Promise<DocumentRef>;
+    indexStatus(corpus: CorpusRef): Promise<IndexStatus>;
+    removeDocument(corpus: CorpusRef, docId: string): Promise<void>;
+    deleteCorpus(corpus: CorpusRef): Promise<void>;
+    listCorpora(): Promise<CorpusRef[]>;
+    asTool(corpora: CorpusRef[], opts?: AsToolOptions): AgentTool;
+    search(corpora: CorpusRef[], query: string, opts?: RetrievalSearchOptions): Promise<RetrievalHit[]>;
+}

package/dist/plugins/retrieval/types.d.ts

@@ -0,0 +1,161 @@
+/** Retrieval (RAG) subsystem — shared types.
+ *
+ *  Five-stage lifecycle shared by all backends:
+ *    create corpus -> add documents -> index -> search / asTool -> cleanup
+ *
+ *  Provider-specific divergences live in capability flags + an `extra` passthrough
+ *  bag, NOT in the core contract. This keeps the interface stable as Google and
+ *  xAI backends are added later.
+ *
+ *  Anti-lock-in: CorpusRef/DocumentRef carry the original source metadata alongside
+ *  the opaque provider id. The source documents are the rebuildable source of truth;
+ *  never depend on exporting a hosted store's embeddings. */
+import type { AgentTool } from '../../agent/types';
+/** Text supplied by the caller; everything else is derived. */
+export interface DocumentSource {
+    /** Plain text content. */
+    text: string;
+    /** Caller-supplied label, e.g. a filename or URL. Stored for citation. */
+    label?: string;
+    /** Arbitrary key-value metadata the caller wants attached to chunks/hits. */
+    metadata?: Record<string, unknown>;
+}
+/** Opaque reference to a corpus (vector store) on a particular backend.
+ *  Carries the original creation options for rebuild support. */
+export interface CorpusRef {
+    /** Backend-specific identifier (e.g. OpenAI vector store id, or local UUID). */
+    id: string;
+    /** Human-readable label; stored alongside the id for display. */
+    name: string;
+    /** Which backend created this corpus. Needed for dispatch. */
+    backend: RetrievalBackendName;
+    /** Provider-specific extra fields (passthrough bag, not part of the core API). */
+    extra?: Record<string, unknown>;
+}
+/** Reference to a single document within a corpus. */
+export interface DocumentRef {
+    /** Backend-specific document identifier. */
+    id: string;
+    /** The corpus this document belongs to. */
+    corpusId: string;
+    /** The original source supplied by the caller (for rebuildability). */
+    source: DocumentSource;
+    /** Provider-specific extra fields. */
+    extra?: Record<string, unknown>;
+}
+/** Normalized indexing state across all backends. */
+export type IndexState = 'pending' | 'indexing' | 'ready' | 'error';
+export interface IndexCounts {
+    /** Total documents in corpus. */
+    total: number;
+    /** Documents fully indexed. */
+    indexed: number;
+    /** Documents in error state. */
+    failed: number;
+}
+export interface IndexStatus {
+    state: IndexState;
+    /** File-level counts (may be absent when not supported by a backend). */
+    counts?: IndexCounts;
+}
+export interface RetrievalHit {
+    /** Matched text chunk. */
+    text: string;
+    /** Cosine similarity score (0-1) or backend-specific relevance score. */
+    score: number;
+    /** Document reference id within the corpus. */
+    docId: string;
+    /** Original caller metadata attached to the document. */
+    metadata?: Record<string, unknown>;
+    /** Human-readable citation string (label + position). */
+    citation?: string;
+}
+/** Provider-native tool specification (splice directly into a provider API call).
+ *  OpenAI/xAI shape: { type: 'file_search', vector_store_ids: [...] }
+ *  Gemini shape: { fileSearch: { fileSearchStoreNames: [...] } } (no top-level type field)
+ *  The index signature allows arbitrary provider-specific keys. */
+export interface ProviderToolSpec {
+    type?: string;
+    vector_store_ids?: string[];
+    max_num_results?: number;
+    filters?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+/** Chunking strategy — named so defaults are never magic. */
+export interface ChunkingOptions {
+    /** Maximum chunk size in tokens (approximate via char heuristic). */
+    maxTokens?: number;
+    /** Overlap between consecutive chunks in tokens. */
+    overlapTokens?: number;
+}
+export interface CreateCorpusOptions {
+    name: string;
+    chunking?: ChunkingOptions;
+    /** How long the corpus lives on hosted backends (e.g. OpenAI `last_active_days`). */
+    expiresAfter?: {
+        anchor: 'last_active_at';
+        days: number;
+    };
+    /** Embedding model for hosted backends that allow selection. */
+    embeddingModel?: string;
+}
+export interface AddDocumentOptions {
+    metadata?: Record<string, unknown>;
+}
+export interface RetrievalSearchOptions {
+    /** Maximum number of hits to return (default: DEFAULT_SEARCH_TOP_K). */
+    maxResults?: number;
+    /** Minimum score threshold to include a hit (0-1). */
+    minScore?: number;
+    /** Backend-specific search mode (e.g. 'hybrid', 'semantic'). */
+    searchMode?: string;
+    /** Metadata filters (backend-specific). */
+    filters?: Record<string, unknown>;
+}
+export interface AsToolOptions {
+    maxResults?: number;
+    searchMode?: string;
+    filters?: Record<string, unknown>;
+}
+/** Static description of what a backend supports. Callers check these to
+ *  degrade gracefully rather than hitting runtime errors. */
+export interface RetrievalCapabilities {
+    /** Whether the caller can control chunking (vs. fully automatic). */
+    userChunking: boolean;
+    /** Available search modes (e.g. ['hybrid'], ['cosine']). */
+    searchModes: string[];
+    /** Whether the backend supports corpus expiration. */
+    expiration: boolean;
+    /** Whether `search()` is supported directly (false for server-side-only). */
+    directSearch: boolean;
+    /** Identifier field name in returned hits (informational). */
+    idField: string;
+    /** Citation format emitted in `RetrievalHit.citation`. */
+    citationFormat: 'label:offset' | 'file_id' | 'gemini' | 'collections-uri' | 'none';
+}
+export type RetrievalBackendName = 'local' | 'hostedOpenAI' | 'hostedGoogle' | 'hostedXai' | (string & NonNullable<unknown>);
+/** Unified interface all retrieval backends must implement. */
+export interface RetrievalBackend {
+    /** Descriptor: what this backend supports. Used for graceful degradation. */
+    readonly capabilities: RetrievalCapabilities;
+    /** Create a new corpus (vector store). */
+    createCorpus(opts: CreateCorpusOptions): Promise<CorpusRef>;
+    /** Add a document to a corpus (hides 1-step vs. 2-step upload differences). */
+    addDocument(corpus: CorpusRef, source: DocumentSource, opts?: AddDocumentOptions): Promise<DocumentRef>;
+    /** Normalized index status across all backends. */
+    indexStatus(corpus: CorpusRef): Promise<IndexStatus>;
+    /** Remove a single document from a corpus. */
+    removeDocument(corpus: CorpusRef, docId: string): Promise<void>;
+    /** Delete an entire corpus and all its documents. */
+    deleteCorpus(corpus: CorpusRef): Promise<void>;
+    /** List all corpora managed by this backend. */
+    listCorpora(): Promise<CorpusRef[]>;
+    /** Build a tool that can be passed to an AgentLoop (local: AgentTool) or
+     *  spliced into a Responses call (hosted: ProviderToolSpec).
+     *  The return type is a union: callers inspect `typeof result === 'object' &&
+     *  'execute' in result` to distinguish AgentTool from ProviderToolSpec. */
+    asTool(corpora: CorpusRef[], opts?: AsToolOptions): AgentTool | ProviderToolSpec;
+    /** Direct search — supported by local and potentially some hosted backends.
+     *  Backends that do not support it throw with a clear message. */
+    search(corpora: CorpusRef[], query: string, opts?: RetrievalSearchOptions): Promise<RetrievalHit[]>;
+}

package/dist/plugins/retrieval/vector-store.d.ts

@@ -0,0 +1,70 @@
+/** VectorStore — interface + in-memory reference implementation.
+ *
+ *  The interface is intentionally minimal so callers can plug a real DB
+ *  (pgvector, Qdrant, Weaviate, etc.) via their own adapter:
+ *
+ *    // bring-your-own backend:
+ *    class MyPgVectorStore implements VectorStore { ... }
+ *    const backend = localRetrieval({ vectorStore: new MyPgVectorStore() });
+ *
+ *  The bundled `InMemoryVectorStore` is the default. It uses cosine similarity,
+ *  runs fully in-process, works in the browser, and has zero external deps.
+ *  It supports optional persistence via the cross-env `Persistence` layer so
+ *  vectors survive process restarts (opt-in; default is ephemeral). */
+import type { Persistence } from '../persistence/types';
+/** A single chunk stored in the vector store. */
+export interface VectorEntry {
+    /** Corpus-scoped unique identifier for this chunk. */
+    id: string;
+    /** ID of the source document. */
+    docId: string;
+    /** ID of the corpus this entry belongs to. */
+    corpusId: string;
+    /** The embedding vector. */
+    vector: number[];
+    /** The original text of this chunk. */
+    text: string;
+    /** Caller-provided metadata from the document source. */
+    metadata?: Record<string, unknown>;
+    /** Human-readable citation (e.g. "label:offset"). */
+    citation?: string;
+}
+/** Pluggable vector storage. Implement this to use any real DB backend.
+ *  The in-memory default `InMemoryVectorStore` satisfies this contract. */
+export interface VectorStore {
+    /** Insert an entry. Overwrites any existing entry with the same `id`. */
+    upsert(entry: VectorEntry): Promise<void>;
+    /** Remove all entries for a given document. */
+    removeByDocId(corpusId: string, docId: string): Promise<void>;
+    /** Remove all entries for an entire corpus. */
+    removeByCorpusId(corpusId: string): Promise<void>;
+    /** Top-k nearest neighbours within a corpus by cosine similarity.
+     *  Returns at most `topK` hits ordered by descending score. */
+    query(corpusId: string, vector: number[], topK: number): Promise<Array<{
+        entry: VectorEntry;
+        score: number;
+    }>>;
+    /** Count stored entries, optionally scoped to a corpus. */
+    count(corpusId?: string): Promise<number>;
+}
+export interface InMemoryVectorStoreConfig {
+    /** Optional persistence layer. When supplied the store saves/loads via it.
+     *  Omit (default) for an entirely ephemeral in-process store. */
+    persistence?: Persistence;
+}
+export declare class InMemoryVectorStore implements VectorStore {
+    private entries;
+    private readonly persistence;
+    private loaded;
+    constructor(config?: InMemoryVectorStoreConfig);
+    upsert(entry: VectorEntry): Promise<void>;
+    removeByDocId(corpusId: string, docId: string): Promise<void>;
+    removeByCorpusId(corpusId: string): Promise<void>;
+    query(corpusId: string, vector: number[], topK: number): Promise<Array<{
+        entry: VectorEntry;
+        score: number;
+    }>>;
+    count(corpusId?: string): Promise<number>;
+    private ensureLoaded;
+    private persist;
+}

package/dist/plugins/scheduler/scheduler.d.ts

@@ -0,0 +1,31 @@
+/** Scheduler — durable task scheduling. Tasks survive restarts when backed
+ *  by a Persistence implementation. Functions registered by name; tasks are
+ *  `{ name, args, fireAt }`. */
+import type { Persistence } from '../persistence/types';
+export interface ScheduledTaskDef {
+    id: string;
+    name: string;
+    args: Record<string, unknown>;
+    fireAt: number;
+    type: 'once' | 'periodic';
+    interval: number | null;
+}
+export declare class Scheduler {
+    private persistence;
+    private handlers;
+    private timers;
+    private running;
+    constructor(persistence: Persistence);
+    register(name: string, fn: (args: Record<string, unknown>) => void | Promise<void>): void;
+    after(duration: string | number, taskName: string, args?: Record<string, unknown>): Promise<string>;
+    at(datetime: Date | number, taskName: string, args?: Record<string, unknown>): Promise<string>;
+    every(interval: string | number, taskName: string, args?: Record<string, unknown>): Promise<string>;
+    cancel(taskId: string): Promise<void>;
+    start(): Promise<void>;
+    stop(): void;
+    pending(): Promise<ScheduledTaskDef[]>;
+    private scheduleTimer;
+    private fireTask;
+}
+/** Parse duration string ('30s', '5m', '1h', '2d') or raw number (ms) into ms. */
+export declare function parseDuration(input: string | number): number;

package/dist/plugins/telemetry/telemetry.d.ts

@@ -0,0 +1,118 @@
+/** TelemetryAdapter — a single tap (HookBus.onAny) that turns the SDK's events
+ *  into the three OpenTelemetry signals, with NO `@opentelemetry` dependency:
+ *
+ *    - TRACES   spans opened/closed from start/complete event pairs, correlated
+ *               by `traceId = sessionId:requestId`.
+ *    - METRICS  event-driven counters/gauges (cost, tokens, retries, queue depth,
+ *               latency samples) — updated ON events, not polled.
+ *    - LOGS     the full event stream (name + category + traceId + raw ctx).
+ *
+ *  An in-memory store backs the sandbox sidebar; `toOtlpTraces()` shapes spans
+ *  into OTLP-compatible JSON for a real OTel exporter to forward. */
+import type { HookBus } from '../../bus/hook-bus';
+import type { HookName } from '../../bus/hook-map';
+export type SpanKind = 'llm' | 'http' | 'media' | 'agent' | 'tool' | 'mcp' | 'other';
+export interface Span {
+    traceId: string;
+    spanId: string;
+    name: string;
+    kind: SpanKind;
+    startTime: number;
+    endTime?: number;
+    durationMs?: number;
+    status: 'unset' | 'ok' | 'error';
+    attributes: Record<string, unknown>;
+}
+export interface TelemetryEvent {
+    seq: number;
+    time: number;
+    name: HookName;
+    category: string;
+    traceId?: string;
+    ctx: unknown;
+}
+export interface TelemetryMetrics {
+    requests: number;
+    errors: number;
+    retries: number;
+    rateLimitHits: number;
+    completions: number;
+    mediaGenerated: number;
+    costUsd: number;
+    inputTokens: number;
+    outputTokens: number;
+    inFlight: number;
+    queueDepth: number;
+    latency: {
+        count: number;
+        min: number;
+        max: number;
+        avg: number;
+    };
+}
+/** OpenTelemetry Resource — identifies the SERVICE producing this telemetry, so
+ *  a shared backend can separate streams from different apps and attribute cost
+ *  per service (`sum by service.name`). Stamped on every span/metric/log. */
+export interface TelemetryResource {
+    /** Primary grouping key, e.g. "billing-api". OTel default: "unknown_service". */
+    serviceName: string;
+    /** Optional namespace/group, e.g. "prod" or a team. */
+    serviceNamespace?: string;
+    /** Unique instance (pod/host/process); a good default is the engine sessionId. */
+    serviceInstanceId?: string;
+    serviceVersion?: string;
+    /** Arbitrary resource attributes (deployment.environment, cloud.region, …). */
+    attributes?: Record<string, string>;
+}
+export interface TelemetryAdapterOptions {
+    /** Cap on retained events (ring buffer). Default 2000. */
+    maxEvents?: number;
+    /** Service identity stamped on all exported telemetry. */
+    resource?: TelemetryResource;
+}
+export declare class TelemetryAdapter {
+    readonly events: TelemetryEvent[];
+    readonly spans: Span[];
+    readonly metrics: TelemetryMetrics;
+    /** Service identity stamped on exported telemetry. */
+    readonly resource: TelemetryResource;
+    private seq;
+    private latSum;
+    private readonly open;
+    private readonly maxEvents;
+    private readonly unsub;
+    constructor(hooks: HookBus, opts?: TelemetryAdapterOptions);
+    /** Stop tapping the bus. */
+    destroy(): void;
+    private handle;
+    private openSpan;
+    private closeSpan;
+    private recordLatency;
+    /** OTLP resource attributes (service.name + extras) — stamped on all exports. */
+    private resourceAttributes;
+    /** Snapshot: completed spans, event log, current metrics. */
+    snapshot(): {
+        spans: Span[];
+        events: TelemetryEvent[];
+        metrics: TelemetryMetrics;
+    };
+    /** A debug bundle as a JSON string, with large strings (base64 blobs) trimmed
+     *  — for "save the session to a file" download. */
+    serialize(): string;
+    /** Shape completed spans into OTLP-compatible JSON (resourceSpans) for an
+     *  external OpenTelemetry exporter — no SDK dependency here. */
+    toOtlpTraces(): unknown;
+}
+/** Redact sensitive query parameters from a URL string.
+ *  Replaces values of params in SENSITIVE_QUERY_PARAMS with REDACTED. */
+export declare function sanitizeUrl(url: string): string;
+/** Redact sensitive header values, returning a new record. */
+export declare function sanitizeHeaders(headers: Record<string, string>): Record<string, string>;
+/** JSON.stringify replacer that truncates huge strings (base64 media blobs) so
+ *  an exported debug bundle stays small + readable. Also unwraps Error objects:
+ *  `message`/`stack` are non-enumerable, so a raw `JSON.stringify(error)` drops
+ *  the most useful field — the actual provider message (e.g. a 400 reason).
+ *
+ *  Only safe, non-sensitive Error fields are exported: name, message, code, cause.
+ *  Arbitrary attached props (which could carry secrets) are NOT spread. */
+export declare function trimReplacer(_key: string, value: unknown): unknown;

package/dist/plugins/tool-catalog/catalog.d.ts

@@ -0,0 +1,31 @@
+/** ToolCatalog — registry of tools, per-agent scopes, gated execution. */
+import type { AgentBus } from '../../bus/agent-bus';
+import type { PermissionPolicy } from '../permissions/policy';
+import type { AgentScope, CatalogedTool, ToolCallRequest, ToolCallResult, ToolDefinition } from './types';
+export interface ToolCatalogConfig {
+    bus?: AgentBus;
+    policy?: PermissionPolicy;
+}
+export declare class ToolCatalog {
+    private readonly tools;
+    private readonly scopes;
+    private readonly bus;
+    private readonly defaultPolicy;
+    constructor(config?: ToolCatalogConfig);
+    register(tool: CatalogedTool): void;
+    unregister(name: string): boolean;
+    has(name: string): boolean;
+    setAgentScope(agentId: string, scope: AgentScope): void;
+    removeAgentScope(agentId: string): void;
+    getAgentScope(agentId: string): AgentScope | undefined;
+    visibleTo(agentId: string): ToolDefinition[];
+    getDefinition(name: string, agentId?: string): ToolDefinition | undefined;
+    search(query: {
+        name?: string;
+        description?: string;
+    }, agentId?: string): ToolDefinition[];
+    call(req: ToolCallRequest): Promise<ToolCallResult>;
+    private scopeAllows;
+    private buildContext;
+    private emitEvent;
+}

package/dist/plugins/tool-catalog/errors.d.ts

@@ -0,0 +1,22 @@
+/** Typed errors thrown by ToolCatalog. */
+import type { PermissionTarget } from '../permissions/types';
+export declare class ToolNotFound extends Error {
+    readonly toolName: string;
+    constructor(toolName: string);
+}
+export declare class NoToolAccess extends Error {
+    readonly source: string;
+    readonly toolName: string;
+    readonly reasonDetail: string;
+    constructor(source: string, toolName: string, reasonDetail: string);
+}
+export declare class PermissionDenied extends Error {
+    readonly source: string;
+    readonly target: PermissionTarget;
+    readonly action: string;
+    readonly reasonDetail?: string;
+    constructor(source: string, target: PermissionTarget, action: string, reasonDetail?: string);
+}
+export declare class ToolRegistrationError extends Error {
+    constructor(message: string);
+}

package/dist/plugins/tool-catalog/types.d.ts

@@ -0,0 +1,44 @@
+/** ToolCatalog types — strict tool-policy contract. */
+import type { JsonSchema } from '../../llm/types/tools';
+import type { PermissionPolicy } from '../permissions/policy';
+import type { PermissionTarget } from '../permissions/types';
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    parameters: JsonSchema;
+}
+export type ToolCategory = 'internal' | 'external';
+export interface TargetDeclaration {
+    kind: string;
+    value?: PermissionTarget;
+    pattern?: string | string[];
+}
+export interface CatalogedTool {
+    definition: ToolDefinition;
+    category: ToolCategory;
+    declaredTargets: TargetDeclaration[];
+    declaredActions: string[];
+    execute: (input: Record<string, unknown>, ctx: ToolContext) => Promise<unknown>;
+}
+export interface ToolContext {
+    source: string;
+    correlationId?: string;
+    checkAccess(target: PermissionTarget, action: string): void;
+    emit(kind: string, payload: unknown): Promise<void>;
+}
+export interface AgentScope {
+    toolNames: readonly string[] | '*';
+    externalAllowed?: boolean;
+    policy?: PermissionPolicy;
+}
+export interface ToolCallRequest {
+    toolName: string;
+    source: string;
+    input: Record<string, unknown>;
+    correlationId?: string;
+}
+export interface ToolCallResult {
+    callId: string;
+    output: unknown;
+    durationMs: number;
+}

package/dist/runtime/runtime.d.ts

@@ -0,0 +1,20 @@
+/** Runtime detection + lazy Node-only module access.
+ *
+ *  The SDK is cross-environment: it runs on Node/Bun (server) and bundles for
+ *  the browser. Browser bundlers cannot resolve `node:*` builtins, so NO module
+ *  on a reachable import path may statically `import 'node:…'`. Node access goes
+ *  through the lazy loaders here instead — the dynamic `import()` only executes
+ *  when the feature is actually used, and rejects cleanly in the browser with a
+ *  friendly message (callers catch it or let it surface). */
+/** True when running inside a browser (DOM present), false on Node/Bun. */
+export declare function isBrowser(): boolean;
+/** Lazily load `node:fs/promises`; throws a friendly error in the browser.
+ *  The isBrowser() guard runs first so the browser bundle never reaches the
+ *  (stubbed) import — keeping node: out of the browser graph entirely. */
+export declare function nodeFsPromises(): Promise<typeof import('node:fs/promises')>;
+/** Lazily load `node:fs` (sync helpers like existsSync); browser-friendly error. */
+export declare function nodeFs(): Promise<typeof import('node:fs')>;
+/** Lazily load `node:path`; browser-friendly error. */
+export declare function nodePath(): Promise<typeof import('node:path')>;
+/** Lazily load `node:child_process` (stdio MCP transport); browser-friendly error. */
+export declare function nodeChildProcess(): Promise<typeof import('node:child_process')>;

package/dist/server/auth.d.ts

@@ -0,0 +1,25 @@
+/** AuthPlugin — server-side authentication slot.
+ *
+ *  Servers without an AuthPlugin treat all requests as unauthenticated
+ *  (userId = null). When attached, every request runs through `verify()`;
+ *  the returned userId scopes the ResponseStore key. */
+export interface AuthVerifyResult {
+    /** Stable owner id used to scope ResponseStore entries. */
+    userId: string;
+    /** Free-form metadata for downstream plugins (roles, scopes, etc.). */
+    metadata?: Record<string, unknown>;
+}
+export interface AuthPlugin {
+    /** Inspect request headers and return the authenticated userId, or throw to reject. */
+    verify(headers: Record<string, string>): Promise<AuthVerifyResult> | AuthVerifyResult;
+}
+/** Bearer key auth — the simplest authenticator. Each known key maps to a userId. */
+export declare class BearerKeyAuth implements AuthPlugin {
+    private readonly keys;
+    constructor(config: {
+        keys: Record<string, string>;
+    } | {
+        keys: string[];
+    });
+    verify(headers: Record<string, string>): AuthVerifyResult;
+}