@roj-ai/sdk 0.0.2

package/dist/core/sessions/session.d.ts

@@ -0,0 +1,212 @@
+/**
+ * Session - OOP wrapper for session management.
+ *
+ * Responsibilities:
+ * - Factory for agents
+ * - User output callback
+ * - Plugin method aggregation
+ */
+import { AgentId } from '../../core/agents/schema.js';
+import { type DomainError } from '../../core/errors.js';
+import type { LLMLogger } from '../../core/llm/logger.js';
+import type { LLMProvider } from '../../core/llm/provider.js';
+import type { CallerContext, ConfiguredPlugin } from '../../core/plugins/plugin-builder.js';
+import { type PluginNotification } from '../../core/plugins/plugin-builder.js';
+import type { Preset } from '../../core/preset/index.js';
+import type { SessionId } from '../../core/sessions/schema.js';
+import type { SessionState } from '../../core/sessions/state.js';
+import type { Logger } from '../../lib/logger/logger.js';
+import type { Platform } from '../../platform/index.js';
+import type { Result } from '../../lib/utils/result.js';
+import { Agent } from '../agents/agent.js';
+import type { EventStore } from '../events/event-store.js';
+import type { ToolExecutor } from '../tools/executor.js';
+import { SessionStore } from './session-store.js';
+/**
+ * Callback for user-facing output.
+ * Receives plugin notifications that are broadcast to connected clients.
+ */
+export type UserOutputCallback = (notification: PluginNotification) => void;
+/**
+ * Dependencies for creating a Session.
+ */
+export interface SessionDependencies {
+    store: SessionStore;
+    preset: Preset;
+    llmProvider: LLMProvider;
+    /** Named provider instances for middleware routing */
+    llmProviders?: ReadonlyMap<string, LLMProvider>;
+    toolExecutor: ToolExecutor;
+    logger: Logger;
+    onUserOutput?: UserOutputCallback;
+    /** Absolute path to session directory */
+    sessionDir: string;
+    /** Configured plugins for this session */
+    plugins: ConfiguredPlugin[];
+    /** Event store for loading/querying events */
+    eventStore: EventStore;
+    /** LLM call logger for debugging and audit */
+    llmLogger?: LLMLogger;
+    /** Host-environment adapters (filesystem, process). */
+    platform: Platform;
+}
+/**
+ * Session manages agents and delegates everything else to plugins.
+ */
+export declare class Session {
+    readonly id: SessionId;
+    readonly store: SessionStore;
+    private readonly preset;
+    private readonly llmProvider;
+    private readonly llmProviders;
+    private readonly toolExecutor;
+    private readonly logger;
+    private readonly onUserOutput?;
+    private readonly sessionDir;
+    private readonly plugins;
+    private readonly eventStore;
+    private readonly llmLogger?;
+    private readonly platform;
+    private readonly agents;
+    /** Cached plugin contexts created by plugin.createContext() */
+    private readonly pluginContexts;
+    constructor(deps: SessionDependencies);
+    /**
+     * Get the current session state.
+     */
+    get state(): SessionState;
+    /**
+     * Get the preset configuration for this session.
+     */
+    getPreset(): Preset;
+    /**
+     * Get the entry agent ID (communicator if present, otherwise orchestrator).
+     */
+    getEntryAgentId(): AgentId | null;
+    /**
+     * Initialize plugin contexts.
+     * Must be called before session hooks or plugin methods that need pluginContext.
+     */
+    initPluginContexts(): Promise<void>;
+    /**
+     * Call onSessionReady hooks for all plugins (with full context).
+     *
+     * Only errors are persisted as events — successful runs produce no event
+     * to keep the session log focused on state changes, not invocation noise.
+     */
+    callSessionReadyHooks(): Promise<void>;
+    /**
+     * Close the session.
+     * Emits session_closed event — hooks and agent shutdown are handled reactively by handleSessionClosed().
+     */
+    close(): Promise<Result<void, DomainError>>;
+    /**
+     * Reopen a closed session.
+     */
+    reopen(): Promise<Result<void, DomainError>>;
+    /**
+     * Get an agent by ID.
+     */
+    getAgent(agentId: AgentId): Agent | null;
+    /**
+     * Get the entry agent (communicator or orchestrator).
+     */
+    getEntryAgent(): Agent | null;
+    /**
+     * Schedule agent processing (with debounce).
+     */
+    scheduleAgent(agentId: AgentId): void;
+    /**
+     * Force process an agent (bypass debounce).
+     */
+    forceProcessAgent(agentId: AgentId): Promise<void>;
+    /**
+     * Resume a paused agent so it can continue processing.
+     */
+    resumeAgent(agentId: AgentId): Promise<Result<void, DomainError>>;
+    /**
+     * Pause an agent manually via API.
+     */
+    pauseAgent(agentId: AgentId, message?: string): Promise<Result<void, DomainError>>;
+    /**
+     * Manually spawn an agent under a given parent.
+     */
+    spawnAgentManually(definitionName: string, parentId: AgentId, message?: string, typedInput?: unknown): Promise<Result<AgentId, DomainError>>;
+    /**
+     * Shutdown the session - stop all agent processing.
+     */
+    shutdown(): void;
+    /**
+     * Check if a session has any agents that need processing.
+     */
+    checkPendingAgents(): void;
+    /**
+     * Aggregate methods from all plugins.
+     * Returns a map of "pluginName.methodName" → { input, output, handler }.
+     */
+    getPluginMethods(): Map<string, ConfiguredPlugin['methods'][string]>;
+    /**
+     * Call a plugin method with properly constructed MethodHandlerContext.
+     * The context includes pluginState, pluginConfig (bound in closure),
+     * pluginContext, and scheduleAgent.
+     */
+    callPluginMethod(method: string, input: unknown, agentId?: AgentId, caller?: CallerContext): Promise<Result<unknown, DomainError>>;
+    /**
+     * Initialize agents from session state.
+     */
+    private initializeAgents;
+    /**
+     * Create an Agent instance from state.
+     */
+    private createAgent;
+    /**
+     * Handle events emitted to the store — reactive scheduling.
+     */
+    private handleStoreEvent;
+    /**
+     * Handle session_closed event — call close hooks and shutdown agents.
+     *
+     * Unlike onSessionReady (which re-throws), onSessionClose intentionally
+     * swallows per-plugin errors so that all plugins get a chance to clean up
+     * and agents are always shut down, even if one plugin's close hook fails.
+     */
+    private handleSessionClosed;
+    /**
+     * Handle newly spawned agent.
+     */
+    private handleAgentSpawned;
+    /**
+     * Handle user-facing output events.
+     */
+    /**
+     * Create a notify function bound to a specific plugin name.
+     */
+    private createNotify;
+    /**
+     * Build deps object for a plugin — delegates method calls to callPluginMethod.
+     */
+    private buildPluginDeps;
+    /**
+     * Build a SessionContext from current session state.
+     */
+    private buildSessionContext;
+    /**
+     * Build context for a session-level hook (onSessionReady / onSessionClose).
+     * Provides pluginConfig (via closure), pluginContext, pluginState, self, and session fields.
+     */
+    private buildSessionHookContext;
+    /**
+     * Get session environment for tool context.
+     */
+    private getSessionEnvironment;
+    /**
+     * Get LLM middleware from the agent/orchestrator/communicator definition.
+     */
+    private getAgentMiddleware;
+    /**
+     * Get agent config from preset definition.
+     * Tools are provided by plugins (Agent collects from plugins).
+     */
+    private getAgentConfig;
+}
+//# sourceMappingURL=session.d.ts.map

