@a5c-ai/agent-comm-mux 5.0.1-staging.04ca6ab00d21

package/dist/config-manager.js

@@ -0,0 +1,202 @@
+/**
+ * ConfigManager interface and implementation for @a5c-ai/agent-mux.
+ *
+ * Provides unified configuration access for all supported agents.
+ * Reads and writes each agent's native config through the adapter layer.
+ *
+ * @see 08-config-and-auth.md
+ */
+import { AgentMuxError } from './errors.js';
+import { deepMerge } from './merge.js';
+// ---------------------------------------------------------------------------
+// ConfigManagerImpl
+// ---------------------------------------------------------------------------
+/**
+ * Implementation of ConfigManager.
+ *
+ * Delegates file I/O to agent adapters. Provides caching,
+ * deep merge, field-level access, and schema introspection.
+ */
+export class ConfigManagerImpl {
+    _adapters;
+    _profileManager;
+    _cache = new Map();
+    /**
+     * Per-agent write serialisation. All `.set()` / `.setField()` / MCP mutation
+     * calls for a given agent queue onto the same promise so concurrent callers
+     * cannot interleave read-modify-write sequences. File-level atomicity is
+     * additionally enforced by the adapter writing through `writeJsonAtomic`
+     * from `atomic-fs.ts`, which uses a tmp+fsync+rename + advisory lockfile.
+     */
+    _writeQueue = new Map();
+    constructor(adapters, profileManager) {
+        this._adapters = adapters;
+        this._profileManager = profileManager;
+    }
+    // -- Helper ------------------------------------------------------------------
+    _getAdapter(agent) {
+        const adapter = this._adapters.get(agent);
+        if (!adapter) {
+            throw new AgentMuxError('AGENT_NOT_FOUND', `Unknown agent: "${agent}"`);
+        }
+        return adapter;
+    }
+    // -- get() -------------------------------------------------------------------
+    get(agent) {
+        const cached = this._cache.get(agent);
+        if (cached)
+            return cached;
+        this._getAdapter(agent); // Validates the agent exists
+        // Return a default config when cache is cold and no file has been read
+        const defaultConfig = {
+            agent,
+            source: 'merged',
+            filePaths: [],
+        };
+        this._cache.set(agent, defaultConfig);
+        return defaultConfig;
+    }
+    // -- getField() --------------------------------------------------------------
+    getField(agent, field) {
+        const config = this.get(agent);
+        return getNestedField(config, field);
+    }
+    // -- set() -------------------------------------------------------------------
+    async set(agent, fields) {
+        return this._enqueueWrite(agent, async () => {
+            const adapter = this._getAdapter(agent);
+            const current = this.get(agent);
+            const merged = deepMerge(current, fields);
+            await adapter.writeConfig(fields);
+            this._cache.set(agent, merged);
+        });
+    }
+    /** Serialise writes per agent so concurrent `.set()` cannot interleave. */
+    async _enqueueWrite(agent, fn) {
+        const prev = this._writeQueue.get(agent) ?? Promise.resolve();
+        const next = prev.catch(() => undefined).then(fn);
+        this._writeQueue.set(agent, next);
+        try {
+            return await next;
+        }
+        finally {
+            if (this._writeQueue.get(agent) === next) {
+                this._writeQueue.delete(agent);
+            }
+        }
+    }
+    // -- setField() --------------------------------------------------------------
+    async setField(agent, field, value) {
+        const partial = buildNestedObject(field, value);
+        await this.set(agent, partial);
+    }
+    // -- schema() ----------------------------------------------------------------
+    schema(agent) {
+        const adapter = this._getAdapter(agent);
+        return adapter.configSchema;
+    }
+    // -- validate() --------------------------------------------------------------
+    validate(_agent, _config) {
+        this._getAdapter(_agent);
+        // Basic validation: always returns valid for now.
+        // Full schema validation will be implemented when adapters provide
+        // detailed ConfigField descriptors.
+        return {
+            valid: true,
+            errors: [],
+            warnings: [],
+        };
+    }
+    // -- getMcpServers() ---------------------------------------------------------
+    getMcpServers(agent) {
+        const config = this.get(agent);
+        return config.mcpServers ?? [];
+    }
+    getModelSelection(agent) {
+        const adapter = this._getAdapter(agent);
+        const config = this.get(agent);
+        const configuredModel = typeof config.model === 'string' ? config.model : null;
+        const configuredProvider = typeof config.provider === 'string' ? config.provider : null;
+        const defaultModel = adapter.defaultModelId ?? null;
+        return {
+            configuredModel,
+            configuredProvider,
+            defaultModel,
+            effectiveModel: configuredModel ?? defaultModel,
+        };
+    }
+    async setModelSelection(agent, selection) {
+        const patch = {};
+        if (Object.prototype.hasOwnProperty.call(selection, 'model')) {
+            patch.model = selection.model ?? null;
+        }
+        if (Object.prototype.hasOwnProperty.call(selection, 'provider')) {
+            patch.provider = selection.provider ?? null;
+        }
+        await this.set(agent, patch);
+    }
+    // -- addMcpServer() ----------------------------------------------------------
+    async addMcpServer(agent, server) {
+        const existing = this.getMcpServers(agent);
+        const duplicate = existing.find((s) => s.name === server.name);
+        if (duplicate) {
+            throw new AgentMuxError('CONFIG_ERROR', `MCP server "${server.name}" already exists in config for agent "${agent}"`);
+        }
+        const updated = [...existing, server];
+        await this.set(agent, { mcpServers: updated });
+    }
+    // -- removeMcpServer() -------------------------------------------------------
+    async removeMcpServer(agent, serverName) {
+        const existing = this.getMcpServers(agent);
+        const index = existing.findIndex((s) => s.name === serverName);
+        if (index === -1) {
+            throw new AgentMuxError('CONFIG_ERROR', `MCP server "${serverName}" not found in config for agent "${agent}"`);
+        }
+        const updated = existing.filter((s) => s.name !== serverName);
+        await this.set(agent, { mcpServers: updated });
+    }
+    // -- reload() ----------------------------------------------------------------
+    async reload(agent) {
+        if (agent) {
+            this._getAdapter(agent);
+            this._cache.delete(agent);
+        }
+        else {
+            this._cache.clear();
+        }
+    }
+    // -- profiles() --------------------------------------------------------------
+    profiles() {
+        return this._profileManager;
+    }
+}
+// ---------------------------------------------------------------------------
+// Helper: dot-notation field access
+// ---------------------------------------------------------------------------
+function getNestedField(obj, path) {
+    const parts = path.split('.');
+    let current = obj;
+    for (const part of parts) {
+        if (current === null || current === undefined || typeof current !== 'object') {
+            return undefined;
+        }
+        current = current[part];
+    }
+    return current;
+}
+function buildNestedObject(path, value) {
+    const parts = path.split('.');
+    if (parts.length === 1) {
+        return { [parts[0]]: value };
+    }
+    const result = {};
+    let current = result;
+    for (let i = 0; i < parts.length - 1; i++) {
+        const next = {};
+        current[parts[i]] = next;
+        current = next;
+    }
+    current[parts[parts.length - 1]] = value;
+    return result;
+}
+//# sourceMappingURL=config-manager.js.map

