@roj-ai/sdk 0.0.2

package/src/plugins/mailbox/plugin.ts

@@ -0,0 +1,270 @@
+/**
+ * Mailbox Plugin - Inter-agent communication via message passing
+ *
+ * Level 1 (Preset): Empty config (mailbox is always enabled)
+ * Level 2 (Session): Events factory + state slice + methods + tools
+ * Level 3 (Agent): send_message tool for communication
+ */
+
+import z from "zod/v4";
+import { getAgentRole } from "~/core/agents/agent-roles.js";
+import { type AgentId, agentIdSchema } from "~/core/agents/schema.js";
+import { ValidationErrors } from "~/core/errors.js";
+import { definePlugin } from "~/core/plugins/plugin-builder.js";
+import { createTool } from "~/core/tools/definition.js";
+import type { ToolError } from "~/core/tools/index.js";
+import { Err, Ok } from "~/lib/utils/result.js";
+import { canCommunicateWith, getCommunicableAgents } from "./helpers.js";
+import {
+	CHILD_REPORTING_SECTION,
+	COMMUNICATOR_FLOW_SECTION,
+	ENTRY_ROLE_SECTION,
+	formatMailboxForLLM,
+	ORCHESTRATOR_REPORTING_SECTION,
+} from "./prompts.js";
+import {
+	getAgentUnconsumedMailbox,
+	getNextMessageSeq,
+	type MailboxPluginState,
+} from "./query.js";
+import { generateMessageId, type MessageId } from "./schema.js";
+import type { MailboxMessage } from "./schema.js";
+import { mailboxEvents } from "./state.js";
+
+/**
+ * Session-wide mailbox configuration.
+ */
+export type MailboxPresetConfig = {};
+
+/**
+ * Agent-specific mailbox configuration.
+ */
+export interface MailboxAgentConfig {
+	/** If true, agent sends a completion message to its parent when it has no more work. */
+	sendCompletionMessage?: boolean;
+}
+
+export const mailboxPlugin = definePlugin("mailbox")
+	.pluginConfig<MailboxPresetConfig>()
+	.agentConfig<MailboxAgentConfig>()
+	.events([mailboxEvents])
+	.state<MailboxPluginState>({
+		key: "mailbox",
+		initial: (): MailboxPluginState => ({
+			agentMailboxes: new Map(),
+		}),
+		reduce: (state, event) => {
+			switch (event.type) {
+				case "mailbox_message": {
+					const agentMailbox = state.agentMailboxes.get(event.toAgentId) ?? [];
+					const newMailboxes = new Map(state.agentMailboxes);
+					newMailboxes.set(event.toAgentId, [...agentMailbox, event.message]);
+					return {
+						...state,
+						agentMailboxes: newMailboxes,
+					};
+				}
+
+				case "mailbox_consumed": {
+					const mailbox = state.agentMailboxes.get(event.agentId);
+					if (!mailbox) return state;
+					const consumedSet = new Set(event.messageIds);
+					const newMailboxes = new Map(state.agentMailboxes);
+					newMailboxes.set(
+						event.agentId,
+						mailbox.map((m) =>
+							consumedSet.has(m.id) ? { ...m, consumed: true } : m,
+						),
+					);
+					return { ...state, agentMailboxes: newMailboxes };
+				}
+
+				default:
+					return state;
+			}
+		},
+	})
+	.method("send", {
+		input: z.object({
+			fromAgentId: agentIdSchema.optional(),
+			toAgentId: agentIdSchema,
+			content: z.string(),
+			debug: z.boolean().optional(),
+		}),
+		output: z.object({ messageId: z.string() }),
+		handler: async (ctx, input) => {
+			const { toAgentId, content } = input;
+
+			if (input.debug) {
+				// Debug messages bypass communication validation
+				const messageId = generateMessageId(getNextMessageSeq(ctx.pluginState));
+				await ctx.emitEvent(
+					mailboxEvents.create("mailbox_message", {
+						toAgentId,
+						message: {
+							id: messageId,
+							from: "debug",
+							content,
+							timestamp: Date.now(),
+							consumed: false,
+						},
+					}),
+				);
+				ctx.scheduleAgent(toAgentId);
+				return Ok({ messageId });
+			}
+
+			const fromAgentId = input.fromAgentId;
+			if (!fromAgentId) {
+				return Err(
+					ValidationErrors.invalid(
+						"fromAgentId is required for non-debug messages",
+					),
+				);
+			}
+
+			// Validate that the target agent is allowed
+			if (!canCommunicateWith(ctx.sessionState, fromAgentId, toAgentId)) {
+				const allowed = getCommunicableAgents(ctx.sessionState, fromAgentId);
+				const allowedStr = allowed.length > 0 ? allowed.join(", ") : "none";
+				return Err(
+					ValidationErrors.invalid(
+						`Cannot send message to agent ${toAgentId}. You can only communicate with your parent or children. Allowed agents: ${allowedStr}`,
+					),
+				);
+			}
+
+			const messageId = generateMessageId(getNextMessageSeq(ctx.pluginState));
+			const now = Date.now();
+
+			await ctx.emitEvent(
+				mailboxEvents.create("mailbox_message", {
+					toAgentId,
+					message: {
+						id: messageId,
+						from: fromAgentId,
+						content,
+						timestamp: now,
+						consumed: false,
+					},
+				}),
+			);
+
+			ctx.scheduleAgent(toAgentId);
+
+			return Ok({ messageId });
+		},
+	})
+	.dequeue({
+		hasPendingMessages: (ctx) => {
+			return getAgentUnconsumedMailbox(ctx.pluginState, ctx.agentId).length > 0;
+		},
+
+		getPendingMessages: (ctx) => {
+			const unconsumed = getAgentUnconsumedMailbox(
+				ctx.pluginState,
+				ctx.agentId,
+			);
+			if (unconsumed.length === 0) return null;
+			return {
+				messages: [
+					{
+						role: "user",
+						content: formatMailboxForLLM(unconsumed, Date.now()),
+						sourceMessageIds: unconsumed.map((m: MailboxMessage) => m.id),
+					},
+				],
+				token: unconsumed.map((m: MailboxMessage) => m.id),
+			};
+		},
+
+		markConsumed: async (ctx, token) => {
+			await ctx.emitEvent(
+				mailboxEvents.create("mailbox_consumed", {
+					agentId: ctx.agentId,
+					messageIds: token,
+				}),
+			);
+		},
+	})
+	.hook("onComplete", async (ctx) => {
+		if (!ctx.agentState.parentId) return null;
+		if (!ctx.pluginAgentConfig?.sendCompletionMessage) return null;
+
+		await ctx.self.send({
+			fromAgentId: ctx.agentId,
+			toAgentId: ctx.agentState.parentId,
+			content: "Task completed.",
+		});
+		return null;
+	})
+	.hook("onError", async (ctx) => {
+		if (!ctx.agentState.parentId) return null;
+
+		await ctx.self.send({
+			fromAgentId: ctx.agentId,
+			toAgentId: ctx.agentState.parentId,
+			content: `Agent encountered an error: ${ctx.error}`,
+		});
+		return null;
+	})
+	.systemPrompt((ctx) => {
+		const role = getAgentRole(ctx.agentState, ctx.sessionState);
+		switch (role) {
+			case "child":
+				return CHILD_REPORTING_SECTION;
+			case "orchestrator":
+				return ORCHESTRATOR_REPORTING_SECTION;
+			case "communicator":
+				return COMMUNICATOR_FLOW_SECTION;
+			case "entry":
+				return ENTRY_ROLE_SECTION;
+		}
+	})
+	.tools((ctx) => {
+		return [
+			createTool({
+				name: "send_message",
+				description:
+					'Send a message to another agent. Use to: "parent" to report back to your parent agent, or a specific agent ID for child agents. (async, in response will ONLY confirm sending)',
+				input: z.object({
+					to: z
+						.string()
+						.describe(
+							'Target agent ID, or "parent" to send to your parent agent',
+						),
+					message: z.string().describe("Message content to send"),
+				}),
+				execute: async (input, context) => {
+					let toAgentId = input.to as AgentId;
+
+					// Resolve "parent" alias to actual parentId
+					if (toAgentId === ("parent" as AgentId)) {
+						const agentState = ctx.sessionState.agents.get(context.agentId);
+						if (!agentState?.parentId) {
+							return Err({
+								message:
+									'Cannot send message to "parent": this agent has no parent.',
+								recoverable: false,
+							} satisfies ToolError);
+						}
+						toAgentId = agentState.parentId;
+					}
+
+					const result = await ctx.self.send({
+						fromAgentId: context.agentId,
+						toAgentId,
+						content: input.message,
+					});
+
+					if (!result.ok)
+						return Err({ message: result.error.message, recoverable: false });
+
+					return Ok(
+						`Message sent to ${input.to} (message ID: ${result.value.messageId}).`,
+					);
+				},
+			}),
+		];
+	})
+	.build();