package/dist/core/sessions/session.d.ts.map

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

package/dist/core/sessions/session.test.d.ts

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

package/dist/core/sessions/session.test.d.ts.map

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

package/dist/core/sessions/state.d.ts

@@ -0,0 +1,110 @@
+import z4 from 'zod/v4';
+import type { AgentId } from '../../core/agents/schema.js';
+import type { DomainEvent } from '../../core/events/types.js';
+import { SessionId } from '../../core/sessions/schema.js';
+import type { ToolCallId } from '../../core/tools/schema.js';
+import type { AgentState } from '../agents/state.js';
+/**
+ * Session lifecycle hook name.
+ * These correspond to ConfiguredPlugin sessionHooks.
+ */
+export type SessionHandlerName = 'onSessionReady' | 'onSessionClose';
+export declare const sessionEvents: import("../../core/events/types").EventsFactory<{
+    session_created: z4.ZodObject<{
+        presetId: z4.ZodString;
+        workspaceDir: z4.ZodOptional<z4.ZodString>;
+        forkedFrom: z4.ZodOptional<z4.ZodObject<{
+            sessionId: z4.core.$ZodBranded<z4.ZodString, "SessionId", "out">;
+            eventIndex: z4.ZodNumber;
+        }, z4.core.$strip>>;
+    }, z4.core.$strip>;
+    session_closed: z4.ZodObject<{}, z4.core.$loose>;
+    session_reopened: z4.ZodObject<{}, z4.core.$loose>;
+    session_restarted: z4.ZodObject<{
+        resetAgentIds: z4.ZodArray<z4.core.$ZodBranded<z4.ZodString, "AgentId", "out">>;
+        clearedToolAgentIds: z4.ZodArray<z4.core.$ZodBranded<z4.ZodString, "AgentId", "out">>;
+    }, z4.core.$strip>;
+    session_metadata_set: z4.ZodObject<{
+        key: z4.ZodString;
+        value: z4.ZodUnknown;
+    }, z4.core.$strip>;
+    session_handler_started: z4.ZodObject<{
+        handlerName: z4.ZodEnum<{
+            onSessionReady: "onSessionReady";
+            onSessionClose: "onSessionClose";
+        }>;
+        pluginName: z4.ZodString;
+    }, z4.core.$strip>;
+    session_handler_completed: z4.ZodObject<{
+        handlerName: z4.ZodEnum<{
+            onSessionReady: "onSessionReady";
+            onSessionClose: "onSessionClose";
+        }>;
+        pluginName: z4.ZodString;
+        durationMs: z4.ZodNumber;
+        error: z4.ZodOptional<z4.ZodString>;
+    }, z4.core.$strip>;
+}>;
+export type SessionCreatedEvent = (typeof sessionEvents)['Events']['session_created'];
+export type SessionClosedEvent = (typeof sessionEvents)['Events']['session_closed'];
+export type SessionReopenedEvent = (typeof sessionEvents)['Events']['session_reopened'];
+export type SessionRestartedEvent = (typeof sessionEvents)['Events']['session_restarted'];
+export type SessionMetadataSetEvent = (typeof sessionEvents)['Events']['session_metadata_set'];
+export type SessionHandlerStartedEvent = (typeof sessionEvents)['Events']['session_handler_started'];
+export type SessionHandlerCompletedEvent = (typeof sessionEvents)['Events']['session_handler_completed'];
+/**
+ * Core session state.
+ *
+ * Plugin-owned fields (todos, workers, services, skills, agentLimits, etc.)
+ * are stored as dynamic keys managed by each plugin's state slice.
+ * Use `selectPluginState()` from reducer.ts to access them.
+ */
+export interface SessionState {
+    id: SessionId;
+    presetId: string;
+    status: 'active' | 'closed';
+    agents: Map<AgentId, AgentState>;
+    createdAt: number;
+    closedAt?: number;
+    /** Counter for agent IDs per definition name */
+    agentCounters: Map<string, number>;
+    /** Workspace directory path, if configured */
+    workspaceDir?: string;
+    /** Generic key-value metadata store (tool sets use their own keys) */
+    metadata: Map<string, unknown>;
+    /** If this session was forked from another session */
+    forkedFrom?: {
+        sessionId: SessionId;
+        eventIndex: number;
+    };
+}
+export declare const createSessionState: (id: SessionId, presetId: string, timestamp: number) => SessionState;
+interface ToolCall {
+    id: ToolCallId;
+    name: string;
+    input: unknown;
+}
+export declare const fromLLMToolCall: (tc: {
+    id: string;
+    name: string;
+    input: unknown;
+}) => ToolCall;
+export declare const fromLLMToolCalls: (llmToolCalls: Array<{
+    id: string;
+    name: string;
+    input: unknown;
+}>) => ToolCall[];
+export declare const coreReducer: import("./reducer.js").SessionReducer;
+export declare const isSessionCreatedEvent: (event: DomainEvent) => event is SessionCreatedEvent;
+export declare const reconstructSessionState: (events: DomainEvent[], reducer: (state: SessionState, event: DomainEvent) => SessionState) => SessionState | null;
+export declare const checkRecoveryNeeded: (state: SessionState) => {
+    resetAgentIds: AgentId[];
+    clearedToolAgentIds: AgentId[];
+} | null;
+export declare const getOrchestratorId: (state: SessionState) => AgentId | null;
+export declare const getCommunicatorId: (state: SessionState) => AgentId | null;
+export declare const getEntryAgentId: (state: SessionState) => AgentId | null;
+export declare const getAgentState: (state: SessionState, agentId: AgentId) => AgentState | null;
+export declare const getNextAgentSeq: (state: SessionState, definitionName: string) => number;
+export {};
+//# sourceMappingURL=state.d.ts.map

