@roj-ai/sdk 0.0.2

package/src/plugins/resources/plugin.ts

@@ -0,0 +1,201 @@
+import { join, relative } from 'node:path'
+import z from 'zod/v4'
+import { definePlugin } from '~/core/plugins/plugin-builder.js'
+import { Ok } from '~/lib/utils/result.js'
+import type { FileSystem } from '~/platform/fs.js'
+import type { ProcessRunner } from '~/platform/process.js'
+import { RESOURCE_MANIFEST_FILENAME, type ResourceManifest, ResourceManifestSchema } from './manifest.js'
+import {
+	type PostInjectContext,
+	type PostInjectExecOptions,
+	type PostInjectHook,
+	postInjectRules,
+} from './post-inject.js'
+import { type InjectedResource, resourceEvents, type ResourcesState } from './state.js'
+
+const MAX_LISTED_PATHS = 100
+
+export interface ResourcesPluginConfig {
+	targetDir?: string
+	/**
+	 * Called after a resource is written/extracted into `targetDir`, before the
+	 * `resource_injected` event is emitted. Use `postInjectRules` for a declarative
+	 * setup, or pass a custom async function for full control.
+	 */
+	postInject?: PostInjectHook
+}
+
+function makeExec(processRunner: ProcessRunner) {
+	return async function exec(
+		cmd: string,
+		args: string[],
+		options?: PostInjectExecOptions,
+	): Promise<{ stdout: string; stderr: string }> {
+		return processRunner.execFile(cmd, args, {
+			timeout: options?.timeout ?? 120_000,
+			maxBuffer: 50 * 1024 * 1024,
+			cwd: options?.cwd,
+			env: options?.env ? { ...process.env, ...options.env } : undefined,
+		})
+	}
+}
+
+async function listFiles(fs: FileSystem, dir: string, maxEntries: number): Promise<string[]> {
+	const results: string[] = []
+
+	async function walk(current: string): Promise<void> {
+		if (results.length >= maxEntries) return
+		const entries = await fs.readdir(current, { withFileTypes: true })
+		for (const entry of entries) {
+			if (results.length >= maxEntries) break
+			const fullPath = join(current, entry.name)
+			if (entry.isDirectory()) {
+				await walk(fullPath)
+			} else {
+				results.push(relative(dir, fullPath))
+			}
+		}
+	}
+
+	await walk(dir)
+	return results
+}
+
+export const resourcesPlugin = definePlugin('resources')
+	.pluginConfig<ResourcesPluginConfig>()
+	.events([resourceEvents])
+	.state<ResourcesState>({
+		key: 'resources',
+		initial: (): ResourcesState => ({ resources: [] }),
+		reduce: (state, event) => {
+			if (event.type === 'resource_injected') {
+				const resource: InjectedResource = {
+					resourceId: event.resourceId,
+					slug: event.slug,
+					name: event.name,
+					filename: event.filename,
+					mimeType: event.mimeType,
+					paths: event.paths,
+					injectedAt: event.injectedAt,
+				}
+				return { resources: [...state.resources, resource] }
+			}
+			return state
+		},
+	})
+	.method('inject', {
+		input: z.object({
+			sessionId: z.string(),
+			filename: z.string(),
+			mimeType: z.string(),
+			size: z.number(),
+			fileBuffer: z.custom<Buffer>(),
+			metadata: z.object({
+				slug: z.string().optional(),
+				name: z.string().optional(),
+			}).optional(),
+		}),
+		output: z.object({
+			resourceId: z.string(),
+			paths: z.array(z.string()),
+		}),
+		handler: async (ctx, input) => {
+			const fs = ctx.platform.fs
+			const exec = makeExec(ctx.platform.process)
+			const targetDir = ctx.pluginConfig?.targetDir ?? ctx.environment.workspaceDir ?? ctx.environment.sessionDir
+			const resourceId = crypto.randomUUID()
+			let paths: string[]
+
+			if (input.mimeType === 'application/zip') {
+				// Write to temp file, extract, clean up
+				const tempPath = join(ctx.environment.sessionDir, `_tmp_resource_${resourceId}.zip`)
+				await fs.writeFile(tempPath, input.fileBuffer)
+
+				try {
+					await exec('unzip', ['-o', '-q', tempPath, '-d', targetDir])
+				} catch (error) {
+					const message = error instanceof Error ? error.message : String(error)
+					// unzip returns exit code 1 for warnings — still usable
+					if (!message.includes('exit code 1')) {
+						await fs.unlink(tempPath).catch(() => {})
+						throw new Error(`unzip failed: ${message}`)
+					}
+				}
+
+				await fs.unlink(tempPath).catch(() => {})
+				paths = await listFiles(fs, targetDir, MAX_LISTED_PATHS)
+			} else {
+				// Copy file directly to target dir
+				const filePath = join(targetDir, input.filename)
+				await fs.writeFile(filePath, input.fileBuffer)
+				paths = [input.filename]
+			}
+
+			let manifest: ResourceManifest | null = null
+			if (input.mimeType === 'application/zip') {
+				const manifestPath = join(targetDir, RESOURCE_MANIFEST_FILENAME)
+				try {
+					const raw = await fs.readFile(manifestPath, 'utf-8')
+					manifest = ResourceManifestSchema.parse(JSON.parse(raw))
+					await fs.unlink(manifestPath).catch(() => {})
+					paths = paths.filter((p) => p !== RESOURCE_MANIFEST_FILENAME)
+					ctx.logger.info('resources.inject: loaded resource manifest', {
+						filename: RESOURCE_MANIFEST_FILENAME,
+						postInjectRules: manifest.postInject?.length ?? 0,
+					})
+				} catch (err) {
+					const code = (err as NodeJS.ErrnoException)?.code
+					if (code !== 'ENOENT') {
+						ctx.logger.warn('resources.inject: invalid resource manifest, skipping', {
+							filename: RESOURCE_MANIFEST_FILENAME,
+							error: err instanceof Error ? err.message : String(err),
+						})
+					}
+				}
+			}
+
+			const postInjectCtx: PostInjectContext = {
+				targetDir,
+				sessionDir: ctx.environment.sessionDir,
+				paths,
+				filename: input.filename,
+				mimeType: input.mimeType,
+				logger: ctx.logger,
+				exec,
+				fs,
+			}
+
+			if (ctx.pluginConfig?.postInject) {
+				await ctx.pluginConfig.postInject(postInjectCtx)
+			}
+
+			if (manifest?.postInject && manifest.postInject.length > 0) {
+				await postInjectRules(manifest.postInject)(postInjectCtx)
+			}
+
+			await ctx.emitEvent(resourceEvents.create('resource_injected', {
+				resourceId,
+				slug: input.metadata?.slug,
+				name: input.metadata?.name,
+				filename: input.filename,
+				mimeType: input.mimeType,
+				paths,
+				injectedAt: Date.now(),
+			}))
+
+			return Ok({ resourceId, paths })
+		},
+	})
+	.systemPrompt((ctx) => {
+		const { resources } = ctx.pluginState
+		if (resources.length === 0) return null
+
+		const targetDir = ctx.pluginConfig?.targetDir ?? ctx.environment.workspaceDir ?? ctx.environment.sessionDir
+		const lines = resources.map(r => {
+			const label = r.name ?? r.slug ?? r.filename
+			return `- **${label}** (${r.filename}): ${r.paths.length} files`
+		})
+
+		return `## Injected Resources\n\nThe following resources have been extracted into your workspace (\`${targetDir}\`):\n${lines.join('\n')}\n\nThese files are ready to use. Explore them with the filesystem tools.`
+	})
+	.build()