package/src/plugins/mailbox/prompts.ts

@@ -0,0 +1,104 @@
+import type { MailboxMessage } from './schema.js'
+
+// ============================================================================
+// Role briefing sections for system prompt composition
+// ============================================================================
+
+/**
+ * Briefing for entry agents (orchestrator without communicator).
+ * Entry agents can communicate directly with users and orchestrate children.
+ */
+export const ENTRY_ROLE_SECTION = `## Your Role: Entry Agent (Orchestrator)
+
+You are the entry point for user communication AND you orchestrate child agents. See your available tools for capabilities.`
+
+/**
+ * Reporting instructions for child agents.
+ * Child agents cannot communicate with users directly.
+ */
+export const CHILD_REPORTING_SECTION = `## Your Role: Child Agent
+
+You were spawned by a parent agent to handle a specific task. You CANNOT communicate with users directly. See your available tools for capabilities.
+
+Focus on completing your assigned task.
+
+## Reporting (MANDATORY)
+
+**You MUST always report back to your parent via \`send_message\` with \`to: "parent"\` before stopping.** This is the most important rule — your parent is waiting for your response and cannot proceed without it.
+
+- **Task completed**: Call \`send_message\` with \`to: "parent"\` and a structured final result summarizing what you accomplished and any relevant outputs.
+- **Task failed / blocked**: If you encounter an error, are blocked, or cannot complete the task for any reason, you MUST still call \`send_message\` with \`to: "parent"\` explaining what went wrong and what you attempted.
+- **Progress updates**: For long-running tasks, report progress to your parent periodically via \`send_message\` with \`to: "parent"\`.
+
+**Never stop without calling \`send_message\` with \`to: "parent"\`.** Silent termination leaves your parent stuck waiting indefinitely.`
+
+/**
+ * Reporting instructions for orchestrator agents (when there's a communicator).
+ */
+export const ORCHESTRATOR_REPORTING_SECTION = `## Your Role: Orchestrator
+
+You coordinate work and spawn child agents to complete tasks. You do NOT communicate directly with users. See your available tools for capabilities.
+
+You receive tasks from the communicator via \`send_message\`. The communicator's agent ID is in the \`from\` field of the message you receive.
+
+## Reporting (MANDATORY)
+
+**You MUST always report back to the communicator via \`send_message\` before stopping.** The communicator is waiting for your response and cannot update the user without it.
+
+- **Task completed**: Send a structured result summarizing what was accomplished.
+- **Task failed / blocked**: If you cannot complete the task, you MUST still send a message explaining what went wrong.
+- **Progress updates**: For long-running tasks, report progress to the communicator periodically.
+
+**Never stop without sending a message to the communicator.** Silent termination leaves the communicator and user stuck waiting indefinitely.`
+
+/**
+ * Message flow instructions for communicator agents.
+ */
+export const COMMUNICATOR_FLOW_SECTION = `## Your Role: Communicator
+
+You handle user communication and relay messages to/from the orchestrator. See your available tools for capabilities.
+
+## Message Flow
+
+- User messages arrive to you first
+- Forward tasks to the orchestrator via \`send_message\` (use the orchestrator's agent ID from messages)
+- When the orchestrator reports back, format and relay the results to the user via \`tell_user\``
+
+// ============================================================================
+// Mailbox formatting
+// ============================================================================
+
+export const formatMailboxForLLM = (messages: MailboxMessage[], currentTimestamp?: number): string => {
+	const formattedMessages = messages
+		.map((m) => {
+			const from = m.from === 'user' ? 'user' : m.from
+			// Format answer messages with XML wrapper for LLM
+			let content = m.answerTo
+				? `<answer questionId="${m.answerTo}">\n${JSON.stringify(m.answerValue)}\n</answer>`
+				: m.content
+
+			// Add attachment information if present
+			if (m.attachments && m.attachments.length > 0) {
+				const attachmentBlocks = m.attachments.map((att) => {
+					const innerContent = att.extractedContent
+						? att.extractedContent
+						: `[File uploaded: ${att.filename}]`
+					return `<attachment uploadId="${att.uploadId}" filename="${att.filename}" type="${att.mimeType}" path="${att.path}">\n${innerContent}\n</attachment>`
+				})
+				content = content + '\n' + attachmentBlocks.join('\n')
+			}
+
+			// Add context block if present (visible to LLM only)
+			if (m.context) {
+				content = content + `\n<message-context>\n${m.context}\n</message-context>`
+			}
+
+			// Add timestamp attribute to message tag
+			return `<message from="${from}" timestamp="${m.timestamp}">\n${content}\n</message>`
+		})
+		.join('\n\n')
+
+	// Add info block with current timestamp at the end
+	const now = currentTimestamp ?? Date.now()
+	return formattedMessages + `\n\n<info>\n  <currentTime>${new Date(now).toISOString()}</currentTime>\n</info>`
+}