package/dist/config-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-manager.js","sourceRoot":"","sources":["../src/config-manager.ts"],"names":[],"mappings":"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"}

package/dist/config-types.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Configuration-related types for @a5c-ai/agent-mux.
+ *
+ * Defines agent config, config schema, config fields,
+ * and validation result types.
+ *
+ * @see 08-config-and-auth.md
+ */
+import type { AgentName, McpServerConfig } from './types.js';
+/** Unified agent configuration structure. */
+export interface AgentConfig {
+    /** The agent this configuration belongs to. */
+    readonly agent?: AgentName;
+    /** Configuration source: global, project, or merged. */
+    readonly source?: 'global' | 'project' | 'merged';
+    /** File paths the configuration was loaded from. */
+    readonly filePaths?: string[];
+    /** Default model ID. */
+    model?: string | null;
+    /** Provider name. */
+    provider?: string | null;
+    /** Sampling temperature. */
+    temperature?: number;
+    /** Maximum output tokens. */
+    maxTokens?: number;
+    /** Allowed shell commands. */
+    allowedCommands?: string[];
+    /** Denied shell commands. */
+    deniedCommands?: string[];
+    /** Approval mode for tool calls. */
+    approvalMode?: 'yolo' | 'prompt' | 'deny';
+    /** MCP server configurations. */
+    mcpServers?: McpServerConfig[];
+    /** Skills to load. */
+    skills?: string[];
+    /** Path to the agents doc file. */
+    agentsDoc?: string;
+    /** Environment variables. */
+    env?: Record<string, string>;
+    /** Native agent-specific configuration. */
+    native?: Record<string, unknown>;
+    /** Index signature for dynamic access. */
+    [key: string]: unknown;
+}
+/** Effective model selection state for an agent. */
+export interface ModelSelection {
+    /** Explicitly configured model, if any. */
+    readonly configuredModel: string | null;
+    /** Explicitly configured provider, if any. */
+    readonly configuredProvider: string | null;
+    /** Adapter-declared default model. */
+    readonly defaultModel: string | null;
+    /** Effective model after config fallback to adapter default. */
+    readonly effectiveModel: string | null;
+}
+/** Describes a single configuration field within an agent's config schema. */
+export interface ConfigField {
+    /** Dot-notation field path. */
+    readonly path: string;
+    /** Human-readable label. */
+    readonly label: string;
+    /** Brief description. */
+    readonly description: string;
+    /** Value type. */
+    readonly type: 'string' | 'number' | 'boolean' | 'enum' | 'string[]' | 'object' | 'McpServerConfig[]';
+    /** Whether the field is required. */
+    readonly required: boolean;
+    /** Default value. */
+    readonly defaultValue?: unknown;
+    /** Allowed values for enum type. */
+    readonly enumValues?: string[];
+    /** Minimum for numeric fields. */
+    readonly min?: number;
+    /** Maximum for numeric fields. */
+    readonly max?: number;
+    /** Regex pattern for string values. */
+    readonly pattern?: string;
+    /** Whether this maps to a normalized AgentConfig field. */
+    readonly normalized: boolean;
+    /** Native key path in the agent's config file. */
+    readonly nativeKeyPath: string;
+    /** Which config scope(s) this field can appear in. */
+    readonly scope: 'global' | 'project' | 'both';
+}
+/** Agent configuration schema descriptor. */
+export interface AgentConfigSchema {
+    /** The agent this schema belongs to. */
+    readonly agent?: AgentName;
+    /** Schema version (for backward compat). */
+    readonly version?: number;
+    /** Schema fields. */
+    readonly fields: ConfigField[] | unknown[];
+    /** Global config file paths. */
+    readonly configFilePaths?: string[];
+    /** Project config file paths. */
+    readonly projectConfigFilePaths?: string[];
+    /** Config file format. */
+    readonly configFormat?: 'json' | 'yaml';
+    /** Whether this agent supports project-level config. */
+    readonly supportsProjectConfig?: boolean;
+}
+/** Validation result from ConfigManager.validate(). */
+export interface ValidationResult {
+    /** Whether the config is valid. */
+    readonly valid: boolean;
+    /** Field-level validation errors. */
+    readonly errors: ConfigValidationError[];
+    /** Field-level warnings. */
+    readonly warnings: ConfigValidationWarning[];
+}
+/** A single validation error for a config field. */
+export interface ConfigValidationError {
+    /** Dot-notation path to the field. */
+    readonly field: string;
+    /** Error code. */
+    readonly code: 'required' | 'type_mismatch' | 'out_of_range' | 'invalid_enum' | 'pattern_mismatch' | 'unknown_field' | 'invalid_format';
+    /** Human-readable error message. */
+    readonly message: string;
+    /** The invalid value. */
+    readonly value?: unknown;
+    /** Expected type or constraint. */
+    readonly expected?: string;
+}
+/** A non-fatal validation warning. */
+export interface ConfigValidationWarning {
+    /** Dot-notation path to the field. */
+    readonly field: string;
+    /** Warning code. */
+    readonly code: 'deprecated' | 'non_standard';
+    /** Human-readable warning message. */
+    readonly message: string;
+    /** Suggested replacement. */
+    readonly suggestion?: string;
+}

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

