@roj-ai/sdk 0.1.14 → 0.1.16

package/src/plugins/context-compact/context-compactor.ts

@@ -2,14 +2,24 @@ import type { AgentId } from '~/core/agents/schema.js'
 import type { CompactedConversationMessage, ContextCompactedEvent } from '~/core/context/state.js'
 import { contextEvents } from '~/core/context/state.js'
 import { withSessionId } from '~/core/events/test-helpers.js'
-import type { LLMMessage, LLMProvider } from '~/core/llm/provider.js'
+import type { InferenceResponse, LLMError, LLMMessage } from '~/core/llm/provider.js'
 import type { ModelId } from '~/core/llm/schema.js'
 import { estimateMessagesTokens } from '~/core/llm/tokens.js'
 import type { SessionId } from '~/core/sessions/schema.js'
 import type { Result } from '~/lib/utils/result.js'
 import { Err, Ok } from '~/lib/utils/result.js'
 import type { Logger } from '../../lib/logger/logger.js'
-import { CONTEXT_SUMMARY_PROMPT, wrapContextSummary } from '../../prompts/index.js'
+import { wrapContextSummary } from '../../prompts/index.js'
+
+/**
+ * Callback used by the compactor to ask the host (an Agent) to run a side-channel
+ * inference reusing its own system prompt, tools, and conversation prefix.
+ *
+ * Implemented in practice by AgentContext.runAuxiliaryInference, which keeps the
+ * agent's prompt cache warm — only the trailing `extraMessages` and the response
+ * tokens are paid for; the rest of the prefix is served from cache.
+ */
+export type RunInferenceFn = (extraMessages: LLMMessage[]) => Promise<Result<InferenceResponse, LLMError>>
 
 // ============================================================================
 // Message formatting for summarization