package/src/plugins/resources/post-inject.ts

@@ -0,0 +1,74 @@
+import { join } from 'node:path'
+import type { Logger } from '~/lib/logger/logger.js'
+import type { FileSystem } from '~/platform/fs.js'
+
+export interface PostInjectExecOptions {
+	cwd?: string
+	timeout?: number
+	env?: Record<string, string>
+}
+
+export interface PostInjectContext {
+	targetDir: string
+	sessionDir: string
+	paths: string[]
+	filename: string
+	mimeType: string
+	logger: Logger
+	exec(
+		cmd: string,
+		args: string[],
+		options?: PostInjectExecOptions,
+	): Promise<{ stdout: string; stderr: string }>
+	fs: FileSystem
+}
+
+export type PostInjectHook = (ctx: PostInjectContext) => Promise<void>
+
+export interface PostInjectRule {
+	/** Log label — defaults to the command string. */
+	name?: string
+	/** Relative path (inside `cwd`) that must exist for the rule to fire. Omit to always run. */
+	when?: string
+	/** Working directory — `target` (default) = injection targetDir, `session` = sessionDir. */
+	cwd?: 'target' | 'session'
+	/** Command + args. */
+	run: [string, ...string[]]
+	/** Environment overrides, merged into process.env. */
+	env?: Record<string, string>
+	/** Command timeout in ms. Default 300000 (5 min). */
+	timeoutMs?: number
+	/** If false, a failing rule throws and aborts subsequent rules. Default: true (warn + continue). */
+	continueOnError?: boolean
+}
+
+export function postInjectRules(rules: PostInjectRule[]): PostInjectHook {
+	return async (ctx) => {
+		for (const rule of rules) {
+			const cwd = rule.cwd === 'session' ? ctx.sessionDir : ctx.targetDir
+
+			if (rule.when) {
+				const probe = join(cwd, rule.when)
+				const exists = await ctx.fs.exists(probe)
+				if (!exists) continue
+			}
+
+			const label = rule.name ?? rule.run.join(' ')
+			ctx.logger.info(`resources.postInject: running "${label}"`, { cwd })
+
+			const [cmd, ...args] = rule.run
+			try {
+				await ctx.exec(cmd, args, {
+					cwd,
+					timeout: rule.timeoutMs ?? 300_000,
+					env: rule.env,
+				})
+				ctx.logger.info(`resources.postInject: "${label}" completed`, { cwd })
+			} catch (err) {
+				const error = err instanceof Error ? err.message : String(err)
+				if (rule.continueOnError === false) throw err
+				ctx.logger.warn(`resources.postInject: "${label}" failed`, { cwd, error })
+			}
+		}
+	}
+}