@@ -0,0 +1 @@
+{"version":3,"file":"config-types.d.ts","sourceRoot":"","sources":["../src/config-types.ts"],"names":[],"mappings":"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"}

package/dist/config-types.js

@@ -0,0 +1,10 @@
+/**
+ * Configuration-related types for @a5c-ai/agent-mux.
+ *
+ * Defines agent config, config schema, config fields,
+ * and validation result types.
+ *
+ * @see 08-config-and-auth.md
+ */
+export {};
+//# sourceMappingURL=config-types.js.map

package/dist/config-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-types.js","sourceRoot":"","sources":["../src/config-types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/dist/cost-utils.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Public helpers for aggregating cost/token usage from an event stream or
+ * a stored session transcript. These mirror the internal accumulators in
+ * run-handle-cost.ts but accept any iterable of AgentEvent — so callers can
+ * use them on live streams (`handle.events()`) and on session files read
+ * back later (`sessions.read(id).events`) with the same shape.
+ */
+import type { AgentEvent } from './events.js';
+export interface EventCostSummary {
+    totalUsd: number;
+    inputTokens: number;
+    outputTokens: number;
+    thinkingTokens: number;
+    cachedTokens: number;
+    totalTokens: number;
+    costEventCount: number;
+}
+/** Fold every `cost` event in a collection into a single summary. */
+export declare function sumCost(events: Iterable<AgentEvent>): EventCostSummary;
+/** Async variant — fold cost events as they arrive on a live stream. */
+export declare function sumCostAsync(events: AsyncIterable<AgentEvent>): Promise<EventCostSummary>;
+/**
+ * Filter an event iterable to a single event type, with correct narrowing.
+ * `for (const ev of filterEvents(events, 'text_delta')) ev.delta ...`
+ */
+export declare function filterEvents<T extends AgentEvent['type']>(events: Iterable<AgentEvent>, type: T): Generator<Extract<AgentEvent, {
+    type: T;
+}>>;
+export declare function filterEventsAsync<T extends AgentEvent['type']>(events: AsyncIterable<AgentEvent>, type: T): AsyncGenerator<Extract<AgentEvent, {
+    type: T;
+}>>;

