@roj-ai/sdk 0.0.2

package/src/plugins/workers/context.ts

@@ -0,0 +1,251 @@
+/**
+ * WorkerContext - context provided to workers during execution.
+ *
+ * Provides:
+ * - State management (event-sourced)
+ * - File storage via FileStore
+ * - Execution control (pause, cancel)
+ * - Communication with owning agent
+ */
+
+import type { AgentId } from '~/core/agents/schema.js'
+import type { FileStore } from '~/core/file-store/types.js'
+import type { SessionId } from '~/core/sessions/schema.js'
+import type { SessionState } from '~/core/sessions/state.js'
+import { getNextMessageSeq, selectMailboxState } from '~/plugins/mailbox/query.js'
+import { generateMessageId } from '~/plugins/mailbox/schema.js'
+import { mailboxEvents } from '~/plugins/mailbox/state.js'
+import type { Logger } from '../../lib/logger/logger.js'
+import type { WorkerSubEvent } from './definition.js'
+import type { EmitEvent } from './plugin.js'
+import { workerEvents } from './plugin.js'
+import { WorkerId } from './worker.js'
+
+// ============================================================================
+// WorkerContext Interface
+// ============================================================================
+
+/**
+ * Context provided to workers during execution.
+ *
+ * @template TState - Worker state type
+ * @template TSubEvent - Worker event type
+ */
+export interface WorkerContext<TState, TSubEvent extends WorkerSubEvent> {
+	/** Session ID */
+	readonly sessionId: SessionId
+
+	/** Worker ID */
+	readonly workerId: WorkerId
+
+	/** Owning agent ID */
+	readonly agentId: AgentId
+
+	/** Logger for debugging */
+	readonly logger: Logger
+
+	/** File store for reading/writing files */
+	readonly files: FileStore
+
+	/**
+	 * Get current worker state (reconstructed from events).
+	 */
+	getState(): TState
+
+	/**
+	 * Emit a worker-specific event.
+	 * The event is persisted and applied to state.
+	 */
+	emit(event: TSubEvent): Promise<void>
+
+	/**
+	 * Check if worker should continue execution.
+	 * Returns false if cancelled or session closed.
+	 */
+	shouldContinue(): boolean
+
+	/**
+	 * Check if worker is paused.
+	 * Workers should pause their work when this returns true.
+	 */
+	isPaused(): boolean
+
+	/**
+	 * Notify the owning agent with a message.
+	 * Sends a mailbox message to the agent.
+	 */
+	notifyAgent(message: string): Promise<void>
+
+	/**
+	 * Get current session state.
+	 * Workers can read session metadata via getSessionState().metadata.
+	 */
+	getSessionState(): SessionState
+
+	/**
+	 * Get an AbortSignal that is aborted when the worker is cancelled.
+	 * Use this to abort long-running operations like fetch() when the worker is cancelled.
+	 */
+	getAbortSignal(): AbortSignal
+}
+
+// ============================================================================
+// WorkerContextImpl
+// ============================================================================
+
+/**
+ * Implementation of WorkerContext.
+ */
+export class WorkerContextImpl<TState, TSubEvent extends WorkerSubEvent> implements WorkerContext<TState, TSubEvent> {
+	readonly sessionId: SessionId
+	readonly workerId: WorkerId
+	readonly agentId: AgentId
+	readonly logger: Logger
+	readonly files: FileStore
+
+	private readonly workerType: string
+	private readonly emitEvent: EmitEvent
+	private readonly getSessionStateCallback: () => SessionState
+	private readonly reducer: (state: TState, event: TSubEvent) => TState
+	private localState: TState
+
+	/**
+	 * Local cancellation flag - provides immediate signal before event is persisted.
+	 * This is set by cancel() and checked by shouldContinue() for fast response.
+	 */
+	private _cancelled = false
+
+	/**
+	 * Local pause flag - provides immediate signal before event is persisted.
+	 * This is set by pause() and checked by isPaused() for fast response.
+	 */
+	private _paused = false
+
+	/**
+	 * AbortController for cancelling long-running operations.
+	 * Aborted when cancel() is called.
+	 */
+	private readonly abortController = new AbortController()
+
+	private readonly scheduleCallback?: () => void
+
+	constructor(params: {
+		sessionId: SessionId
+		workerId: WorkerId
+		agentId: AgentId
+		workerType: string
+		files: FileStore
+		emitEvent: EmitEvent
+		getSessionState: () => SessionState
+		reducer: (state: TState, event: TSubEvent) => TState
+		initialState: TState
+		logger: Logger
+		schedule?: () => void
+	}) {
+		this.sessionId = params.sessionId
+		this.workerId = params.workerId
+		this.agentId = params.agentId
+		this.workerType = params.workerType
+		this.files = params.files
+		this.emitEvent = params.emitEvent
+		this.getSessionStateCallback = params.getSessionState
+		this.reducer = params.reducer
+		this.localState = params.initialState
+		this.logger = params.logger
+		this.scheduleCallback = params.schedule
+	}
+
+	/**
+	 * Get current worker state (tracked locally).
+	 */
+	getState(): TState {
+		return this.localState
+	}
+
+	/**
+	 * Emit a worker-specific event.
+	 * Applies the event to local state before persisting.
+	 */
+	async emit(event: TSubEvent): Promise<void> {
+		this.localState = this.reducer(this.localState, event)
+		await this.emitEvent(workerEvents.create('worker_sub_event', {
+			workerId: this.workerId,
+			workerType: this.workerType,
+			subEvent: event,
+		}))
+	}
+
+	/**
+	 * Check if worker should continue execution.
+	 * Returns false if cancelled.
+	 */
+	shouldContinue(): boolean {
+		return !this._cancelled
+	}
+
+	/**
+	 * Check if worker is paused.
+	 * Workers should check this in their main loop and wait when paused.
+	 */
+	isPaused(): boolean {
+		return this._paused
+	}
+
+	/**
+	 * Notify the owning agent.
+	 * NOTE: Uses direct mailbox event emission because mailbox.send() only accepts AgentId
+	 * as sender, but workers need to send as WorkerId. Migrate when mailbox.send supports WorkerId.
+	 */
+	async notifyAgent(message: string): Promise<void> {
+		const messageId = generateMessageId(getNextMessageSeq(selectMailboxState(this.getSessionStateCallback())))
+
+		await this.emitEvent(mailboxEvents.create('mailbox_message', {
+			toAgentId: this.agentId,
+			message: {
+				id: messageId,
+				from: this.workerId,
+				content: message,
+				timestamp: Date.now(),
+				consumed: false,
+			},
+		}))
+
+		this.scheduleCallback?.()
+	}
+
+	/**
+	 * Get current session state.
+	 */
+	getSessionState(): SessionState {
+		return this.getSessionStateCallback()
+	}
+
+	/**
+	 * Get AbortSignal for cancelling long-running operations.
+	 */
+	getAbortSignal(): AbortSignal {
+		return this.abortController.signal
+	}
+
+	/**
+	 * Mark worker as cancelled and abort any pending operations.
+	 */
+	cancel(): void {
+		this._cancelled = true
+		this.abortController.abort()
+	}
+
+	/**
+	 * Mark worker as paused.
+	 */
+	pause(): void {
+		this._paused = true
+	}
+
+	/**
+	 * Resume worker.
+	 */
+	resume(): void {
+		this._paused = false
+	}
+}

