@roj-ai/sdk 0.0.2

package/dist/core/agents/agent.d.ts

@@ -0,0 +1,234 @@
+/**
+ * Agent - OOP wrapper for agent orchestration.
+ *
+ * Responsibilities:
+ * - Process mailbox (inference + tool execution loop)
+ * - Embedded scheduling with debounce
+ * - Spawn child agents
+ */
+import z from 'zod/v4';
+import { DebounceCallback } from '../../core/agents/debounce.js';
+import type { AgentId } from '../../core/agents/schema.js';
+import type { AgentState } from '../../core/agents/state.js';
+import type { FileStore } from '../../core/file-store/types.js';
+import type { LLMProvider } from '../../core/llm/provider.js';
+import { ModelId } from '../../core/llm/schema.js';
+import type { AgentPluginConfig, ConfiguredPlugin, PluginMethodCaller, PluginNotification } from '../../core/plugins/plugin-builder.js';
+import type { ToolDefinition } from '../../core/tools/definition.js';
+import type { Logger } from '../../lib/logger/logger.js';
+import type { SessionContext } from '../sessions/context.js';
+import type { SessionStore } from '../sessions/session-store.js';
+import type { SessionEnvironment, ToolExecutor } from '../tools';
+/**
+ * Agent configuration - includes both behavior and debounce settings.
+ */
+export interface AgentConfig<TInput = unknown> {
+    systemPrompt: string;
+    model: ModelId;
+    spawnableAgents: string[];
+    /** Preset-level static tools (merged with plugin tools at runtime) */
+    tools?: ToolDefinition<any>[];
+    /** Debounce time in ms before processing agent mailbox. Default: 500ms */
+    debounceMs?: number;
+    /** Optional callback to determine when to process */
+    debounceCallback?: DebounceCallback;
+    /** Interval in ms for checking debounce callback (default: 100) */
+    checkIntervalMs?: number;
+    /** Optional Zod schema for typed agent input validation */
+    input?: z.ZodType<TInput>;
+    /** Per-plugin agent-level configs */
+    plugins?: AgentPluginConfig[];
+}
+/**
+ * Dependencies for creating an Agent.
+ */
+export interface AgentDependencies {
+    id: AgentId;
+    sessionContext: SessionContext;
+    store: SessionStore;
+    llmProvider: LLMProvider;
+    /** Named provider instances, passed to InferenceContext for middleware routing */
+    llmProviders?: ReadonlyMap<string, LLMProvider>;
+    toolExecutor: ToolExecutor;
+    logger: Logger;
+    config: AgentConfig;
+    plugins: ConfiguredPlugin[];
+    /** Session environment directories for tool context */
+    environment: SessionEnvironment;
+    /** FileStore for resolving agent-visible file:// paths (used by LLM provider) */
+    fileStore: FileStore;
+    /** Plugin contexts created by session-level initPluginContexts(), keyed by plugin name */
+    pluginContexts?: ReadonlyMap<string, unknown>;
+    /** Callback for sending plugin notifications directly to transport */
+    sendNotification?: (notification: PluginNotification) => void;
+    /** Callback for resolving cross-plugin method calls (delegates to session) */
+    pluginMethodCaller?: PluginMethodCaller;
+    /** Callback for scheduling this agent for processing */
+    schedule?: () => void;
+}
+/**
+ * Agent handles mailbox processing, inference, and tool execution.
+ *
+ * Features:
+ * - Debounced processing (timer or callback-based)
+ * - LLM inference with retry
+ * - Context compaction
+ * - Tool execution
+ */
+export declare class Agent {
+    readonly id: AgentId;
+    private readonly config;
+    private readonly sessionContext;
+    private readonly store;
+    private readonly logger;
+    private readonly llmProvider;
+    private readonly llmProviders;
+    private readonly toolExecutor;
+    private readonly plugins;
+    private readonly environment;
+    private readonly fileStore;
+    private readonly pluginContexts;
+    private readonly sendNotification?;
+    private readonly pluginMethodCaller?;
+    private readonly scheduleCallback?;
+    /** Merged tools map: config tools + plugin tools (plugins override). Rebuilt each processing cycle. */
+    private tools;
+    private debounceTimer?;
+    private processing;
+    private scheduled;
+    private pendingReschedule;
+    private readonly abortController;
+    /** Track conversation turn number for handler context */
+    private turnNumber;
+    constructor(deps: AgentDependencies);
+    /**
+     * Get the current agent state from store.
+     */
+    get state(): AgentState | null;
+    /**
+     * Unified processing entry point - decides what to do next.
+     * Safe to call multiple times; skips if already processing.
+     */
+    continue(): Promise<void>;
+    /**
+     * Schedule processing with debounce.
+     * Use this when receiving new messages or after tool execution.
+     */
+    scheduleProcessing(): void;
+    /**
+     * Shutdown the agent - cancel any scheduled processing.
+     */
+    shutdown(): void;
+    /**
+     * Check if processing is scheduled.
+     */
+    isScheduled(): boolean;
+    /**
+     * Determine the next action based on current agent state.
+     */
+    private decide;
+    private static readonly MAX_INFERENCE_RETRIES;
+    /**
+     * Run inference on agent's mailbox.
+     * Runs when there are unconsumed messages OR pending tool results.
+     */
+    private runInference;
+    /**
+     * Emit inference_completed event.
+     */
+    private emitInferenceCompleted;
+    /**
+     * Cancel any scheduled processing.
+     */
+    private cancelSchedule;
+    /**
+     * Execute a single tool call.
+     */
+    private executeToolCall;
+    /**
+     * Emit agent_paused event with reason 'handler'.
+     */
+    private emitHandlerPause;
+    /**
+     * Build base AgentContext for handler/hook calls.
+     */
+    private buildAgentContext;
+    /**
+     * Build PluginHookContext for a specific plugin.
+     * Adds pluginConfig, pluginAgentConfig, pluginContext, pluginState, self.
+     */
+    private buildPluginHookContext;
+    /**
+     * Emit handler_completed event.
+     *
+     * Skipped when the handler produced no action (null result) — those events are
+     * pure noise (64%+ of a typical session log). onStart is the one exception: the
+     * reducer uses its completion event to flip `onStartCalled`, so we always emit
+     * it even with a null result.
+     */
+    private emitHandlerCompleted;
+    /**
+     * Execute onStart handler - called once on first inference.
+     */
+    private executeOnStart;
+    /**
+     * Execute beforeInference handler.
+     */
+    private executeBeforeInference;
+    /**
+     * Execute afterInference handler.
+     */
+    private executeAfterInference;
+    /**
+     * Execute beforeToolCall handler.
+     */
+    private executeBeforeToolCall;
+    /**
+     * Execute afterToolCall handler.
+     */
+    private executeAfterToolCall;
+    /**
+     * Execute onComplete handler.
+     */
+    private executeOnComplete;
+    /**
+     * Execute onError handler.
+     */
+    private executeOnError;
+    /**
+     * Build pending messages from tool results.
+     * Mailbox messages are handled by the mailbox plugin's dequeue mechanism.
+     */
+    private buildPendingMessages;
+    /**
+     * Build LLM messages from agent state and pending messages.
+     * Order: [preamble, conversation history, pending messages]
+     * - Preamble is never compacted (includes skills injected by plugin)
+     * - Conversation history may be compacted
+     * - Pending messages are ephemeral (for current turn)
+     */
+    private buildLLMMessages;
+    /**
+     * Build merged tools map from config (preset-level) and plugin tools.
+     * Plugin tools override config tools with the same name.
+     */
+    private buildToolsMap;
+    /**
+     * Build composed system prompt from base briefing, plugin sections, environment, and preset prompt.
+     */
+    private buildSystemPrompt;
+    /**
+     * Get combined status from all plugins.
+     */
+    private getPluginStatus;
+    /**
+     * Check if any plugin has pending messages for this agent.
+     */
+    private hasPluginPendingMessages;
+    /**
+     * Collect pending messages from all plugins that have dequeue hooks.
+     * Returns array of { plugin, messages, token } for each plugin with pending messages.
+     */
+    private collectPluginMessages;
+}
+//# sourceMappingURL=agent.d.ts.map