package/dist/cost-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost-utils.d.ts","sourceRoot":"","sources":["../src/cost-utils.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;CACxB;AAcD,qEAAqE;AACrE,wBAAgB,OAAO,CAAC,MAAM,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,gBAAgB,CAetE;AAED,wEAAwE;AACxE,wBAAsB,YAAY,CAAC,MAAM,EAAE,aAAa,CAAC,UAAU,CAAC,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAe/F;AAED;;;GAGG;AACH,wBAAiB,YAAY,CAAC,CAAC,SAAS,UAAU,CAAC,MAAM,CAAC,EACxD,MAAM,EAAE,QAAQ,CAAC,UAAU,CAAC,EAC5B,IAAI,EAAE,CAAC,GACN,SAAS,CAAC,OAAO,CAAC,UAAU,EAAE;IAAE,IAAI,EAAE,CAAC,CAAA;CAAE,CAAC,CAAC,CAI7C;AAED,wBAAuB,iBAAiB,CAAC,CAAC,SAAS,UAAU,CAAC,MAAM,CAAC,EACnE,MAAM,EAAE,aAAa,CAAC,UAAU,CAAC,EACjC,IAAI,EAAE,CAAC,GACN,cAAc,CAAC,OAAO,CAAC,UAAU,EAAE;IAAE,IAAI,EAAE,CAAC,CAAA;CAAE,CAAC,CAAC,CAIlD"}