package/dist/core/sessions/state.d.ts.map

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

package/dist/core/system.d.ts

@@ -0,0 +1,97 @@
+/**
+ * System — Composition Root
+ *
+ * createSystem() is the main entry point that:
+ * - Accepts all plugin definitions and infrastructure dependencies
+ * - Composes plugins, creates SessionManager internally
+ * - Exposes typed method registry for RPC type inference
+ */
+import type z4 from 'zod/v4';
+import type { Logger } from '../lib/logger/logger.js';
+import type { Platform } from '../platform/index.js';
+import type { PortPool } from '../plugins/services/port-pool.js';
+import type { PreprocessorRegistry } from '../plugins/uploads/preprocessor.js';
+import type { EventStore } from './events/event-store.js';
+import type { FileStore } from './file-store/types.js';
+import type { LLMLogger } from './llm/logger.js';
+import type { LLMProvider } from './llm/provider.js';
+import type { PluginDefinition } from './plugins/plugin-builder.js';
+import type { Preset } from './preset/index.js';
+import { SessionManager } from './sessions/session-manager.js';
+import type { UserOutputCallback } from './sessions/session.js';
+import type { ToolExecutor } from './tools/executor.js';
+export type MethodSchema = {
+    input: z4.ZodType;
+    output: z4.ZodType;
+};
+/**
+ * Extract manager method schemas from a single PluginDefinition.
+ * Uses indexed access on type brands (P['name'], P['_managerMethods'])
+ * instead of conditional `infer` — avoids expensive pattern matching on 5-param generic.
+ */
+type ManagerMethodSchemas<P extends PluginDefinition<string, any, any, any, any>> = {
+    [K in string & keyof NonNullable<P['_managerMethods']> as `${P['name']}.${K}`]: NonNullable<P['_managerMethods']>[K];
+};
+/**
+ * Extract session-level method schemas from a single PluginDefinition.
+ * The `__session` marker enables RpcInput<M> to automatically add `sessionId: string`
+ * for session methods (the RPC dispatcher requires sessionId for routing).
+ */
+type SessionMethodSchemas<P extends PluginDefinition<string, any, any, any, any>> = {
+    [K in string & keyof NonNullable<P['_methods']> as `${P['name']}.${K}`]: NonNullable<P['_methods']>[K] & {
+        __session: true;
+    };
+};
+/** Merge manager + session method schemas from a single plugin into one object */
+type PluginSchemas<P extends PluginDefinition<string, any, any, any, any>> = ManagerMethodSchemas<P> & SessionMethodSchemas<P>;
+/**
+ * Merge method schemas from an array of PluginDefinitions.
+ * Recursive tuple traversal — directly accumulates intersections without
+ * UnionToIntersection (which uses expensive contravariant inference over distributive conditionals).
+ */
+type MergePluginSchemas<TPlugins extends readonly PluginDefinition<string, any, any, any, any>[], Acc = {}> = TPlugins extends readonly [
+    infer Head extends PluginDefinition<string, any, any, any, any>,
+    ...infer Tail extends readonly PluginDefinition<string, any, any, any, any>[]
+] ? MergePluginSchemas<Tail, Acc & PluginSchemas<Head>> : Acc;
+export type AllMethodSchemas<TPlugins extends readonly PluginDefinition<string, any, any, any, any>[]> = MergePluginSchemas<TPlugins>;
+/**
+ * Maps an array of PluginDefinitions to a record keyed by plugin name.
+ * Enables `system.plugins.todo` → typed PluginDefinition accessor.
+ */
+type PluginsAccessor<TPlugins extends readonly PluginDefinition<string, any, any, any, any>[]> = {
+    [P in TPlugins[number] as P extends PluginDefinition<infer N, any, any, any, any> ? N : never]: P;
+};
+export interface System<TMethodSchemas = Record<string, MethodSchema>, TPlugins extends readonly PluginDefinition<string, any, any, any, any>[] = readonly PluginDefinition[]> {
+    /** SessionManager wrapped internally */
+    sessionManager: SessionManager;
+    /** Typed method registry (inferred from all plugins) */
+    methodSchemas: TMethodSchemas;
+    /** Typed accessor for all registered plugins */
+    plugins: PluginsAccessor<TPlugins>;
+    /** Shutdown all sessions */
+    shutdown(): Promise<void>;
+    /** Load all sessions from event store */
+    loadAllSessions(): Promise<void>;
+}
+export interface CreateSystemOptions<TPlugins extends readonly PluginDefinition<string, any, any, any, any>[]> {
+    /** All plugin definitions */
+    plugins: TPlugins;
+    eventStore: EventStore;
+    llmProvider: LLMProvider;
+    /** Named provider instances for middleware routing */
+    llmProviders?: ReadonlyMap<string, LLMProvider>;
+    toolExecutor: ToolExecutor;
+    presets: Map<string, Preset>;
+    logger: Logger;
+    basePath: string;
+    dataFileStore: FileStore;
+    onUserOutput?: UserOutputCallback;
+    preprocessorRegistry?: PreprocessorRegistry;
+    llmLogger?: LLMLogger;
+    portPool?: PortPool;
+    /** Host-environment adapters (filesystem, process). */
+    platform: Platform;
+}
+export declare function createSystem<const TPlugins extends readonly PluginDefinition<string, any, any, any, any>[]>(options: CreateSystemOptions<TPlugins>): System<AllMethodSchemas<TPlugins>, TPlugins>;
+export {};
+//# sourceMappingURL=system.d.ts.map