package/src/plugins/resources/state.ts

@@ -0,0 +1,30 @@
+import z4 from 'zod/v4'
+import { createEventsFactory } from '~/core/events/types'
+
+export const resourceEvents = createEventsFactory({
+	events: {
+		resource_injected: z4.object({
+			resourceId: z4.string(),
+			slug: z4.string().optional(),
+			name: z4.string().optional(),
+			filename: z4.string(),
+			mimeType: z4.string(),
+			paths: z4.array(z4.string()),
+			injectedAt: z4.number(),
+		}),
+	},
+})
+
+export interface InjectedResource {
+	resourceId: string
+	slug?: string
+	name?: string
+	filename: string
+	mimeType: string
+	paths: string[]
+	injectedAt: number
+}
+
+export interface ResourcesState {
+	resources: InjectedResource[]
+}

package/src/plugins/result-eviction/index.ts

@@ -0,0 +1,2 @@
+export { resultEvictionPlugin } from './plugin.js'
+export type { EvictionAgentConfig, EvictionConfig } from './plugin.js'

package/src/plugins/result-eviction/plugin.ts

@@ -0,0 +1,65 @@
+/**
+ * Result Eviction Plugin - saves large tool outputs to disk
+ *
+ * When a tool produces output exceeding the token threshold, the full output is saved
+ * to a file in the session's .results directory, and a truncated preview with
+ * head + tail + file path is returned instead.
+ */
+
+import { truncateByTokens } from '~/core/llm/tokens.js'
+import { definePlugin } from '~/core/plugins/plugin-builder.js'
+
+export interface EvictionConfig {
+	/** Max tokens before eviction (default: 20000) */
+	maxTokens?: number
+}
+
+export interface EvictionAgentConfig {
+	/** Whether result eviction is enabled for this agent (default: true) */
+	enabled?: boolean
+	/** Eviction configuration */
+	config?: EvictionConfig
+}
+
+const DEFAULT_MAX_TOKENS = 20_000
+
+export const resultEvictionPlugin = definePlugin('result-eviction')
+	.agentConfig<EvictionAgentConfig>()
+	.hook('afterToolCall', async (ctx) => {
+		const agentConfig = ctx.pluginAgentConfig
+		const enabled = agentConfig?.enabled !== false
+
+		if (!enabled || ctx.result.isError) {
+			return null
+		}
+
+		const { content } = ctx.result
+
+		// Only evict string content
+		if (typeof content !== 'string') {
+			return null
+		}
+
+		const maxTokens = agentConfig?.config?.maxTokens ?? DEFAULT_MAX_TOKENS
+
+		const truncation = truncateByTokens(content, maxTokens)
+		if (!truncation) {
+			return null
+		}
+
+		// Write full content to file via FileStore
+		const fileName = `${ctx.toolCall.id}.txt`
+		const filePath = `.results/${fileName}`
+		await ctx.files.session.write(filePath, content)
+
+		const truncatedContent = `${truncation.content}\n\n[Full output saved to: ${filePath}]`
+
+		return {
+			action: 'modify',
+			result: {
+				isError: false,
+				content: truncatedContent,
+			},
+		}
+	})
+	.build()

package/src/plugins/result-eviction/result-eviction.integration.test.ts