package/dist/core/agents/agent.d.ts.map

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

package/dist/core/agents/agent.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=agent.test.d.ts.map

package/dist/core/agents/agent.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.test.d.ts","sourceRoot":"","sources":["../../../src/core/agents/agent.test.ts"],"names":[],"mappings":""}

package/dist/core/agents/communicator.d.ts

@@ -0,0 +1,3 @@
+import type { AgentDefinition, CommunicatorConfig } from './config.js';
+export declare function createCommunicatorDefinition(config: CommunicatorConfig): AgentDefinition;
+//# sourceMappingURL=communicator.d.ts.map

package/dist/core/agents/communicator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"communicator.d.ts","sourceRoot":"","sources":["../../../src/core/agents/communicator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAEtE,wBAAgB,4BAA4B,CAC3C,MAAM,EAAE,kBAAkB,GACxB,eAAe,CAWjB"}

package/dist/core/agents/config.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Agent configuration types for Roj presets
+ */
+import z from 'zod/v4';
+import type { DebounceCallback } from '../../core/agents/debounce.js';
+import type { LLMMiddleware } from '../../core/llm/middleware.js';
+import { ModelId } from '../../core/llm/schema.js';
+import type { AgentPluginConfig } from '../../core/plugins/plugin-builder.js';
+import type { ToolDefinition } from '../../core/tools';
+import type { ServiceConfig } from '../../plugins/services/schema.js';
+/**
+ * User communication mode for agents.
+ * - 'tool': Use tell_user/ask_user tools only (default)
+ * - 'xml': Use <user> tags in response content
+ * - 'both': Support both tools and <user> tags
+ */
+export type UserCommunicationMode = 'tool' | 'xml' | 'both';
+/**
+ * Base configuration shared by all agent types.
+ */
+export interface BaseAgentConfig<TInput = unknown> {
+    /** System prompt for the agent */
+    system: string;
+    /** LLM model for this agent */
+    model: ModelId;
+    /** Available tools for the agent */
+    tools?: ToolDefinition<any>[];
+    /** Names of agents this agent can spawn */
+    agents?: string[];
+    /** Per-plugin agent-level configs */
+    plugins?: AgentPluginConfig[];
+    /** Debounce time in ms before processing mailbox. Default: 500ms */
+    debounceMs?: number;
+    /** Custom debounce callback for dynamic processing decisions */
+    debounceCallback?: DebounceCallback;
+    /** Interval in ms for checking debounce callback (default: 100) */
+    checkIntervalMs?: number;
+    /** User communication mode. Default: 'tool' */
+    userCommunication?: UserCommunicationMode;
+    /** Optional Zod schema for typed agent input validation */
+    input?: z.ZodType<TInput>;
+    /** Service configurations for this agent (auto-wired to services plugin) */
+    services?: ServiceConfig[];
+    /** LLM middleware chain applied per-agent (runs after preset-level middleware) */
+    llmMiddleware?: LLMMiddleware[];
+}
+/**
+ * Agent definition - configuration for a spawnable agent.
+ * Extends BaseAgentConfig with a name field.
+ */
+export interface AgentDefinition<TInput = unknown> extends BaseAgentConfig<TInput> {
+    name: string;
+}
+/**
+ * Agent definition for use in Preset arrays.
+ * Uses 'any' to allow mixing typed and untyped agents in the same array.
+ */
+export type AnyAgentDefinition = AgentDefinition<any>;
+/**
+ * Orchestrator configuration - same as BaseAgentConfig.
+ */
+export type OrchestratorConfig<TInput = unknown> = BaseAgentConfig<TInput>;
+/**
+ * Response format preferences for communicator
+ */
+export interface ResponseFormat {
+    /** Preferred language */
+    language?: string;
+    /** Tone (formal, casual, friendly, professional) */
+    tone?: 'formal' | 'casual' | 'friendly' | 'professional';
+    /** Include thinking/reasoning in responses */
+    showReasoning?: boolean;
+    /** Maximum response length hint */
+    maxLengthHint?: number;
+}
+/**
+ * Communicator configuration (optional communication agent).
+ * Extends base config with optional tools (defaults provided) and response format.
+ */
+export interface CommunicatorConfig extends BaseAgentConfig {
+    /** Response format preferences (communicator-specific) */
+    responseFormat?: ResponseFormat;
+}
+//# sourceMappingURL=config.d.ts.map