package/dist/core/system.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"system.d.ts","sourceRoot":"","sources":["../../src/core/system.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,MAAM,QAAQ,CAAA;AAC5B,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAA;AACpD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAA;AACnD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAA;AAC/D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAA;AAC7E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAA;AACzD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAA;AACtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAChD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AACpD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAA;AACnE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAC/C,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAA;AAC9D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAA;AAC/D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAMvD,MAAM,MAAM,YAAY,GAAG;IAAE,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC;IAAC,MAAM,EAAE,EAAE,CAAC,OAAO,CAAA;CAAE,CAAA;AAEpE;;;;GAIG;AACH,KAAK,oBAAoB,CAAC,CAAC,SAAS,gBAAgB,CAAC,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,IAAI;KAClF,CAAC,IAAI,MAAM,GAAG,MAAM,WAAW,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,WAAW,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAAC;CACpH,CAAA;AAED;;;;GAIG;AACH,KAAK,oBAAoB,CAAC,CAAC,SAAS,gBAAgB,CAAC,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,IAAI;KAClF,CAAC,IAAI,MAAM,GAAG,MAAM,WAAW,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,WAAW,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG;QAAE,SAAS,EAAE,IAAI,CAAA;KAAE;CAC5H,CAAA;AAED,kFAAkF;AAClF,KAAK,aAAa,CAAC,CAAC,SAAS,gBAAgB,CAAC,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,IAAI,oBAAoB,CAAC,CAAC,CAAC,GAAG,oBAAoB,CAAC,CAAC,CAAC,CAAA;AAE9H;;;;GAIG;AACH,KAAK,kBAAkB,CAAC,QAAQ,SAAS,SAAS,gBAAgB,CAAC,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EAAE,EAAE,GAAG,GAAG,EAAE,IAAI,QAAQ,SAAS,SAAS;IACvI,MAAM,IAAI,SAAS,gBAAgB,CAAC,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC;IAC/D,GAAG,MAAM,IAAI,SAAS,SAAS,gBAAgB,CAAC,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EAAE;CAC7E,GAAG,kBAAkB,CAAC,IAAI,EAAE,GAAG,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC,GACpD,GAAG,CAAA;AAEN,MAAM,MAAM,gBAAgB,CAAC,QAAQ,SAAS,SAAS,gBAAgB,CAAC,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EAAE,IAAI,kBAAkB,CAAC,QAAQ,CAAC,CAAA;AAMrI;;;GAGG;AACH,KAAK,eAAe,CAAC,QAAQ,SAAS,SAAS,gBAAgB,CAAC,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EAAE,IAAI;KAC/F,CAAC,IAAI,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,gBAAgB,CAAC,MAAM,CAAC,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,GAAG,CAAC;CACjG,CAAA;AAMD,MAAM,WAAW,MAAM,CACtB,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,EAC7C,QAAQ,SAAS,SAAS,gBAAgB,CAAC,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EAAE,GAAG,SAAS,gBAAgB,EAAE;IAEtG,wCAAwC;IACxC,cAAc,EAAE,cAAc,CAAA;IAE9B,wDAAwD;IACxD,aAAa,EAAE,cAAc,CAAA;IAE7B,gDAAgD;IAChD,OAAO,EAAE,eAAe,CAAC,QAAQ,CAAC,CAAA;IAElC,4BAA4B;IAC5B,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IAEzB,yCAAyC;IACzC,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CAChC;AAMD,MAAM,WAAW,mBAAmB,CAAC,QAAQ,SAAS,SAAS,gBAAgB,CAAC,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EAAE;IAC5G,6BAA6B;IAC7B,OAAO,EAAE,QAAQ,CAAA;IAGjB,UAAU,EAAE,UAAU,CAAA;IACtB,WAAW,EAAE,WAAW,CAAA;IACxB,sDAAsD;IACtD,YAAY,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,CAAA;IAC/C,YAAY,EAAE,YAAY,CAAA;IAC1B,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC5B,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,CAAA;IAChB,aAAa,EAAE,SAAS,CAAA;IACxB,YAAY,CAAC,EAAE,kBAAkB,CAAA;IACjC,oBAAoB,CAAC,EAAE,oBAAoB,CAAA;IAC3C,SAAS,CAAC,EAAE,SAAS,CAAA;IACrB,QAAQ,CAAC,EAAE,QAAQ,CAAA;IACnB,uDAAuD;IACvD,QAAQ,EAAE,QAAQ,CAAA;CAClB;AAMD,wBAAgB,YAAY,CAAC,KAAK,CAAC,QAAQ,SAAS,SAAS,gBAAgB,CAAC,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EAAE,EAC1G,OAAO,EAAE,mBAAmB,CAAC,QAAQ,CAAC,GACpC,MAAM,CAAC,gBAAgB,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,CAyE9C"}

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