package/dist/cost-utils.js

@@ -0,0 +1,69 @@
+/**
+ * Public helpers for aggregating cost/token usage from an event stream or
+ * a stored session transcript. These mirror the internal accumulators in
+ * run-handle-cost.ts but accept any iterable of AgentEvent — so callers can
+ * use them on live streams (`handle.events()`) and on session files read
+ * back later (`sessions.read(id).events`) with the same shape.
+ */
+function emptySummary() {
+    return {
+        totalUsd: 0,
+        inputTokens: 0,
+        outputTokens: 0,
+        thinkingTokens: 0,
+        cachedTokens: 0,
+        totalTokens: 0,
+        costEventCount: 0,
+    };
+}
+/** Fold every `cost` event in a collection into a single summary. */
+export function sumCost(events) {
+    const acc = emptySummary();
+    for (const ev of events) {
+        if (ev.type === 'cost') {
+            const c = ev.cost;
+            acc.totalUsd += c.totalUsd ?? 0;
+            acc.inputTokens += c.inputTokens ?? 0;
+            acc.outputTokens += c.outputTokens ?? 0;
+            acc.thinkingTokens += c.thinkingTokens ?? 0;
+            acc.cachedTokens += c.cachedTokens ?? 0;
+            acc.costEventCount += 1;
+        }
+    }
+    acc.totalTokens = acc.inputTokens + acc.outputTokens + acc.thinkingTokens;
+    return acc;
+}
+/** Async variant — fold cost events as they arrive on a live stream. */
+export async function sumCostAsync(events) {
+    const acc = emptySummary();
+    for await (const ev of events) {
+        if (ev.type === 'cost') {
+            const c = ev.cost;
+            acc.totalUsd += c.totalUsd ?? 0;
+            acc.inputTokens += c.inputTokens ?? 0;
+            acc.outputTokens += c.outputTokens ?? 0;
+            acc.thinkingTokens += c.thinkingTokens ?? 0;
+            acc.cachedTokens += c.cachedTokens ?? 0;
+            acc.costEventCount += 1;
+        }
+    }
+    acc.totalTokens = acc.inputTokens + acc.outputTokens + acc.thinkingTokens;
+    return acc;
+}
+/**
+ * Filter an event iterable to a single event type, with correct narrowing.
+ * `for (const ev of filterEvents(events, 'text_delta')) ev.delta ...`
+ */
+export function* filterEvents(events, type) {
+    for (const ev of events) {
+        if (ev.type === type)
+            yield ev;
+    }
+}
+export async function* filterEventsAsync(events, type) {
+    for await (const ev of events) {
+        if (ev.type === type)
+            yield ev;
+    }
+}
+//# sourceMappingURL=cost-utils.js.map