package/dist/core/agents/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/core/agents/config.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,CAAC,MAAM,QAAQ,CAAA;AACtB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAA;AACjE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAA;AAC7D,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAA;AAC9C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAA;AACzE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAClD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAA;AAMjE;;;;;GAKG;AACH,MAAM,MAAM,qBAAqB,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,CAAA;AAE3D;;GAEG;AACH,MAAM,WAAW,eAAe,CAAC,MAAM,GAAG,OAAO;IAChD,kCAAkC;IAClC,MAAM,EAAE,MAAM,CAAA;IACd,+BAA+B;IAC/B,KAAK,EAAE,OAAO,CAAA;IAGd,oCAAoC;IACpC,KAAK,CAAC,EAAE,cAAc,CAAC,GAAG,CAAC,EAAE,CAAA;IAC7B,2CAA2C;IAC3C,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;IACjB,qCAAqC;IACrC,OAAO,CAAC,EAAE,iBAAiB,EAAE,CAAA;IAC7B,oEAAoE;IACpE,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,gEAAgE;IAChE,gBAAgB,CAAC,EAAE,gBAAgB,CAAA;IACnC,mEAAmE;IACnE,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,+CAA+C;IAC/C,iBAAiB,CAAC,EAAE,qBAAqB,CAAA;IACzC,2DAA2D;IAC3D,KAAK,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAA;IACzB,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,aAAa,EAAE,CAAA;IAC1B,kFAAkF;IAClF,aAAa,CAAC,EAAE,aAAa,EAAE,CAAA;CAC/B;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe,CAAC,MAAM,GAAG,OAAO,CAAE,SAAQ,eAAe,CAAC,MAAM,CAAC;IACjF,IAAI,EAAE,MAAM,CAAA;CACZ;AAED;;;GAGG;AAEH,MAAM,MAAM,kBAAkB,GAAG,eAAe,CAAC,GAAG,CAAC,CAAA;AAErD;;GAEG;AACH,MAAM,MAAM,kBAAkB,CAAC,MAAM,GAAG,OAAO,IAAI,eAAe,CAAC,MAAM,CAAC,CAAA;AAE1E;;GAEG;AACH,MAAM,WAAW,cAAc;IAC9B,yBAAyB;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,oDAAoD;IACpD,IAAI,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,UAAU,GAAG,cAAc,CAAA;IACxD,8CAA8C;IAC9C,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,mCAAmC;IACnC,aAAa,CAAC,EAAE,MAAM,CAAA;CACtB;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAmB,SAAQ,eAAe;IAC1D,0DAA0D;IAC1D,cAAc,CAAC,EAAE,cAAc,CAAA;CAC/B"}