@@ -0,0 +1,3 @@
+import type { AgentContext } from '../agents/context';
+export type ToolContext = AgentContext;
+//# sourceMappingURL=context.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../../src/core/tools/context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAErD,MAAM,MAAM,WAAW,GAAG,YAAY,CAAA"}

package/dist/core/tools/definition.d.ts

@@ -0,0 +1,10 @@
+import z4 from 'zod/v4';
+import { ToolExecutionCallback } from './schema';
+export type ToolDefinition<TInput = unknown> = {
+    name: string;
+    description: string;
+    input: z4.ZodType<TInput>;
+    execute: ToolExecutionCallback<TInput>;
+};
+export declare function createTool<TInput = unknown>(args: ToolDefinition<TInput>): ToolDefinition<TInput>;
+//# sourceMappingURL=definition.d.ts.map

package/dist/core/tools/definition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"definition.d.ts","sourceRoot":"","sources":["../../../src/core/tools/definition.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,QAAQ,CAAA;AACvB,OAAO,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAA;AAEhD,MAAM,MAAM,cAAc,CAAC,MAAM,GAAG,OAAO,IAAI;IAC9C,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,CAAA;IACzB,OAAO,EAAE,qBAAqB,CAAC,MAAM,CAAC,CAAA;CACtC,CAAA;AAED,wBAAgB,UAAU,CAAC,MAAM,GAAG,OAAO,EAC1C,IAAI,EAAE,cAAc,CAAC,MAAM,CAAC,GAC1B,cAAc,CAAC,MAAM,CAAC,CAExB"}