package/src/plugins/mailbox/query.ts

@@ -0,0 +1,53 @@
+/**
+ * Mailbox plugin query helpers.
+ *
+ * Query functions accept MailboxPluginState directly.
+ * Use selectMailboxState() to extract plugin state from SessionState.
+ */
+
+import type { AgentId } from '~/core/agents/schema.js'
+import { selectPluginState } from '~/core/sessions/reducer.js'
+import type { SessionState } from '~/core/sessions/state.js'
+import type { MailboxMessage } from './schema.js'
+
+/**
+ * Mailbox plugin state — session-level state keyed by agent ID.
+ */
+export interface MailboxPluginState {
+	agentMailboxes: Map<AgentId, MailboxMessage[]>
+}
+
+const defaultState: MailboxPluginState = { agentMailboxes: new Map() }
+
+/**
+ * Extract MailboxPluginState from SessionState.
+ */
+export function selectMailboxState(sessionState: SessionState): MailboxPluginState {
+	return selectPluginState<MailboxPluginState>(sessionState, 'mailbox') ?? defaultState
+}
+
+/**
+ * Get all mailbox messages for a specific agent.
+ */
+export function getAgentMailbox(pluginState: MailboxPluginState, agentId: AgentId): MailboxMessage[] {
+	return pluginState.agentMailboxes.get(agentId) ?? []
+}
+
+/**
+ * Get unconsumed mailbox messages for a specific agent.
+ */
+export function getAgentUnconsumedMailbox(pluginState: MailboxPluginState, agentId: AgentId): MailboxMessage[] {
+	return getAgentMailbox(pluginState, agentId).filter((m) => !m.consumed)
+}
+
+/**
+ * Get the next message sequence number.
+ * Derived from total message count across all mailboxes (replay-safe).
+ */
+export function getNextMessageSeq(pluginState: MailboxPluginState): number {
+	let total = 0
+	for (const messages of pluginState.agentMailboxes.values()) {
+		total += messages.length
+	}
+	return total + 1
+}