package/dist/core/agents/context.d.ts

@@ -0,0 +1,16 @@
+import { SessionContext } from '../sessions/context';
+import { AgentConfig } from './agent';
+import { AgentId } from './schema';
+import { AgentState } from './state';
+export type AgentContext<TInput = unknown> = SessionContext & {
+    /** The agent's ID */
+    agentId: AgentId;
+    /** The agent's current state */
+    agentState: AgentState;
+    agentConfig: AgentConfig;
+    /** The typed input if agent has inputSchema, otherwise the task string */
+    input: TInput;
+    /** The parent agent ID (null for root agents) */
+    parentId: AgentId | null;
+};
+//# sourceMappingURL=context.d.ts.map

package/dist/core/agents/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../../src/core/agents/context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAA;AAClC,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AAEpC,MAAM,MAAM,YAAY,CAAC,MAAM,GAAG,OAAO,IACtC,cAAc,GACd;IACD,qBAAqB;IACrB,OAAO,EAAE,OAAO,CAAA;IAChB,gCAAgC;IAChC,UAAU,EAAE,UAAU,CAAA;IAEtB,WAAW,EAAE,WAAW,CAAA;IACxB,0EAA0E;IAC1E,KAAK,EAAE,MAAM,CAAA;IACb,iDAAiD;IACjD,QAAQ,EAAE,OAAO,GAAG,IAAI,CAAA;CACxB,CAAA"}