package/dist/core/tools/executor.d.ts

@@ -0,0 +1,28 @@
+import { ToolResultContent } from '../../core/llm/llm-log-types.js';
+import { SessionEnvironment } from '../../core/sessions/session-environment';
+import type { Logger } from '../../lib/logger/logger.js';
+import { Result } from '../../lib/utils/result.js';
+import { ToolContext } from './context.js';
+import { ToolDefinition } from './definition.js';
+export type { SessionEnvironment };
+/**
+ * Tool execution error
+ */
+export interface ToolError {
+    message: string;
+    recoverable: boolean;
+    details?: unknown;
+}
+/**
+ * ToolExecutor - executes tools with logging and error handling
+ */
+export declare class ToolExecutor {
+    private readonly logger;
+    constructor(logger: Logger);
+    /**
+     * Execute a tool with given input.
+     * Validates input against the tool's schema before execution.
+     */
+    execute(tool: ToolDefinition<any>, input: unknown, context: ToolContext): Promise<Result<ToolResultContent, ToolError>>;
+}
+//# sourceMappingURL=executor.d.ts.map

package/dist/core/tools/executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../../../src/core/tools/executor.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAA;AAC/D,OAAO,EAAE,kBAAkB,EAAE,MAAM,qCAAqC,CAAA;AACxE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAA;AACpD,OAAO,EAAW,MAAM,EAAE,MAAM,uBAAuB,CAAA;AACvD,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAEhD,YAAY,EAAE,kBAAkB,EAAE,CAAA;AAMlC;;GAEG;AACH,MAAM,WAAW,SAAS;IACzB,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,EAAE,OAAO,CAAA;IACpB,OAAO,CAAC,EAAE,OAAO,CAAA;CACjB;AAMD;;GAEG;AACH,qBAAa,YAAY;IACZ,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,MAAM;IAE3C;;;OAGG;IACG,OAAO,CACZ,IAAI,EAAE,cAAc,CAAC,GAAG,CAAC,EACzB,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,WAAW,GAClB,OAAO,CAAC,MAAM,CAAC,iBAAiB,EAAE,SAAS,CAAC,CAAC;CA2EhD"}