@@ -0,0 +1,244 @@
+import { describe, expect, it } from 'bun:test'
+import z from 'zod/v4'
+import { MockLLMProvider } from '~/core/llm/mock.js'
+import { definePlugin } from '~/core/plugins/plugin-builder.js'
+import { createTool } from '~/core/tools/definition.js'
+import { ToolCallId } from '~/core/tools/schema.js'
+import { Ok } from '~/lib/utils/result.js'
+import { createTestPreset, TestHarness } from '~/testing/index.js'
+import { resultEvictionPlugin } from './index.js'
+
+/**
+ * Helper plugin that provides a `generate_output` tool returning a string of given size.
+ */
+const bigOutputPlugin = definePlugin('big-output')
+	.tools(() => [
+		createTool({
+			name: 'generate_output',
+			description: 'Generate output of a given size',
+			input: z.object({ size: z.number() }),
+			execute: async (input) => Ok('x'.repeat(input.size)),
+		}),
+	])
+	.build()
+
+function createEvictionHarness(options: Omit<ConstructorParameters<typeof TestHarness>[0], 'systemPlugins'>) {
+	return new TestHarness({ ...options, systemPlugins: [resultEvictionPlugin, bigOutputPlugin] })
+}
+
+function createEvictionPreset(overrides?: Parameters<typeof createTestPreset>[0]) {
+	return createTestPreset(overrides)
+}
+
+describe('result-eviction plugin', () => {
+	it('small tool output → returned unchanged', async () => {
+		let toolResultContent: string | null = null
+		const harness = createEvictionHarness({
+			presets: [createEvictionPreset()],
+			mockHandler: (request) => {
+				const callCount = harness.llmProvider.getCallCount()
+				if (callCount === 1) {
+					return {
+						content: null,
+						toolCalls: [{ id: ToolCallId('tc1'), name: 'generate_output', input: { size: 100 } }],
+						finishReason: 'stop',
+						metrics: MockLLMProvider.defaultMetrics(),
+					}
+				}
+				// Capture the tool result
+				for (const msg of request.messages) {
+					if (msg.role === 'tool' && typeof msg.content === 'string') {
+						toolResultContent = msg.content
+					}
+				}
+				return { content: 'Done', toolCalls: [], finishReason: 'stop', metrics: MockLLMProvider.defaultMetrics() }
+			},
+		})
+
+		const session = await harness.createSession('test')
+		await session.sendAndWaitForIdle('Generate small output')
+
+		expect(toolResultContent).not.toBeNull()
+		// Should be the full output (100 x's), not truncated
+		expect(toolResultContent!).toBe('x'.repeat(100))
+
+		await harness.shutdown()
+	})
+
+	it('large tool output → truncated with file path', async () => {
+		let toolResultContent: string | null = null
+		const harness = createEvictionHarness({
+			presets: [createEvictionPreset()],
+			mockHandler: (request) => {
+				const callCount = harness.llmProvider.getCallCount()
+				if (callCount === 1) {
+					return {
+						content: null,
+						toolCalls: [{ id: ToolCallId('tc1'), name: 'generate_output', input: { size: 250_000 } }],
+						finishReason: 'stop',
+						metrics: MockLLMProvider.defaultMetrics(),
+					}
+				}
+				for (const msg of request.messages) {
+					if (msg.role === 'tool' && typeof msg.content === 'string') {
+						toolResultContent = msg.content
+					}
+				}
+				return { content: 'Done', toolCalls: [], finishReason: 'stop', metrics: MockLLMProvider.defaultMetrics() }
+			},
+		})
+
+		const session = await harness.createSession('test')
+		await session.sendAndWaitForIdle('Generate large output')
+
+		expect(toolResultContent).not.toBeNull()
+		expect(toolResultContent!).toContain('truncated')
+		expect(toolResultContent!).toContain('.results/')
+		expect(toolResultContent!).toContain('Full output saved to:')
+		expect(toolResultContent!.length).toBeLessThan(250_000)
+
+		await harness.shutdown()
+	})
+
+	it('full output saved to .results/<toolCallId>.txt', async () => {
+		const harness = createEvictionHarness({
+			presets: [createEvictionPreset()],
+			llmProvider: MockLLMProvider.withSequence([
+				{
+					toolCalls: [{ id: ToolCallId('tc1'), name: 'generate_output', input: { size: 250_000 } }],
+				},
+				{ content: 'Done', toolCalls: [] },
+			]),
+		})
+
+		const session = await harness.createSession('test')
+		await session.sendAndWaitForIdle('Generate large output')
+
+		// Verify the tool_completed event has evicted (truncated) content
+		const toolCompletedEvents = await session.getEventsByType('tool_completed')
+		expect(toolCompletedEvents.length).toBeGreaterThanOrEqual(1)
+
+		await harness.shutdown()
+	})
+
+	it('enabled: false → no eviction even for large output', async () => {
+		let toolResultContent: string | null = null
+		const harness = createEvictionHarness({
+			presets: [createEvictionPreset({
+				orchestratorPlugins: [
+					resultEvictionPlugin.configureAgent({ enabled: false }),
+				],
+			})],
+			mockHandler: (request) => {
+				const callCount = harness.llmProvider.getCallCount()
+				if (callCount === 1) {
+					return {
+						content: null,
+						toolCalls: [{ id: ToolCallId('tc1'), name: 'generate_output', input: { size: 250_000 } }],
+						finishReason: 'stop',
+						metrics: MockLLMProvider.defaultMetrics(),
+					}
+				}
+				for (const msg of request.messages) {
+					if (msg.role === 'tool' && typeof msg.content === 'string') {
+						toolResultContent = msg.content
+					}
+				}
+				return { content: 'Done', toolCalls: [], finishReason: 'stop', metrics: MockLLMProvider.defaultMetrics() }
+			},
+		})
+
+		const session = await harness.createSession('test')
+		await session.sendAndWaitForIdle('Generate large output')
+
+		expect(toolResultContent).not.toBeNull()
+		// With eviction disabled, the full output should be returned
+		expect(toolResultContent!).toBe('x'.repeat(250_000))
+
+		await harness.shutdown()
+	})
+
+	it('custom maxTokens respected', async () => {
+		let toolResultContent: string | null = null
+		const harness = createEvictionHarness({
+			presets: [createEvictionPreset({
+				orchestratorPlugins: [
+					resultEvictionPlugin.configureAgent({ config: { maxTokens: 10 } }),
+				],
+			})],
+			mockHandler: (request) => {
+				const callCount = harness.llmProvider.getCallCount()
+				if (callCount === 1) {
+					return {
+						content: null,
+						toolCalls: [{ id: ToolCallId('tc1'), name: 'generate_output', input: { size: 200 } }],
+						finishReason: 'stop',
+						metrics: MockLLMProvider.defaultMetrics(),
+					}
+				}
+				for (const msg of request.messages) {
+					if (msg.role === 'tool' && typeof msg.content === 'string') {
+						toolResultContent = msg.content
+					}
+				}
+				return { content: 'Done', toolCalls: [], finishReason: 'stop', metrics: MockLLMProvider.defaultMetrics() }
+			},
+		})
+
+		const session = await harness.createSession('test')
+		await session.sendAndWaitForIdle('Generate output')
+
+		expect(toolResultContent).not.toBeNull()
+		// With maxTokens=10, 200 chars should be evicted
+		expect(toolResultContent!).toContain('truncated')
+		expect(toolResultContent!).toContain('.results/')
+
+		await harness.shutdown()
+	})
+
+	it('error tool results → not evicted even if large', async () => {
+		// Create a plugin with a tool that always errors with large content
+		const errorToolPlugin = definePlugin('error-tool')
+			.tools(() => [
+				createTool({
+					name: 'always_error',
+					description: 'Always errors with large output',
+					input: z.object({}),
+					execute: async () => ({ ok: false, error: { message: 'ERROR_CONTENT_' + 'x'.repeat(250_000), recoverable: true } }),
+				}),
+			])
+			.build()
+
+		let toolResultContent: string | null = null
+		const harness = new TestHarness({
+			presets: [createEvictionPreset()],
+			systemPlugins: [resultEvictionPlugin, errorToolPlugin],
+			mockHandler: (request) => {
+				const callCount = harness.llmProvider.getCallCount()
+				if (callCount === 1) {
+					return {
+						content: null,
+						toolCalls: [{ id: ToolCallId('tc1'), name: 'always_error', input: {} }],
+						finishReason: 'stop',
+						metrics: MockLLMProvider.defaultMetrics(),
+					}
+				}
+				for (const msg of request.messages) {
+					if (msg.role === 'tool' && typeof msg.content === 'string' && msg.content.includes('ERROR_CONTENT_')) {
+						toolResultContent = msg.content
+					}
+				}
+				return { content: 'Done', toolCalls: [], finishReason: 'stop', metrics: MockLLMProvider.defaultMetrics() }
+			},
+		})
+
+		const session = await harness.createSession('test')
+		await session.sendAndWaitForIdle('Try error')
+
+		// Error results should NOT be evicted — so no truncation markers
+		expect(toolResultContent).not.toBeNull()
+		expect(toolResultContent!).not.toContain('Full output saved to:')
+
+		await harness.shutdown()
+	})
+})