package/src/plugins/workers/definition.ts

@@ -0,0 +1,169 @@
+/**
+ * WorkerDefinition - defines the interface for worker types.
+ *
+ * Each worker type defines:
+ * 1. State shape - worker-specific state structure
+ * 2. Event types - worker-specific events
+ * 3. Reducer - how events change state
+ * 4. Execute - main worker logic
+ * 5. Commands - optional command definitions for typed tools
+ */
+
+import type z from 'zod/v4'
+import type { ToolResultContent } from '~/core/llm/llm-log-types.js'
+import type { Result } from '~/lib/utils/result.js'
+import type { WorkerContext } from './context.js'
+import { WorkerCommand, WorkerError, WorkerResult } from './worker.js'
+
+/**
+ * Base worker configuration.
+ * Describes a worker type's metadata and state management.
+ * Agent-server's WorkerDefinition adds typed generics and execution logic.
+ */
+export interface WorkerConfig {
+	/** Unique worker type identifier */
+	type: string
+	/** Human-readable description */
+	description: string
+	/** Zod schema for config validation */
+	configSchema: z.ZodType<unknown>
+	/** Optional command definitions for typed tools */
+	commands?: Record<string, WorkerCommandConfig>
+	/** Create initial state from config (method syntax for bivariance) */
+	initialState(config: unknown): unknown
+	/** Reducer for worker-specific events (method syntax for bivariance) */
+	reduce(state: unknown, event: { type: string; [key: string]: unknown }): unknown
+}
+
+/**
+ * Configuration for a worker command.
+ * Used to generate typed tools for worker control.
+ */
+export interface WorkerCommandConfig {
+	description: string
+	schema: z.ZodType<unknown>
+}
+
+/**
+ * Definition for a worker command.
+ * Used to generate typed tools for worker control.
+ * Extends WorkerCommandConfig from shared.
+ */
+export interface WorkerCommandDefinition<TArgs = unknown> extends WorkerCommandConfig {
+	/** Zod schema for command arguments validation */
+	schema: z.ZodType<TArgs>
+}
+
+// ============================================================================
+// WorkerDefinition Interface
+// ============================================================================
+
+/**
+ * Base sub-event type that all worker-specific events must extend.
+ */
+export interface WorkerSubEvent {
+	type: string
+	[key: string]: unknown
+}
+
+/**
+ * Worker definition - describes a worker type's behavior.
+ * Structurally compatible with WorkerConfig from shared (when default type params are used).
+ * Adds typed generics and execution logic.
+ *
+ * @template TConfig - Worker configuration type
+ * @template TState - Worker state type
+ * @template TSubEvent - Worker-specific event type
+ */
+export interface WorkerDefinition<
+	TConfig = unknown,
+	TState = unknown,
+	TSubEvent extends WorkerSubEvent = WorkerSubEvent,
+> {
+	/** Unique worker type identifier */
+	type: string
+
+	/** Human-readable description */
+	description: string
+
+	/** Zod schema for config validation */
+	configSchema: z.ZodType<TConfig>
+
+	/** Optional command definitions for generating typed tools */
+	commands?: Record<string, WorkerCommandDefinition>
+
+	/** Create initial state from config */
+	initialState(config: TConfig): TState
+
+	/** Reducer for worker-specific events */
+	reduce(state: TState, event: TSubEvent): TState
+
+	/**
+	 * Main execution logic.
+	 * The worker runs until completion, failure, or cancellation.
+	 */
+	execute(
+		config: TConfig,
+		context: WorkerContext<TState, TSubEvent>,
+	): Promise<Result<WorkerResult, WorkerError>>
+
+	/**
+	 * Optional: handle commands from agent.
+	 * Commands allow agents to control running workers.
+	 * Returns ToolResultContent for the agent to receive.
+	 */
+	handleCommand?(
+		command: WorkerCommand,
+		context: WorkerContext<TState, TSubEvent>,
+	): Promise<Result<ToolResultContent, WorkerError>>
+
+	/**
+	 * Optional: summarize state for status reporting.
+	 * When provided, worker_status tool returns this summary instead of the full state.
+	 * Use this to avoid sending large state objects (e.g. full crawl results) into LLM context.
+	 */
+	summarizeState?(state: TState): unknown
+}
+
+// ============================================================================
+// Helper to create WorkerDefinition
+// ============================================================================
+
+/**
+ * Create a worker definition with proper typing.
+ *
+ * @param type - Unique worker type identifier
+ * @param description - Human-readable description
+ * @param configSchema - Zod schema for config validation
+ * @param definition - Worker behavior definition
+ */
+export function createWorkerDefinition<
+	TConfig,
+	TState,
+	TSubEvent extends WorkerSubEvent,
+>(
+	type: string,
+	description: string,
+	configSchema: z.ZodType<TConfig>,
+	definition: {
+		commands?: Record<string, WorkerCommandDefinition>
+		initialState: (config: TConfig) => TState
+		reduce: (state: TState, event: TSubEvent) => TState
+		execute: (
+			config: TConfig,
+			ctx: WorkerContext<TState, TSubEvent>,
+		) => Promise<Result<WorkerResult, WorkerError>>
+		handleCommand?: (
+			cmd: WorkerCommand,
+			ctx: WorkerContext<TState, TSubEvent>,
+		) => Promise<Result<ToolResultContent, WorkerError>>
+		summarizeState?: (state: TState) => unknown
+	},
+): WorkerDefinition<TConfig, TState, TSubEvent> {
+	return {
+		type,
+		description,
+		configSchema,
+		...definition,
+	}
+}

package/src/plugins/workers/index.ts

@@ -0,0 +1,21 @@
+// Plugin
+export { workerPlugin } from './plugin.js'
+export type { WorkerAgentConfig, WorkerPresetConfig } from './plugin.js'
+
+// Events (now in plugin.ts)
+export { workerEvents } from './plugin.js'
+export type { WorkerCompletedEvent, WorkerFailedEvent, WorkerStartedEvent, WorkerStatusChangedEvent, WorkerSubEventEmittedEvent } from './plugin.js'
+
+// Definition
+export type { WorkerDefinition, WorkerSubEvent } from './definition.js'
+export { createWorkerDefinition } from './definition.js'
+
+// Context
+export type { WorkerContext } from './context.js'
+export { WorkerContextImpl } from './context.js'
+
+// Worker result types
+export type { WorkerError, WorkerResult } from './worker.js'
+
+// Types
+export type { EmitEvent } from './plugin.js'