package/dist/core/tools/executor.test.d.ts

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

package/dist/core/tools/executor.test.d.ts.map

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

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/tools/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAA;AAC5B,cAAc,YAAY,CAAA;AAC1B,cAAc,UAAU,CAAA"}

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

@@ -0,0 +1,61 @@
+/**
+ * Tool domain types and schemas
+ *
+ * Contains all types related to tools:
+ * - Branded ID type and constructor
+ * - Tool definition types
+ * - Zod schemas for validation
+ */
+import z from 'zod/v4';
+import type { ToolResultContent } from '../../core/llm/llm-log-types.js';
+import { ToolContext } from './context';
+/** ToolCallId schema - validates any string and brands as ToolCallId. */
+export declare const toolCallIdSchema: z.core.$ZodBranded<z.ZodString, "ToolCallId", "out">;
+/** Branded ToolCallId type */
+export type ToolCallId = z.infer<typeof toolCallIdSchema>;
+/** Constructor for ToolCallId */
+export declare const ToolCallId: (id: string) => ToolCallId;
+/** Generate a new ToolCallId (UUIDv7) */
+export declare const generateToolCallId: () => ToolCallId;
+/**
+ * Tool call in agent state.
+ */
+export interface ToolCall {
+    id: ToolCallId;
+    name: string;
+    input: unknown;
+}
+/**
+ * Tool result in agent state.
+ */
+export interface ToolResult {
+    toolCallId: ToolCallId;
+    result: unknown;
+    isError: boolean;
+}
+/**
+ * Pending tool result awaiting LLM processing.
+ * Stored after tool_completed/tool_failed, moved to conversationHistory by inference_completed.
+ */
+export interface PendingToolResult {
+    toolCallId: ToolCallId;
+    toolName: string;
+    timestamp: number;
+    isError: boolean;
+    content: ToolResultContent;
+}
+export type ToolOkResponse = {
+    ok: true;
+    value: ToolResultContent;
+};
+export type ToolErrorResponse = {
+    ok: false;
+    error: {
+        message: string;
+        recoverable: boolean;
+        details?: unknown;
+    };
+};
+export type ToolResponse = ToolOkResponse | ToolErrorResponse;
+export type ToolExecutionCallback<TInput = unknown> = (input: TInput, context: ToolContext) => Promise<ToolResponse>;
+//# sourceMappingURL=schema.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/core/tools/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,CAAC,MAAM,QAAQ,CAAA;AACtB,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAA;AACpE,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAMvC,yEAAyE;AACzE,eAAO,MAAM,gBAAgB,sDAAiC,CAAA;AAE9D,8BAA8B;AAC9B,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAA;AAEzD,iCAAiC;AACjC,eAAO,MAAM,UAAU,GAAI,IAAI,MAAM,KAAG,UAA8B,CAAA;AAEtE,yCAAyC;AACzC,eAAO,MAAM,kBAAkB,QAAO,UAAkC,CAAA;AASxE;;GAEG;AACH,MAAM,WAAW,QAAQ;IACxB,EAAE,EAAE,UAAU,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,OAAO,CAAA;CACd;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IAC1B,UAAU,EAAE,UAAU,CAAA;IACtB,MAAM,EAAE,OAAO,CAAA;IACf,OAAO,EAAE,OAAO,CAAA;CAChB;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IACjC,UAAU,EAAE,UAAU,CAAA;IACtB,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,OAAO,CAAA;IAChB,OAAO,EAAE,iBAAiB,CAAA;CAC1B;AAED,MAAM,MAAM,cAAc,GAAG;IAC5B,EAAE,EAAE,IAAI,CAAA;IACR,KAAK,EAAE,iBAAiB,CAAA;CACxB,CAAA;AAED,MAAM,MAAM,iBAAiB,GAAG;IAC/B,EAAE,EAAE,KAAK,CAAA;IACT,KAAK,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,CAAA;CACnE,CAAA;AAED,MAAM,MAAM,YAAY,GAAG,cAAc,GAAG,iBAAiB,CAAA;AAE7D,MAAM,MAAM,qBAAqB,CAAC,MAAM,GAAG,OAAO,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,KAAK,OAAO,CAAC,YAAY,CAAC,CAAA"}