package/dist/core/agents/debounce.d.ts

@@ -0,0 +1,52 @@
+import { MailboxMessage } from '../../plugins/mailbox/schema';
+import { PendingToolResult } from '../tools/schema';
+/**
+ * Context provided to debounce callback for decision making.
+ */
+export interface DebounceContext {
+    /** Unconsumed messages waiting in the mailbox */
+    messages: MailboxMessage[];
+    /** How long the oldest message has been waiting (ms) */
+    oldestWaitingMs: number;
+    /** Total number of pending messages */
+    totalPending: number;
+    /** Pending tool results awaiting LLM processing */
+    pendingToolResults: PendingToolResult[];
+}
+/**
+ * Decision returned by debounce callback.
+ */
+export type DebounceDecision = 'process_now' | 'wait';
+/**
+ * Callback function for dynamic debounce decisions.
+ * Called periodically to decide whether to process agent mailbox.
+ * Async to allow for external checks (e.g., rate limiting, external state).
+ */
+export type DebounceCallback = (context: DebounceContext) => DebounceDecision | Promise<DebounceDecision>;
+/**
+ * Default debounce callback - process after 500ms wait.
+ */
+export declare const defaultDebounceCallback: DebounceCallback;
+/**
+ * Aggressive debounce callback - process quickly after 100ms.
+ */
+export declare const aggressiveDebounceCallback: DebounceCallback;
+/**
+ * Batching debounce callback - wait for multiple messages or timeout.
+ * Processes when 5+ messages accumulated or after 2s wait.
+ */
+export declare const batchingDebounceCallback: DebounceCallback;
+/**
+ * Wait-for-response debounce callback - waits for response after communication tools.
+ * Used by child agents that should wait after sending messages instead of
+ * immediately calling LLM with a "WAITING" response.
+ *
+ * Behavior:
+ * - If new mailbox messages arrived, process immediately
+ * - If ANY tool result has isError=true, process immediately (error recovery)
+ * - If ALL pending tool results are from communication tools (send_message, start_*, etc.),
+ *   wait up to 60s for a response before processing
+ * - If ANY tool result is NOT a communication tool, process immediately
+ */
+export declare const waitForResponseDebounceCallback: DebounceCallback;
+//# sourceMappingURL=debounce.d.ts.map

package/dist/core/agents/debounce.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debounce.d.ts","sourceRoot":"","sources":["../../../src/core/agents/debounce.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAA;AAC7D,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAA;AAEnD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC/B,iDAAiD;IACjD,QAAQ,EAAE,cAAc,EAAE,CAAA;IAC1B,wDAAwD;IACxD,eAAe,EAAE,MAAM,CAAA;IACvB,uCAAuC;IACvC,YAAY,EAAE,MAAM,CAAA;IACpB,mDAAmD;IACnD,kBAAkB,EAAE,iBAAiB,EAAE,CAAA;CACvC;AAED;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,aAAa,GAAG,MAAM,CAAA;AAErD;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,EAAE,eAAe,KAAK,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAA;AAMzG;;GAEG;AACH,eAAO,MAAM,uBAAuB,EAAE,gBAKrC,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,0BAA0B,EAAE,gBAKxC,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,wBAAwB,EAAE,gBAKtC,CAAA;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,+BAA+B,EAAE,gBAuC7C,CAAA"}

package/dist/core/agents/handler-events.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Tests for handler-related event handling in session state
+ */
+export {};
+//# sourceMappingURL=handler-events.test.d.ts.map

package/dist/core/agents/handler-events.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler-events.test.d.ts","sourceRoot":"","sources":["../../../src/core/agents/handler-events.test.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/core/agents/index.d.ts

@@ -0,0 +1,2 @@
+export * from './schema.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/agents/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/agents/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAA"}