package/dist/cost-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost-utils.js","sourceRoot":"","sources":["../src/cost-utils.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAcH,SAAS,YAAY;IACnB,OAAO;QACL,QAAQ,EAAE,CAAC;QACX,WAAW,EAAE,CAAC;QACd,YAAY,EAAE,CAAC;QACf,cAAc,EAAE,CAAC;QACjB,YAAY,EAAE,CAAC;QACf,WAAW,EAAE,CAAC;QACd,cAAc,EAAE,CAAC;KAClB,CAAC;AACJ,CAAC;AAED,qEAAqE;AACrE,MAAM,UAAU,OAAO,CAAC,MAA4B;IAClD,MAAM,GAAG,GAAG,YAAY,EAAE,CAAC;IAC3B,KAAK,MAAM,EAAE,IAAI,MAAM,EAAE,CAAC;QACxB,IAAI,EAAE,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;YACvB,MAAM,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC;YAClB,GAAG,CAAC,QAAQ,IAAI,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC;YAChC,GAAG,CAAC,WAAW,IAAI,CAAC,CAAC,WAAW,IAAI,CAAC,CAAC;YACtC,GAAG,CAAC,YAAY,IAAI,CAAC,CAAC,YAAY,IAAI,CAAC,CAAC;YACxC,GAAG,CAAC,cAAc,IAAI,CAAC,CAAC,cAAc,IAAI,CAAC,CAAC;YAC5C,GAAG,CAAC,YAAY,IAAI,CAAC,CAAC,YAAY,IAAI,CAAC,CAAC;YACxC,GAAG,CAAC,cAAc,IAAI,CAAC,CAAC;QAC1B,CAAC;IACH,CAAC;IACD,GAAG,CAAC,WAAW,GAAG,GAAG,CAAC,WAAW,GAAG,GAAG,CAAC,YAAY,GAAG,GAAG,CAAC,cAAc,CAAC;IAC1E,OAAO,GAAG,CAAC;AACb,CAAC;AAED,wEAAwE;AACxE,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,MAAiC;IAClE,MAAM,GAAG,GAAG,YAAY,EAAE,CAAC;IAC3B,IAAI,KAAK,EAAE,MAAM,EAAE,IAAI,MAAM,EAAE,CAAC;QAC9B,IAAI,EAAE,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;YACvB,MAAM,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC;YAClB,GAAG,CAAC,QAAQ,IAAI,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC;YAChC,GAAG,CAAC,WAAW,IAAI,CAAC,CAAC,WAAW,IAAI,CAAC,CAAC;YACtC,GAAG,CAAC,YAAY,IAAI,CAAC,CAAC,YAAY,IAAI,CAAC,CAAC;YACxC,GAAG,CAAC,cAAc,IAAI,CAAC,CAAC,cAAc,IAAI,CAAC,CAAC;YAC5C,GAAG,CAAC,YAAY,IAAI,CAAC,CAAC,YAAY,IAAI,CAAC,CAAC;YACxC,GAAG,CAAC,cAAc,IAAI,CAAC,CAAC;QAC1B,CAAC;IACH,CAAC;IACD,GAAG,CAAC,WAAW,GAAG,GAAG,CAAC,WAAW,GAAG,GAAG,CAAC,YAAY,GAAG,GAAG,CAAC,cAAc,CAAC;IAC1E,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;GAGG;AACH,MAAM,SAAS,CAAC,CAAC,YAAY,CAC3B,MAA4B,EAC5B,IAAO;IAEP,KAAK,MAAM,EAAE,IAAI,MAAM,EAAE,CAAC;QACxB,IAAI,EAAE,CAAC,IAAI,KAAK,IAAI;YAAE,MAAM,EAAsC,CAAC;IACrE,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,SAAS,CAAC,CAAC,iBAAiB,CACtC,MAAiC,EACjC,IAAO;IAEP,IAAI,KAAK,EAAE,MAAM,EAAE,IAAI,MAAM,EAAE,CAAC;QAC9B,IAAI,EAAE,CAAC,IAAI,KAAK,IAAI;YAAE,MAAM,EAAsC,CAAC;IACrE,CAAC;AACH,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Error hierarchy for @a5c-ai/agent-mux.
+ *
+ * All errors extend the base AgentMuxError.
+ */
+import type { AgentName, ErrorCode, ValidationFieldError } from './types.js';
+/**
+ * Base error class for all agent-mux errors.
+ * Provides a machine-readable `code` and a `recoverable` flag.
+ */
+export declare class AgentMuxError extends Error {
+    /** Machine-readable error code. */
+    readonly code: ErrorCode;
+    /** Whether the operation can be retried. */
+    readonly recoverable: boolean;
+    constructor(code: ErrorCode, message: string, recoverable?: boolean);
+}
+/**
+ * Thrown when a RunOptions field or API call requires a capability that
+ * the target agent or model does not support.
+ */
+export declare class CapabilityError extends AgentMuxError {
+    /** The agent that lacks the capability. */
+    readonly agent: AgentName;
+    /** The capability that was requested. */
+    readonly capability: string;
+    /** The model that was targeted, if applicable. */
+    readonly model?: string;
+    constructor(agent: AgentName, capability: string, model?: string);
+}
+/**
+ * Thrown when input values fail schema or range validation.
+ */
+export declare class ValidationError extends AgentMuxError {
+    /** The field(s) that failed validation. */
+    readonly fields: ValidationFieldError[];
+    constructor(fields: ValidationFieldError[]);
+}
+/**
+ * Thrown when an agent's authentication state prevents the requested operation.
+ */
+export declare class AuthError extends AgentMuxError {
+    /** The agent with the auth problem. */
+    readonly agent: AgentName;
+    /** Current auth status. */
+    readonly status: 'unauthenticated' | 'expired' | 'unknown';
+    /** Human-readable guidance on how to authenticate. */
+    readonly guidance: string;
+    constructor(agent: AgentName, status: AuthError['status'], guidance: string);
+}

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAM7E;;;GAGG;AACH,qBAAa,aAAc,SAAQ,KAAK;IACtC,mCAAmC;IACnC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAEzB,4CAA4C;IAC5C,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;gBAElB,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,GAAE,OAAe;CAM3E;AAMD;;;GAGG;AACH,qBAAa,eAAgB,SAAQ,aAAa;IAChD,2CAA2C;IAC3C,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAE1B,yCAAyC;IACzC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B,kDAAkD;IAClD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;gBAEZ,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM;CAYjE;AAMD;;GAEG;AACH,qBAAa,eAAgB,SAAQ,aAAa;IAChD,2CAA2C;IAC3C,QAAQ,CAAC,MAAM,EAAE,oBAAoB,EAAE,CAAC;gBAE5B,MAAM,EAAE,oBAAoB,EAAE;CAM3C;AAMD;;GAEG;AACH,qBAAa,SAAU,SAAQ,aAAa;IAC1C,uCAAuC;IACvC,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAE1B,2BAA2B;IAC3B,QAAQ,CAAC,MAAM,EAAE,iBAAiB,GAAG,SAAS,GAAG,SAAS,CAAC;IAE3D,sDAAsD;IACtD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAGxB,KAAK,EAAE,SAAS,EAChB,MAAM,EAAE,SAAS,CAAC,QAAQ,CAAC,EAC3B,QAAQ,EAAE,MAAM;CAYnB"}

