@roj-ai/sdk 0.0.2

package/src/plugins/logs/plugin.ts

@@ -0,0 +1,39 @@
+import { resolve } from 'node:path'
+import z from 'zod/v4'
+import { definePlugin } from '~/core/plugins/plugin-builder.js'
+import { Ok } from '~/lib/utils/result.js'
+
+export const logsPlugin = definePlugin('logs')
+	.method('tail', {
+		input: z.object({ since: z.number().int().min(0).optional() }),
+		output: z.object({ lines: z.array(z.string()), offset: z.number() }),
+		handler: async (ctx, input) => {
+			const since = input.since ?? 0
+			const logPath = resolve(ctx.environment.sessionDir, 'session.log')
+
+			let fileSize: number
+			try {
+				const st = await ctx.platform.fs.stat(logPath)
+				fileSize = st.size
+			} catch {
+				return Ok({ lines: [], offset: 0 })
+			}
+
+			if (since >= fileSize) {
+				return Ok({ lines: [], offset: fileSize })
+			}
+
+			const fh = await ctx.platform.fs.open(logPath, 'r')
+			try {
+				const length = fileSize - since
+				const buf = Buffer.alloc(length)
+				await fh.read(buf, 0, length, since)
+				const text = buf.toString('utf-8')
+				const lines = text.split('\n').filter((l) => l.length > 0)
+				return Ok({ lines, offset: fileSize })
+			} finally {
+				await fh.close()
+			}
+		},
+	})
+	.build()

package/src/plugins/mailbox/helpers.ts

@@ -0,0 +1,83 @@
+import { AgentId } from '~/core/agents'
+import { COMMUNICATOR_ROLE, ORCHESTRATOR_ROLE } from '~/core/agents/agent-roles'
+import { AgentState } from '~/core/agents/state'
+
+/**
+ * Check if an agent can communicate with another agent.
+ * Communication is only allowed with:
+ * - Parent agent
+ * - Child agents
+ * - Special case: communicator ↔ orchestrator (both are root-level)
+ */
+export const canCommunicateWith = (
+	session: { agents: Map<AgentId, AgentState> },
+	fromAgentId: AgentId,
+	toAgentId: AgentId,
+): boolean => {
+	const fromAgent = session.agents.get(fromAgentId)
+	const toAgent = session.agents.get(toAgentId)
+
+	if (!fromAgent || !toAgent) return false
+
+	// Can communicate with parent
+	if (fromAgent.parentId === toAgentId) return true
+
+	// Can communicate with child
+	if (toAgent.parentId === fromAgentId) return true
+
+	// Special case: communicator ↔ orchestrator (both are root-level agents)
+	if (fromAgent.parentId === null && toAgent.parentId === null) {
+		const fromDef = fromAgent.definitionName
+		const toDef = toAgent.definitionName
+		if (
+			(fromDef === COMMUNICATOR_ROLE && toDef === ORCHESTRATOR_ROLE)
+			|| (fromDef === ORCHESTRATOR_ROLE && toDef === COMMUNICATOR_ROLE)
+		) {
+			return true
+		}
+	}
+
+	return false
+}
+
+/**
+ * Get list of agents that the given agent can communicate with.
+ * Returns parent (if exists), children, and communicator/orchestrator peer (if applicable).
+ */
+export const getCommunicableAgents = (
+	session: { agents: Map<AgentId, AgentState> },
+	agentId: AgentId,
+): AgentId[] => {
+	const agent = session.agents.get(agentId)
+	if (!agent) return []
+
+	const result: AgentId[] = []
+
+	// Parent
+	if (agent.parentId) {
+		result.push(agent.parentId)
+	}
+
+	// Children
+	for (const [id, other] of session.agents) {
+		if (other.parentId === agentId) {
+			result.push(id)
+		}
+	}
+
+	// Special case: communicator ↔ orchestrator
+	if (agent.parentId === null) {
+		for (const [id, other] of session.agents) {
+			if (id === agentId) continue
+			if (other.parentId === null) {
+				const isCommOrch = (agent.definitionName === COMMUNICATOR_ROLE && other.definitionName === ORCHESTRATOR_ROLE)
+					|| (agent.definitionName === ORCHESTRATOR_ROLE && other.definitionName === COMMUNICATOR_ROLE)
+				if (isCommOrch) {
+					result.push(id)
+				}
+			}
+		}
+	}
+
+	return result
+}

package/src/plugins/mailbox/index.ts

@@ -0,0 +1,13 @@
+/**
+ * Mailbox plugin - inter-agent communication
+ */
+
+export { type MailboxAgentConfig, mailboxPlugin, type MailboxPresetConfig } from './plugin.js'
+
+export { type MailboxConsumedEvent, mailboxEvents, type MailboxMessageEvent, type MailboxMessageSender } from './state.js'
+
+export { canCommunicateWith, getCommunicableAgents } from './helpers.js'
+
+export { generateMessageId, generateTestMessageId, type MailboxMessage, MessageId, messageIdSchema } from './schema.js'
+
+export { getAgentMailbox, getAgentUnconsumedMailbox, getNextMessageSeq, type MailboxPluginState, selectMailboxState } from './query.js'