package/dist/core/tools/state.d.ts

@@ -0,0 +1,28 @@
+import z4 from 'zod/v4';
+import type { ToolResultContent } from '../../core/llm/llm-log-types.js';
+export declare const toolEvents: import("../events/types").EventsFactory<{
+    tool_started: z4.ZodObject<{
+        agentId: z4.core.$ZodBranded<z4.ZodString, "AgentId", "out">;
+        toolCallId: z4.core.$ZodBranded<z4.ZodString, "ToolCallId", "out">;
+        toolName: z4.ZodString;
+        input: z4.ZodCustom<Record<string, unknown>, Record<string, unknown>>;
+    }, z4.core.$strip>;
+    tool_completed: z4.ZodObject<{
+        agentId: z4.core.$ZodBranded<z4.ZodString, "AgentId", "out">;
+        toolCallId: z4.core.$ZodBranded<z4.ZodString, "ToolCallId", "out">;
+        result: z4.ZodCustom<ToolResultContent, ToolResultContent>;
+        workspaceRef: z4.ZodOptional<z4.ZodString>;
+        sessionRef: z4.ZodOptional<z4.ZodString>;
+    }, z4.core.$strip>;
+    tool_failed: z4.ZodObject<{
+        agentId: z4.core.$ZodBranded<z4.ZodString, "AgentId", "out">;
+        toolCallId: z4.core.$ZodBranded<z4.ZodString, "ToolCallId", "out">;
+        error: z4.ZodString;
+        workspaceRef: z4.ZodOptional<z4.ZodString>;
+        sessionRef: z4.ZodOptional<z4.ZodString>;
+    }, z4.core.$strip>;
+}>;
+export type ToolStartedEvent = (typeof toolEvents)['Events']['tool_started'];
+export type ToolCompletedEvent = (typeof toolEvents)['Events']['tool_completed'];
+export type ToolFailedEvent = (typeof toolEvents)['Events']['tool_failed'];
+//# sourceMappingURL=state.d.ts.map

package/dist/core/tools/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../../src/core/tools/state.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,QAAQ,CAAA;AAEvB,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAA;AAIpE,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;EAuBrB,CAAA;AAEF,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,QAAQ,CAAC,CAAC,cAAc,CAAC,CAAA;AAC5E,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,QAAQ,CAAC,CAAC,gBAAgB,CAAC,CAAA;AAChF,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,QAAQ,CAAC,CAAC,aAAa,CAAC,CAAA"}