@@ -76,24 +86,44 @@ function formatToolInput(input: unknown): string {
 // ============================================================================
 
 export interface CompactionConfig {
-	/** Model ID to use for summarization (required) */
-	model: ModelId
-	/** Token threshold to trigger compaction */
+	/**
+	 * @deprecated No longer used. Summarization runs on the agent's own model via
+	 * the auxiliary inference callback so the agent's prompt cache is reused.
+	 * Kept in the interface so existing preset configs continue to type-check.
+	 */
+	model?: ModelId
+	/** Token threshold to trigger compaction. */
 	maxTokens: number
-	/** Number of recent messages to keep uncompacted */
+	/** Number of recent messages to keep uncompacted. */
 	keepRecentMessages: number
-	/** Max tokens for kept recent messages (whichever limit is hit first) */
+	/** Max tokens for kept recent messages (whichever limit is hit first). */
 	keepRecentTokens?: number
-	/** Target token count after compaction (informational) */
+	/** Target token count after compaction (informational). */
 	targetTokens?: number
-	/** System prompt for summarization */
+	/** Optional override for the trailing summarization instruction sent to the model. */
 	summaryPrompt?: string
-	/** Enable history offloading before compaction */
+	/** Enable history offloading before compaction. */
 	offloadHistory?: boolean
-	/** Path prefix for offloaded history (default: /session/.history/) */
+	/** Path prefix for offloaded history (default: /session/.history/). */
 	historyPathPrefix?: string
 }
 
+/**
+ * Trailing user-message instruction appended to the agent's full prefix when
+ * requesting a summary. The model sees its real system prompt, tools and full
+ * conversation, then this instruction last. Phrased to discourage tool calls
+ * — Sonnet-class models reliably emit a plain text response under this prompt.
+ */
+export const DEFAULT_SUMMARY_INSTRUCTION =
+	'[CONTEXT COMPACTION REQUEST]\n'
+	+ 'The conversation above is approaching the context budget. Produce a concise '
+	+ 'summary (under 600 words) of everything discussed and decided so far. Cover: '
+	+ 'completed tasks and their outcomes, key decisions and rationale, current state '
+	+ 'of any in-progress work, important file paths or identifiers, and outstanding '
+	+ 'questions.\n\n'
+	+ 'Reply with plain text only. Do NOT call any tools. Do NOT acknowledge this '
+	+ 'request — just emit the summary directly.'
+
 // ============================================================================
 // Compaction Result
 // ============================================================================
@@ -141,7 +171,6 @@ export interface HistoryOffloader {
 
 export class ContextCompactor {
 	constructor(
-		private readonly llmProvider: LLMProvider,
 		private readonly logger: Logger,
 		private readonly config: CompactionConfig,
 		private readonly historyOffloader?: HistoryOffloader,
@@ -179,10 +208,17 @@ export class ContextCompactor {
 	}
 
 	/**
-	 * Check if compaction is needed based on token count.
+	 * Check if compaction is needed.
+	 *
+	 * Prefers the provider-reported prompt token count from the previous turn
+	 * (authoritative — comes straight from the model's tokenizer). Falls back
+	 * to the in-process estimator when no previous metrics exist (first turn).
+	 *
+	 * The estimator under-counts JSON-heavy tool-result history by ~2x, so
+	 * relying on it alone causes the trigger to never fire in long sessions.
 	 */
-	needsCompaction(messages: LLMMessage[]): boolean {
-		const tokens = estimateMessagesTokens(messages)
+	needsCompaction(messages: LLMMessage[], lastActualPromptTokens?: number): boolean {
+		const tokens = lastActualPromptTokens ?? estimateMessagesTokens(messages)
 		return tokens > this.config.maxTokens
 	}
 
@@ -194,33 +230,42 @@ export class ContextCompactor {
 		sessionId: SessionId,
 		agentId: AgentId,
 		messages: LLMMessage[],
+		runInference: RunInferenceFn,
+		lastActualPromptTokens?: number,
 	): Promise<Result<CompactionResult | null, Error>> {
-		if (!this.needsCompaction(messages)) {
+		if (!this.needsCompaction(messages, lastActualPromptTokens)) {
 			return Ok(null)
 		}
 
-		return this.compact(sessionId, agentId, messages)
+		return this.compact(sessionId, agentId, messages, runInference, lastActualPromptTokens)
 	}
 
 	/**
-	 * Compact conversation history by summarizing older messages.
+	 * Compact conversation history by asking the agent's own model to summarize
+	 * the older portion. The summarization call reuses the agent's existing
+	 * prompt cache via `runInference`, paying only for the trailing instruction
+	 * (a few hundred tokens) and the summary output — not the whole conversation
+	 * a second time.
 	 */
 	async compact(
 		sessionId: SessionId,
 		agentId: AgentId,
 		messages: LLMMessage[],
+		runInference: RunInferenceFn,
+		lastActualPromptTokens?: number,
 	): Promise<Result<CompactionResult, Error>> {
-		const originalTokens = estimateMessagesTokens(messages)
+		const originalTokens = lastActualPromptTokens ?? estimateMessagesTokens(messages)
 
 		this.logger.info('Starting context compaction', {
 			sessionId,
 			agentId,
 			messageCount: messages.length,
-			estimatedTokens: originalTokens,
+			originalTokens,
+			actualTokensReported: lastActualPromptTokens !== undefined,
 		})
 
-		// Split messages: keep recent, compact older
-		// Respect both count limit and token budget (whichever is hit first)
+		// Split messages: keep recent, compact older.
+		// Respect both count limit and token budget (whichever is hit first).
 		const keepCount = this.computeKeepCount(messages)
 		const toCompact = messages.slice(0, messages.length - keepCount)
 		const toKeep = messages.slice(messages.length - keepCount)
@@ -236,20 +281,16 @@ export class ContextCompactor {
 			})
 		}
 
-		// Format messages for summarization
-		const conversationText = toCompact
-			.map(formatMessageForSummary)
-			.join('\n\n')
-
-		// Offload history if enabled
+		// Offload the dropped messages to disk for forensics / replay.
+		// Best-effort; failures are logged but don't block compaction.
 		let historyPath: string | undefined
 		if (this.config.offloadHistory && this.historyOffloader) {
 			try {
+				const conversationText = toCompact.map(formatMessageForSummary).join('\n\n')
 				const pathPrefix = this.config.historyPathPrefix ?? DEFAULT_HISTORY_PATH_PREFIX
 				historyPath = await this.historyOffloader.offload(agentId, conversationText, pathPrefix)
 				this.logger.info('History offloaded', { sessionId, agentId, historyPath })
 			} catch (error) {
-				// History offloading is best-effort, log and continue
 				this.logger.warn('Failed to offload history', {
 					sessionId,
 					agentId,
@@ -258,18 +299,14 @@ export class ContextCompactor {
 			}
 		}
 
-		// Generate summary using LLM
-		const summaryResult = await this.llmProvider.inference({
-			model: this.config.model,
-			systemPrompt: this.config.summaryPrompt ?? CONTEXT_SUMMARY_PROMPT,
-			messages: [
-				{
-					role: 'user',
-					content: `Please summarize this conversation:\n\n${conversationText}`,
-				},
-			],
-			tools: [],
-		})
+		// Inline summarization: append the instruction as a trailing user message
+		// and let the host run inference with the agent's full live prefix. The
+		// agent's prompt cache from the previous turn covers everything up to
+		// (but not including) this instruction.
+		const summaryInstruction = this.config.summaryPrompt ?? DEFAULT_SUMMARY_INSTRUCTION
+		const summaryResult = await runInference([
+			{ role: 'user', content: summaryInstruction },
+		])
 
 		if (!summaryResult.ok) {
 			const llmError = summaryResult.error
@@ -283,9 +320,17 @@ export class ContextCompactor {
 
 		const summary = summaryResult.value.content ?? ''
 
-		// Create summary message (with history reference if offloaded)
+		if (!summary.trim()) {
+			this.logger.warn('Summarization returned empty content', { sessionId, agentId })
+			return Err(new Error('Compaction failed: model returned empty summary'))
+		}
+
+		// Replace the compacted portion with a single user-role summary message.
+		// Using `user` role (not `system`) so the wrap reads as part of the
+		// conversation flow — Anthropic recommends user-role for arbitrary
+		// mid-conversation context blocks.
 		const summaryMessage: LLMMessage = {
-			role: 'system',
+			role: 'user',
 			content: wrapContextSummary(summary, historyPath),
 		}
 

package/src/plugins/context-compact/plugin.ts

@@ -10,36 +10,45 @@ import { type CompactionConfig, ContextCompactor, createContextCompactedEvent, t
 import { FileHistoryOffloader } from './history-offloader.js'
 
 /**
- * Plugin config — session-level compaction settings.
+ * Plugin config — session-level (default) compaction settings.
+ * Individual agents may override fields via `contextCompactPlugin.configureAgent({ ... })`.
  */
 export interface ContextCompactPluginConfig {
 	compaction: CompactionConfig
 }
 
+/**
+ * Per-agent override. Any field omitted falls back to the session-level config.
+ * Used for cases like "orchestrator gets a tighter 50k threshold while subagents
+ * keep the default 200k".
+ */
+export type ContextCompactAgentConfig = Partial<CompactionConfig>
+
 export const contextCompactPlugin = definePlugin('context-compact')
 	.pluginConfig<ContextCompactPluginConfig>()
+	.agentConfig<ContextCompactAgentConfig>()
 	.context(async (ctx, pluginConfig) => {
 		const historyOffloader: HistoryOffloader | undefined = pluginConfig.compaction.offloadHistory
 			? new FileHistoryOffloader(ctx.environment.sessionDir, ctx.platform.fs)
 			: undefined
 
-		const compactor = new ContextCompactor(
-			ctx.llm,
-			ctx.logger,
-			pluginConfig.compaction,
-			historyOffloader,
-		)
-
-		return { compactor }
+		return { historyOffloader, sessionConfig: pluginConfig.compaction }
 	})
 	.hook('beforeInference', async (ctx) => {
-		const compactor = ctx.pluginContext.compactor
+		const { historyOffloader, sessionConfig } = ctx.pluginContext
+		const agentOverrides = ctx.pluginAgentConfig ?? {}
+		const effectiveConfig: CompactionConfig = { ...sessionConfig, ...agentOverrides }
+
+		const compactor = new ContextCompactor(ctx.logger, effectiveConfig, historyOffloader)
 		const historyLLMMessages = ctx.agentState.conversationHistory
+		const lastActualPromptTokens = ctx.agentState.lastInferenceMetrics?.promptTokens
 
 		const result = await compactor.compactIfNeeded(
 			ctx.sessionId,
 			ctx.agentId,
 			historyLLMMessages,
+			ctx.runAuxiliaryInference,
+			lastActualPromptTokens,
 		)
 
 		if (result.ok && result.value !== null) {

package/src/plugins/filesystem/filesystem.integration.test.ts

@@ -22,6 +22,14 @@ beforeAll(() => {
 	fs.writeFileSync(path.join(fixtureDir, 'hello.txt'), 'Hello, world!')
 	fs.writeFileSync(path.join(fixtureDir, 'multiline.txt'), Array.from({ length: 20 }, (_, i) => `Line ${i + 1}`).join('\n'))
 
+	// Create a minimal 1x1 PNG for image tests
+	const onePixelPng = Buffer.from(
+		'89504e470d0a1a0a0000000d49484452000000010000000108060000001f15c489000000'
+			+ '0a49444154789c6300010000000500010d0a2db40000000049454e44ae426082',
+		'hex',
+	)
+	fs.writeFileSync(path.join(fixtureDir, 'pixel.png'), onePixelPng)
+
 	// Create subdirectory with files
 	fs.mkdirSync(path.join(fixtureDir, 'subdir'), { recursive: true })
 	fs.writeFileSync(path.join(fixtureDir, 'subdir', 'nested.txt'), 'Nested content')
@@ -154,6 +162,42 @@ describe('filesystem plugin', () => {
 			await harness.shutdown()
 		})
 
+		it('read image file → file:// URL uses agent-visible input path, not resolved real path', async () => {
+			// Regression: previously read_file returned file://<realPath>, which the
+			// sandboxed FileStore then rejected when re-resolving on the next inference
+			// (it only accepts agent-visible paths like /home/user/session/...). The URL
+			// must echo input.path so it stays resolvable through fileStore.realPath().
+			const filePath = path.join(fixtureDir, 'pixel.png')
+			const harness = createFsHarness({
+				presets: [createFsPreset()],
+				llmProvider: MockLLMProvider.withSequence([
+					{
+						toolCalls: [{
+							id: ToolCallId('tc1'),
+							name: 'read_file',
+							input: { path: filePath },
+						}],
+					},
+					{ content: 'Done', toolCalls: [] },
+				]),
+			})
+
+			const session = await harness.createSession('test')
+			await session.sendAndWaitForIdle('Read image')
+
+			const callHistory = harness.llmProvider.getCallHistory()
+			const toolMessages = callHistory[1].messages.filter((m) => m.role === 'tool')
+			expect(toolMessages).toHaveLength(1)
+			const content = toolMessages[0].content
+			expect(Array.isArray(content)).toBe(true)
+			const blocks = content as Array<{ type: string; text?: string; imageUrl?: { url: string } }>
+			const imageBlock = blocks.find((b) => b.type === 'image_url')
+			expect(imageBlock).toBeDefined()
+			expect(imageBlock?.imageUrl?.url).toBe(`file://${filePath}`)
+
+			await harness.shutdown()
+		})
+
 		it('read a directory path → "is not a file" error', async () => {
 			const dirPath = path.join(fixtureDir, 'subdir')
 			const harness = createFsHarness({

package/src/plugins/filesystem/plugin.ts

@@ -158,16 +158,18 @@ export const filesystemPlugin = definePlugin('filesystem')
 						})
 					}
 
-					// Image files → return as multimodal image content
+					// Image files → return as multimodal image content.
+					// Store the agent-visible input.path (not the resolved real path):
+					// the URL survives into conversationHistory and gets re-resolved
+					// via fileStore.realPath() on every subsequent inference. In
+					// sandboxed mode, realPath() rejects already-resolved disk paths
+					// (only accepts the virtual prefix), so storing realPath would
+					// surface as "[Image unavailable: …]" on every later turn.
 					const mimeType = getImageMimeType(input.path)
 					if (mimeType) {
-						const realPathResult = fileStore.realPath(input.path)
-						if (!realPathResult.ok) {
-							return Err({ message: realPathResult.error, recoverable: false })
-						}
 						return Ok([
 							{ type: 'text', text: `Image: ${input.path} (${mimeType}, ${stats.size} bytes)` },
-							{ type: 'image_url', imageUrl: { url: `file://${realPathResult.value}` } },
+							{ type: 'image_url', imageUrl: { url: `file://${input.path}` } },
 						])
 					}
 

package/src/plugins/mailbox/mailbox.integration.test.ts

@@ -581,7 +581,7 @@ describe('mailbox plugin', () => {
 			await harness.shutdown()
 		})
 
-		it('empty-stop LLM response → agent retries; persistent empty → onError reports to parent', async () => {
+		it('empty-stop LLM response → agent retries; persistent empty → coalesces to WAITING, no error', async () => {
 			let workerCalls = 0
 			let orchestratorCalls = 0
 
@@ -603,31 +603,25 @@ describe('mailbox plugin', () => {
 						return { content: 'Done', toolCalls: [], finishReason: 'stop', metrics: MockLLMProvider.defaultMetrics() }
 					}
 					workerCalls++
-					// Always empty-stop → triggers retry until exhausted, then onError
+					// Always empty-stop → triggers retry until exhausted, then coalesces to WAITING
 					return { content: null, toolCalls: [], finishReason: 'stop', metrics: MockLLMProvider.defaultMetrics() }
 				},
 			})
 
 			const session = await harness.createSession('test')
-			await session.sendMessage('Start')
-
-			// Worker ends up errored (not idle); poll for the error message to parent.
-			const deadline = Date.now() + 5000
-			let errMsg: { message: { content: string; from: unknown } } | undefined
-			while (Date.now() < deadline) {
-				const events = await session.getEventsByType(mailboxEvents, 'mailbox_message')
-				errMsg = events.find(e =>
-					e.message.from === AgentId('worker_1')
-					&& typeof e.message.content === 'string'
-					&& e.message.content.startsWith('Agent encountered an error:'),
-				)
-				if (errMsg) break
-				await new Promise((r) => setTimeout(r, 50))
-			}
+			await session.sendAndWaitForIdle('Start')
 
 			// Initial + 2 retries = 3 worker LLM calls
 			expect(workerCalls).toBe(3)
-			expect(errMsg).toBeDefined()
+
+			// No error message to parent — exhaustion coalesces to WAITING, not failure
+			const events = await session.getEventsByType(mailboxEvents, 'mailbox_message')
+			const errMsg = events.find(e =>
+				e.message.from === AgentId('worker_1')
+				&& typeof e.message.content === 'string'
+				&& e.message.content.startsWith('Agent encountered an error:'),
+			)
+			expect(errMsg).toBeUndefined()
 
 			await harness.shutdown()
 		})

package/src/plugins/resources/plugin.ts

@@ -112,7 +112,10 @@ export const resourcesPlugin = definePlugin('resources')
 				await fs.writeFile(tempPath, input.fileBuffer)
 
 				try {
-					await exec('unzip', ['-o', '-q', tempPath, '-d', targetDir])
+					// `-x .git .git/*` so a stray .git entry in the ZIP can't overwrite the
+					// worktree's gitdir pointer (which silently breaks every subsequent git
+					// command in the workspace).
+					await exec('unzip', ['-o', '-q', tempPath, '-d', targetDir, '-x', '.git', '.git/*'])
 				} catch (error) {
 					const message = error instanceof Error ? error.message : String(error)
 					// unzip returns exit code 1 for warnings — still usable

package/src/plugins/uploads/preprocessors/image-classifier.ts

@@ -71,6 +71,7 @@ export class ImageClassifierPreprocessor implements Preprocessor {
 		mimeType: string,
 		ctx: PreprocessorContext,
 	): Promise<Result<PreprocessorResult, Error>> {
+		const totalStart = Date.now()
 		try {
 			// Check + stat image file
 			if (!(await this.fs.exists(filePath))) {
@@ -88,15 +89,21 @@ export class ImageClassifierPreprocessor implements Preprocessor {
 			}
 
 			// Try vision inference
+			const inferenceStart = Date.now()
 			const description = await this.describeImage(filePath, mimeType)
+			const inferenceDurationMs = Date.now() - inferenceStart
 
 			if (description) {
 				// Save description to file
 				const writeResult = await ctx.files.write('description.txt', description)
 
-				this.logger.debug('Image described successfully', {
+				this.logger.info('Image described successfully', {
 					filename,
+					mimeType,
+					sizeBytes: size,
 					descriptionLength: description.length,
+					inferenceDurationMs,
+					totalDurationMs: Date.now() - totalStart,
 				})
 
 				return Ok({
@@ -106,6 +113,12 @@ export class ImageClassifierPreprocessor implements Preprocessor {
 			}
 
 			// Fallback to basic metadata
+			this.logger.warn('Image description unavailable, falling back to metadata', {
+				filename,
+				mimeType,
+				sizeBytes: size,
+				inferenceDurationMs,
+			})
 			return Ok({
 				extractedContent: `[Image: ${filename}, ${this.formatSize(size)}, ${mimeType}]`,
 			})
@@ -113,7 +126,7 @@ export class ImageClassifierPreprocessor implements Preprocessor {
 			this.logger.error(
 				'Image classification failed',
 				error instanceof Error ? error : undefined,
-				{ filePath },
+				{ filePath, durationMs: Date.now() - totalStart },
 			)
 
 			// Return basic info on error instead of failing