package/src/plugins/mailbox/schema.ts

@@ -0,0 +1,81 @@
+/**
+ * Message domain types and schemas
+ *
+ * Contains all types related to messages:
+ * - Branded ID type and constructor
+ * - Mailbox types
+ * - AskUser input types
+ * - Zod schemas for validation
+ */
+
+import z from 'zod/v4'
+import { COMMUNICATOR_ROLE, ORCHESTRATOR_ROLE } from '../../core/agents/agent-roles.js'
+import type { AgentId } from '../../core/agents/schema.js'
+import type { MessageAttachment } from '../uploads/schema.js'
+import type { WorkerId } from '../workers/worker.js'
+
+// ============================================================================
+// MessageId - Branded type
+// ============================================================================
+
+/** MessageId schema - validates any string and brands as MessageId. */
+export const messageIdSchema = z.string().brand('MessageId')
+
+/** Branded MessageId type */
+export type MessageId = z.infer<typeof messageIdSchema>
+
+/** Constructor for MessageId */
+export const MessageId = (id: string): MessageId => id as MessageId
+
+/**
+ * Generate a short message ID.
+ * Format: m{seq} e.g., "m1", "m42"
+ */
+export const generateMessageId = (seq: number): MessageId => MessageId(`m${seq}`)
+
+// ============================================================================
+// Test helpers
+// ============================================================================
+
+let testCounter = 0
+
+/**
+ * Generate a test message ID (for tests only).
+ * Uses incrementing counter for uniqueness.
+ */
+export const generateTestMessageId = (): MessageId => MessageId(`m${++testCounter}`)
+
+// ============================================================================
+// Mailbox types
+// ============================================================================
+
+/**
+ * Sender of a mailbox message.
+ * Can be an agent, user, system roles, or a worker.
+ */
+export type MailboxMessageSender =
+	| AgentId
+	| WorkerId
+	| 'user'
+	| 'debug'
+	| typeof ORCHESTRATOR_ROLE
+	| typeof COMMUNICATOR_ROLE
+
+/**
+ * Message in an agent's mailbox.
+ */
+export type MailboxMessage = {
+	id: MessageId
+	from: MailboxMessageSender
+	content: string
+	timestamp: number
+	consumed: boolean
+	/** If this message is an answer to a question, the question's message ID */
+	answerTo?: MessageId
+	/** The answer value (JSON-serializable), only present when answerTo is set */
+	answerValue?: unknown
+	/** File attachments uploaded with this message */
+	attachments?: MessageAttachment[]
+	/** Optional context visible to LLM but not displayed in chat UI */
+	context?: string
+}