package/dist/errors.js

@@ -0,0 +1,85 @@
+/**
+ * Error hierarchy for @a5c-ai/agent-mux.
+ *
+ * All errors extend the base AgentMuxError.
+ */
+// ---------------------------------------------------------------------------
+// AgentMuxError — Base (§3.1)
+// ---------------------------------------------------------------------------
+/**
+ * Base error class for all agent-mux errors.
+ * Provides a machine-readable `code` and a `recoverable` flag.
+ */
+export class AgentMuxError extends Error {
+    /** Machine-readable error code. */
+    code;
+    /** Whether the operation can be retried. */
+    recoverable;
+    constructor(code, message, recoverable = false) {
+        super(message);
+        this.name = 'AgentMuxError';
+        this.code = code;
+        this.recoverable = recoverable;
+    }
+}
+// ---------------------------------------------------------------------------
+// CapabilityError (§3.2)
+// ---------------------------------------------------------------------------
+/**
+ * Thrown when a RunOptions field or API call requires a capability that
+ * the target agent or model does not support.
+ */
+export class CapabilityError extends AgentMuxError {
+    /** The agent that lacks the capability. */
+    agent;
+    /** The capability that was requested. */
+    capability;
+    /** The model that was targeted, if applicable. */
+    model;
+    constructor(agent, capability, model) {
+        const modelSuffix = model ? ` (model: ${model})` : '';
+        super('CAPABILITY_ERROR', `Agent "${agent}" does not support capability "${capability}"${modelSuffix}`, false);
+        this.name = 'CapabilityError';
+        this.agent = agent;
+        this.capability = capability;
+        this.model = model;
+    }
+}
+// ---------------------------------------------------------------------------
+// ValidationError (§3.3)
+// ---------------------------------------------------------------------------
+/**
+ * Thrown when input values fail schema or range validation.
+ */
+export class ValidationError extends AgentMuxError {
+    /** The field(s) that failed validation. */
+    fields;
+    constructor(fields) {
+        const summary = fields.map((f) => `${f.field}: ${f.message}`).join('; ');
+        super('VALIDATION_ERROR', `Validation failed: ${summary}`, false);
+        this.name = 'ValidationError';
+        this.fields = fields;
+    }
+}
+// ---------------------------------------------------------------------------
+// AuthError (§3.4)
+// ---------------------------------------------------------------------------
+/**
+ * Thrown when an agent's authentication state prevents the requested operation.
+ */
+export class AuthError extends AgentMuxError {
+    /** The agent with the auth problem. */
+    agent;
+    /** Current auth status. */
+    status;
+    /** Human-readable guidance on how to authenticate. */
+    guidance;
+    constructor(agent, status, guidance) {
+        super('AUTH_ERROR', `Agent "${agent}" authentication failed (${status}): ${guidance}`, false);
+        this.name = 'AuthError';
+        this.agent = agent;
+        this.status = status;
+        this.guidance = guidance;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,8EAA8E;AAC9E,8BAA8B;AAC9B,8EAA8E;AAE9E;;;GAGG;AACH,MAAM,OAAO,aAAc,SAAQ,KAAK;IACtC,mCAAmC;IAC1B,IAAI,CAAY;IAEzB,4CAA4C;IACnC,WAAW,CAAU;IAE9B,YAAY,IAAe,EAAE,OAAe,EAAE,cAAuB,KAAK;QACxE,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;IACjC,CAAC;CACF;AAED,8EAA8E;AAC9E,yBAAyB;AACzB,8EAA8E;AAE9E;;;GAGG;AACH,MAAM,OAAO,eAAgB,SAAQ,aAAa;IAChD,2CAA2C;IAClC,KAAK,CAAY;IAE1B,yCAAyC;IAChC,UAAU,CAAS;IAE5B,kDAAkD;IACzC,KAAK,CAAU;IAExB,YAAY,KAAgB,EAAE,UAAkB,EAAE,KAAc;QAC9D,MAAM,WAAW,GAAG,KAAK,CAAC,CAAC,CAAC,YAAY,KAAK,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;QACtD,KAAK,CACH,kBAAkB,EAClB,UAAU,KAAK,kCAAkC,UAAU,IAAI,WAAW,EAAE,EAC5E,KAAK,CACN,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;QAC9B,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;CACF;AAED,8EAA8E;AAC9E,yBAAyB;AACzB,8EAA8E;AAE9E;;GAEG;AACH,MAAM,OAAO,eAAgB,SAAQ,aAAa;IAChD,2CAA2C;IAClC,MAAM,CAAyB;IAExC,YAAY,MAA8B;QACxC,MAAM,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACzE,KAAK,CAAC,kBAAkB,EAAE,sBAAsB,OAAO,EAAE,EAAE,KAAK,CAAC,CAAC;QAClE,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;QAC9B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF;AAED,8EAA8E;AAC9E,mBAAmB;AACnB,8EAA8E;AAE9E;;GAEG;AACH,MAAM,OAAO,SAAU,SAAQ,aAAa;IAC1C,uCAAuC;IAC9B,KAAK,CAAY;IAE1B,2BAA2B;IAClB,MAAM,CAA4C;IAE3D,sDAAsD;IAC7C,QAAQ,CAAS;IAE1B,YACE,KAAgB,EAChB,MAA2B,EAC3B,QAAgB;QAEhB,KAAK,CACH,YAAY,EACZ,UAAU,KAAK,4BAA4B,MAAM,MAAM,QAAQ,EAAE,EACjE,KAAK,CACN,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;QACxB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;CACF"}