package/dist/core/agents/response-sanitizer.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Response sanitization utilities for LLM outputs.
+ *
+ * Prevents hallucination by:
+ * - Truncating at <message tags (system-generated only)
+ * - Truncating after WAITING signal
+ */
+/**
+ * Result of sanitizing an LLM response.
+ */
+export interface SanitizedResponse {
+    /** Sanitized content (truncated at message tags, WAITING) */
+    content: string | null;
+    /** Whether the response was truncated */
+    wasTruncated: boolean;
+}
+/**
+ * Sanitize LLM response content to prevent hallucination.
+ * - Truncates at any `<message` tag (LLM should not generate these)
+ * - Truncates content after `WAITING` signal
+ *
+ * @param content - Raw LLM response content
+ */
+export declare function sanitizeLLMResponse(content: string | null): SanitizedResponse;
+//# sourceMappingURL=response-sanitizer.d.ts.map

package/dist/core/agents/response-sanitizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"response-sanitizer.d.ts","sourceRoot":"","sources":["../../../src/core/agents/response-sanitizer.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH;;GAEG;AACH,MAAM,WAAW,iBAAiB;IACjC,6DAA6D;IAC7D,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,yCAAyC;IACzC,YAAY,EAAE,OAAO,CAAA;CACrB;AAMD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAClC,OAAO,EAAE,MAAM,GAAG,IAAI,GACpB,iBAAiB,CA+BnB"}

package/dist/core/agents/response-sanitizer.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=response-sanitizer.test.d.ts.map

package/dist/core/agents/response-sanitizer.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"response-sanitizer.test.d.ts","sourceRoot":"","sources":["../../../src/core/agents/response-sanitizer.test.ts"],"names":[],"mappings":""}

package/dist/core/agents/retry.d.ts

@@ -0,0 +1,40 @@
+import type { LLMError } from '../../core/llm/provider.js';
+import type { Result } from '../../lib/utils/result.js';
+import type { Logger } from '../../lib/logger/logger.js';
+export interface RetryOptions {
+    maxAttempts?: number;
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+}
+export declare const DEFAULT_RETRY_OPTIONS: Required<RetryOptions>;
+export interface WithRetryOptions<E> extends RetryOptions {
+    isRetryable: (error: E) => boolean;
+    getRetryDelay?: (error: E) => number | undefined;
+    /** Error to return when aborted before first attempt */
+    abortError?: E;
+    logger?: Logger;
+    context?: string;
+    signal?: AbortSignal;
+}
+/**
+ * Generic retry wrapper with exponential backoff.
+ */
+export declare function withRetry<T, E>(fn: () => Promise<Result<T, E>>, options: WithRetryOptions<E>): Promise<Result<T, E>>;
+/**
+ * Determines if an LLM error is retryable.
+ * Retryable: rate_limit, server_error, network_error, timeout
+ * Non-retryable: invalid_request, context_length (permanent failures)
+ */
+export declare function isRetryableLLMError(error: LLMError): boolean;
+/**
+ * Gets retry delay from LLM error if available (e.g., rate limit retry-after).
+ */
+export declare function getLLMRetryDelay(error: LLMError): number | undefined;
+/**
+ * Convenience wrapper for LLM inference with retry.
+ */
+export declare function withLLMRetry<T>(fn: () => Promise<Result<T, LLMError>>, options?: RetryOptions & {
+    logger?: Logger;
+    signal?: AbortSignal;
+}): Promise<Result<T, LLMError>>;
+//# sourceMappingURL=retry.d.ts.map

package/dist/core/agents/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../../src/core/agents/retry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAA;AACtD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAA;AAEnD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAA;AAMxD,MAAM,WAAW,YAAY;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,UAAU,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,eAAO,MAAM,qBAAqB,EAAE,QAAQ,CAAC,YAAY,CAIxD,CAAA;AAMD,MAAM,WAAW,gBAAgB,CAAC,CAAC,CAAE,SAAQ,YAAY;IACxD,WAAW,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,OAAO,CAAA;IAClC,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,MAAM,GAAG,SAAS,CAAA;IAChD,wDAAwD;IACxD,UAAU,CAAC,EAAE,CAAC,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,MAAM,CAAC,EAAE,WAAW,CAAA;CACpB;AAED;;GAEG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAAE,CAAC,EACnC,EAAE,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAC/B,OAAO,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAC1B,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAoDvB;AAsCD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAI5D;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM,GAAG,SAAS,CAEpE;AAED;;GAEG;AACH,wBAAsB,YAAY,CAAC,CAAC,EACnC,EAAE,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,EACtC,OAAO,CAAC,EAAE,YAAY,GAAG;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAAE,GAChE,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,CAQ9B"}