package/src/plugins/mailbox/state.ts

@@ -0,0 +1,52 @@
+import z4 from 'zod/v4'
+import { AgentId, agentIdSchema } from '~/core/agents'
+import { COMMUNICATOR_ROLE, ORCHESTRATOR_ROLE } from '~/core/agents/agent-roles'
+import { createEventsFactory } from '~/core/events/types'
+import { messageIdSchema } from '~/plugins/mailbox/schema'
+import { uploadIdSchema } from '~/plugins/uploads/schema'
+import { WorkerId, workerIdSchema } from '../workers/worker'
+
+export type MailboxMessageSender =
+	| AgentId
+	| WorkerId
+	| 'user'
+	| 'debug'
+	| typeof ORCHESTRATOR_ROLE
+	| typeof COMMUNICATOR_ROLE
+
+export const mailboxEvents = createEventsFactory({
+	events: {
+		mailbox_message: z4.object({
+			toAgentId: agentIdSchema,
+			message: z4.object({
+				id: messageIdSchema,
+				from: z4.union([
+					agentIdSchema,
+					workerIdSchema,
+					z4.enum(['user', 'debug', COMMUNICATOR_ROLE, ORCHESTRATOR_ROLE]),
+				]),
+				content: z4.string(),
+				timestamp: z4.number(),
+				consumed: z4.boolean(),
+				answerTo: messageIdSchema.optional(),
+				answerValue: z4.unknown().optional(),
+				attachments: z4.array(z4.object({
+					uploadId: uploadIdSchema,
+					filename: z4.string(),
+					mimeType: z4.string(),
+					size: z4.number(),
+					path: z4.string(),
+					extractedContent: z4.string().optional(),
+					derivedPaths: z4.array(z4.string()).optional(),
+				})).optional(),
+			}),
+		}),
+		mailbox_consumed: z4.object({
+			agentId: agentIdSchema,
+			messageIds: z4.array(messageIdSchema),
+		}),
+	},
+})
+
+export type MailboxMessageEvent = (typeof mailboxEvents)['Events']['mailbox_message']
+export type MailboxConsumedEvent = (typeof mailboxEvents)['Events']['mailbox_consumed']

package/src/plugins/resources/index.ts

@@ -0,0 +1,11 @@
+export { resourcesPlugin } from './plugin.js'
+export type { ResourcesPluginConfig } from './plugin.js'
+export { postInjectRules } from './post-inject.js'
+export type {
+	PostInjectContext,
+	PostInjectExecOptions,
+	PostInjectHook,
+	PostInjectRule,
+} from './post-inject.js'
+export { RESOURCE_MANIFEST_FILENAME, ResourceManifestSchema } from './manifest.js'
+export type { ResourceManifest } from './manifest.js'

package/src/plugins/resources/manifest.ts

@@ -0,0 +1,25 @@
+import z from 'zod/v4'
+import type { PostInjectRule } from './post-inject.js'
+
+/**
+ * File at the root of a resource zip that ships template-specific setup
+ * instructions (e.g. `bun install` for a JS template). Read by the resources
+ * plugin after extraction, then deleted so it doesn't pollute the workspace.
+ */
+export const RESOURCE_MANIFEST_FILENAME = 'roj.resource.json'
+
+const PostInjectRuleSchema = z.object({
+	name: z.string().optional(),
+	when: z.string().optional(),
+	cwd: z.enum(['target', 'session']).optional(),
+	run: z.tuple([z.string()]).rest(z.string()),
+	env: z.record(z.string(), z.string()).optional(),
+	timeoutMs: z.number().positive().optional(),
+	continueOnError: z.boolean().optional(),
+}) satisfies z.ZodType<PostInjectRule>
+
+export const ResourceManifestSchema = z.object({
+	postInject: z.array(PostInjectRuleSchema).optional(),
+})
+
+export type ResourceManifest = z.infer<typeof ResourceManifestSchema>