package/dist/core/agents/schema.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Agent domain types and schemas
+ *
+ * Contains all types related to agents:
+ * - Branded ID type and constructor
+ * - Agent status types (domain and protocol)
+ * - Zod schemas for validation
+ */
+import z from 'zod/v4';
+/** AgentId schema - validates any string and brands as AgentId. */
+export declare const agentIdSchema: z.core.$ZodBranded<z.ZodString, "AgentId", "out">;
+/** Branded AgentId type */
+export type AgentId = z.infer<typeof agentIdSchema>;
+/** Constructor for AgentId */
+export declare const AgentId: (id: string) => AgentId;
+/**
+ * Generate a short agent ID based on definition name and sequence number.
+ * Format: {definitionName}_{seq} e.g., "orchestrator_1", "planner_2"
+ */
+export declare const generateAgentId: (definitionName: string, seq: number) => AgentId;
+/**
+ * Domain agent status - represents the internal state machine.
+ * Used by the agent runtime and event sourcing.
+ */
+export type AgentStatus = 'pending' | 'inferring' | 'tool_exec' | 'errored' | 'paused';
+/**
+ * Zod schema for domain agent status.
+ */
+export declare const agentStatusSchema: z.ZodEnum<{
+    errored: "errored";
+    pending: "pending";
+    inferring: "inferring";
+    tool_exec: "tool_exec";
+    paused: "paused";
+}>;
+/**
+ * Protocol agent status - represents the UI-friendly status.
+ * Maps from domain status for display in the SPA.
+ */
+export type ProtocolAgentStatus = 'idle' | 'thinking' | 'responding' | 'waiting_for_user' | 'error' | 'paused';
+/**
+ * Zod schema for protocol agent status.
+ */
+export declare const protocolAgentStatusSchema: z.ZodEnum<{
+    error: "error";
+    paused: "paused";
+    idle: "idle";
+    thinking: "thinking";
+    responding: "responding";
+    waiting_for_user: "waiting_for_user";
+}>;
+/**
+ * Generate a test agent ID (for tests only).
+ * Uses incrementing counter for uniqueness.
+ */
+export declare const generateTestAgentId: (definitionName?: string) => AgentId;
+//# sourceMappingURL=schema.d.ts.map

package/dist/core/agents/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/core/agents/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,CAAC,MAAM,QAAQ,CAAA;AAMtB,mEAAmE;AACnE,eAAO,MAAM,aAAa,mDAA8B,CAAA;AAExD,2BAA2B;AAC3B,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAA;AAEnD,8BAA8B;AAC9B,eAAO,MAAM,OAAO,GAAI,IAAI,MAAM,KAAG,OAAwB,CAAA;AAE7D;;;GAGG;AACH,eAAO,MAAM,eAAe,GAAI,gBAAgB,MAAM,EAAE,KAAK,MAAM,KAAG,OAA8C,CAAA;AAUpH;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,WAAW,GAAG,WAAW,GAAG,SAAS,GAAG,QAAQ,CAAA;AAEtF;;GAEG;AACH,eAAO,MAAM,iBAAiB;;;;;;EAAqE,CAAA;AAMnG;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,UAAU,GAAG,YAAY,GAAG,kBAAkB,GAAG,OAAO,GAAG,QAAQ,CAAA;AAE9G;;GAEG;AACH,eAAO,MAAM,yBAAyB;;;;;;;EAAoF,CAAA;AAQ1H;;;GAGG;AACH,eAAO,MAAM,mBAAmB,GAAI,uBAA6B,KAAG,OAAwD,CAAA"}