@gajae-code/coding-agent 0.5.4 → 0.6.1

package/src/rlm/index.ts

@@ -0,0 +1,339 @@
+/**
+ * RLM (research) mode entry point.
+ *
+ * Composes a research session over the existing agent/session loop (python
+ * kernel + read + web_search + read-only bash), optional DATA.md context, live
+ * notebook.ipynb, first-class complete_research report synthesis, autonomous
+ * goal-arg execution, and resumable .gjc/rlm/<session> artifacts.
+ */
+import * as fs from "node:fs/promises";
+import { getProjectDir } from "@gajae-code/utils";
+import { type Args, parseArgs } from "../cli/args";
+import { disposeKernelSessionsByOwner } from "../eval/py/executor";
+import type { CustomTool } from "../extensibility/custom-tools/types";
+import { type RlmPreset, runRootCommand } from "../main";
+import rlmReportCommandPrompt from "../prompts/system/rlm-report-command.md" with { type: "text" };
+import type { CreateAgentSessionOptions } from "../sdk";
+import type { AgentSession } from "../session/agent-session";
+import {
+	ensureRlmSessionDir,
+	generateRlmSessionId,
+	readRlmNotebookIfPresent,
+	resolveRlmArtifactPaths,
+	rlmSessionExists,
+} from "./artifacts";
+import {
+	countSuccessfulNotebookRuns,
+	createRlmCompleteResearchTool,
+	summarizeNotebookForReplay,
+	writeRlmReport,
+} from "./complete-research-tool";
+import { loadRlmDataContext, type RlmDataContext } from "./data-context";
+import { RlmNotebookWriter } from "./notebook";
+import { assertRlmToolAllowlist, buildRlmSystemPrompt, isRlmToolAllowed, RLM_READ_ONLY_BASH_PREFIXES } from "./preset";
+import { createRlmPythonTool } from "./python-tool";
+import type { RlmArtifactPaths, RlmSessionMetadata } from "./types";
+
+interface ExtractedRlmFlags {
+	dataPath: string | undefined;
+	resumeSessionId: string | undefined;
+	minSuccessfulRuns: number;
+	rest: string[];
+}
+
+export interface RlmPresetOptions {
+	dataContext: RlmDataContext | null;
+	pythonTool: CustomTool;
+	completeResearchTool?: CustomTool;
+	objective?: string;
+	resumeContext?: string;
+	onSessionReady?: (session: AgentSession) => void;
+}
+
+interface RlmRunController {
+	completed: boolean;
+	finalSummary: string | undefined;
+	session: AgentSession | undefined;
+}
+
+function parseNonNegativeIntegerFlag(name: string, value: string | undefined): number {
+	if (value === undefined || value.trim().length === 0) {
+		throw new Error(`${name} requires a non-negative integer value.`);
+	}
+	const parsed = Number(value);
+	if (!Number.isInteger(parsed) || parsed < 0) {
+		throw new Error(`${name} requires a non-negative integer value.`);
+	}
+	return parsed;
+}
+
+/** Pull RLM-owned flags out of argv; the remainder is forwarded to the root command. */
+export function extractRlmFlags(argv: string[]): ExtractedRlmFlags {
+	const rest: string[] = [];
+	let dataPath: string | undefined;
+	let resumeSessionId: string | undefined;
+	let minSuccessfulRuns = 0;
+	for (let i = 0; i < argv.length; i++) {
+		const arg = argv[i];
+		if (arg === "--data") {
+			dataPath = argv[i + 1];
+			i += 1;
+		} else if (arg.startsWith("--data=")) {
+			dataPath = arg.slice("--data=".length);
+		} else if (arg === "--resume" || arg === "-r") {
+			const next = argv[i + 1];
+			if (!next || next.startsWith("-")) throw new Error("gjc rlm --resume requires an RLM session id.");
+			resumeSessionId = next;
+			i += 1;
+		} else if (arg.startsWith("--resume=")) {
+			resumeSessionId = arg.slice("--resume=".length);
+		} else if (arg === "--min-successful-runs") {
+			minSuccessfulRuns = parseNonNegativeIntegerFlag(arg, argv[i + 1]);
+			i += 1;
+		} else if (arg.startsWith("--min-successful-runs=")) {
+			minSuccessfulRuns = parseNonNegativeIntegerFlag(
+				"--min-successful-runs",
+				arg.slice("--min-successful-runs=".length),
+			);
+		} else {
+			rest.push(arg);
+		}
+	}
+	return { dataPath, resumeSessionId, minSuccessfulRuns, rest };
+}
+
+/** @deprecated use extractRlmFlags; retained for tests and compatibility. */
+export function extractDataFlag(argv: string[]): { dataPath: string | undefined; rest: string[] } {
+	const { dataPath, rest } = extractRlmFlags(argv);
+	return { dataPath, rest };
+}
+
+export function createRlmPreset({
+	dataContext,
+	pythonTool,
+	completeResearchTool,
+	objective,
+	resumeContext,
+	onSessionReady,
+}: RlmPresetOptions): RlmPreset {
+	const resolvedObjective = objective ?? buildRlmGoalObjective({ messages: [], dataContext });
+	const customTools = completeResearchTool ? [pythonTool, completeResearchTool] : [pythonTool];
+	return {
+		applyOptions: (options: CreateAgentSessionOptions, settings) => {
+			options.systemPrompt = buildRlmSystemPrompt(dataContext, resumeContext);
+			options.customTools = customTools;
+			options.toolNames = ["read", "web_search", "search_tool_bm25", "bash", "goal"];
+			options.requireYieldTool = false;
+			options.skills = [];
+			options.rules = [];
+			options.disableExtensionDiscovery = true;
+			options.extensions = [];
+			options.additionalExtensionPaths = [];
+			options.preloadedExtensions = undefined;
+			options.bashAllowedPrefixes = [...RLM_READ_ONLY_BASH_PREFIXES];
+			options.bashRestrictionProfile = "read-only";
+			options.goalToolAllowedOps = ["get", "complete"];
+			options.discoverableToolAllowedNames = [];
+			options.slashCommands = [
+				...(options.slashCommands ?? []),
+				{
+					name: "report",
+					description: "Synthesize a draft RLM report from the current notebook",
+					content: rlmReportCommandPrompt,
+					source: "rlm",
+				},
+			];
+			// RLM always runs in goal mode; recipe injection stays outside the research surface.
+			settings.override("goal.enabled", true);
+			settings.override("tools.discoveryMode", "all");
+			settings.override("recipe.enabled", false);
+		},
+		onSessionCreated: async (session: AgentSession) => {
+			onSessionReady?.(session);
+			await ensureRlmGoalMode(session, resolvedObjective);
+			// Hard boundary: fail launch if any non-allowlisted tool slipped into the active set.
+			assertRlmToolAllowlist(session.getActiveToolNames());
+		},
+	};
+}
+
+async function ensureRlmGoalMode(session: AgentSession, objective: string): Promise<void> {
+	const current = session.getGoalModeState();
+	if (current?.goal && current.goal.status !== "complete" && current.goal.status !== "dropped") {
+		if (!current.enabled || current.goal.status === "paused") {
+			await session.goalRuntime.resumeGoal();
+		}
+	} else {
+		await session.goalRuntime.createGoal({ objective });
+	}
+	await session.setActiveToolsByName([...new Set([...session.getActiveToolNames().filter(isRlmToolAllowed), "goal"])]);
+}
+
+export function buildRlmGoalObjective(input: {
+	messages: readonly string[];
+	dataContext: RlmDataContext | null;
+}): string {
+	const prompt = input.messages
+		.map(message => message.trim())
+		.filter(Boolean)
+		.join("\n\n");
+	if (prompt.length > 0) return prompt;
+	if (input.dataContext) {
+		return `Complete an RLM research session using data context ${input.dataContext.path}, grounding conclusions in notebook outputs and finishing with a report.`;
+	}
+	return "Complete this RLM research session, grounding conclusions in notebook outputs and finishing with a report.";
+}
+export function isRlmAutonomousRun(parsed: Pick<Args, "print" | "mode" | "messages">, pipedStdin: boolean): boolean {
+	return parsed.print === true || parsed.mode !== undefined || pipedStdin;
+}
+
+export function prepareRlmLaunchMode(parsed: Args, pipedStdin: boolean): boolean {
+	const autonomous = isRlmAutonomousRun(parsed, pipedStdin);
+	if (autonomous && parsed.mode === undefined) {
+		parsed.print = true;
+	}
+	return autonomous;
+}
+
+async function loadExistingMetadata(paths: RlmArtifactPaths): Promise<RlmSessionMetadata | undefined> {
+	try {
+		return (await Bun.file(paths.metadataPath).json()) as RlmSessionMetadata;
+	} catch {
+		return undefined;
+	}
+}
+
+async function writeRlmMetadata(input: {
+	paths: RlmArtifactPaths;
+	sessionId: string;
+	createdAt: string;
+	cwd: string;
+	dataPath: string | null;
+	cellCount: number;
+	mode: "interactive" | "autonomous";
+	resumedFrom: string | null;
+	completedAt: string | null;
+	finalSummary: string | null;
+	minSuccessfulRuns: number;
+	successfulRuns: number;
+}): Promise<void> {
+	const metadata: RlmSessionMetadata = {
+		sessionId: input.sessionId,
+		createdAt: input.createdAt,
+		cwd: input.cwd,
+		dataPath: input.dataPath,
+		cellCount: input.cellCount,
+		mode: input.mode,
+		resumedFrom: input.resumedFrom,
+		completedAt: input.completedAt,
+		finalSummary: input.finalSummary,
+		minSuccessfulRuns: input.minSuccessfulRuns,
+		successfulRuns: input.successfulRuns,
+	};
+	await Bun.write(input.paths.metadataPath, `${JSON.stringify(metadata, null, 2)}\n`);
+}
+
+export async function runRlmCommand(argv: string[]): Promise<void> {
+	const cwd = getProjectDir();
+	const { dataPath, resumeSessionId, minSuccessfulRuns, rest } = extractRlmFlags(argv);
+	const dataContext = await loadRlmDataContext(cwd, dataPath);
+
+	const sessionId = resumeSessionId ?? generateRlmSessionId();
+	const paths = resolveRlmArtifactPaths(cwd, sessionId);
+	if (resumeSessionId && !(await rlmSessionExists(cwd, resumeSessionId))) {
+		throw new Error(`RLM session not found: ${resumeSessionId}`);
+	}
+	await ensureRlmSessionDir(paths);
+	await fs.mkdir(paths.agentSessionDir, { recursive: true });
+
+	const existingNotebook = resumeSessionId ? await readRlmNotebookIfPresent(cwd, sessionId) : undefined;
+	const existingMetadata = await loadExistingMetadata(paths);
+	const notebook = new RlmNotebookWriter(paths.notebookPath, existingNotebook);
+	const pythonTool = createRlmPythonTool({
+		cwd,
+		sessionId,
+		artifactsDir: paths.dir,
+		notebook,
+		managedWorkspaceVenv: true,
+	});
+	const controller: RlmRunController = { completed: false, finalSummary: undefined, session: undefined };
+	const reportTitle = `RLM research session ${sessionId}`;
+	const completeResearchTool = createRlmCompleteResearchTool({
+		paths,
+		notebook,
+		title: reportTitle,
+		dataPath: dataContext?.path ?? null,
+		minSuccessfulRuns,
+		getGoalStatus: () => controller.session?.getGoalModeState()?.goal.status,
+		markCompleted: summary => {
+			controller.completed = true;
+			controller.finalSummary = summary;
+		},
+	});
+
+	const parsed = parseArgs(rest);
+	parsed.sessionDir = paths.agentSessionDir;
+	if (resumeSessionId) {
+		parsed.continue = true;
+	}
+	// Piped stdin (non-TTY), explicit --print, and explicit --mode run as autonomous
+	// research. Positional argv messages seed the interactive RLM shell, so
+	// `gjc rlm "question"` still loads the TUI instead of being coerced into
+	// print mode.
+	const pipedStdin = process.stdin.isTTY === false;
+	const autonomous = prepareRlmLaunchMode(parsed, pipedStdin);
+	const resumeContext = existingNotebook ? summarizeNotebookForReplay(existingNotebook) : undefined;
+	const preset = createRlmPreset({
+		dataContext,
+		pythonTool,
+		completeResearchTool,
+		objective: buildRlmGoalObjective({ messages: parsed.messages, dataContext }),
+		resumeContext,
+		onSessionReady: session => {
+			controller.session = session;
+		},
+	});
+	if (autonomous) {
+		preset.applyOptions = ((applyOptions: RlmPreset["applyOptions"]) => (options, settings) => {
+			applyOptions(options, settings);
+			options.shouldPause = () => controller.completed;
+		})(preset.applyOptions);
+	}
+
+	let runError: unknown;
+	try {
+		await runRootCommand(parsed, rest, { rlmPreset: preset, suppressProcessExit: autonomous });
+	} catch (error) {
+		runError = error;
+		throw error;
+	} finally {
+		// The RLM python tool owns a retained kernel keyed by `rlm:<sessionId>`; the
+		// session's own dispose targets a different owner id, so release it here so
+		// the persistent kernel subprocess is reaped on every exit path.
+		await disposeKernelSessionsByOwner(`rlm:${sessionId}`).catch(() => {});
+		await writeRlmReport({
+			paths,
+			notebook,
+			title: reportTitle,
+			summary: controller.finalSummary,
+			dataPath: dataContext?.path ?? null,
+		});
+		await writeRlmMetadata({
+			paths,
+			sessionId,
+			createdAt: existingMetadata?.createdAt ?? new Date().toISOString(),
+			cwd,
+			dataPath: dataContext?.path ?? null,
+			cellCount: notebook.cellCount,
+			mode: autonomous ? "autonomous" : "interactive",
+			resumedFrom: resumeSessionId ?? null,
+			completedAt: controller.completed ? new Date().toISOString() : null,
+			finalSummary: controller.finalSummary ?? null,
+			minSuccessfulRuns,
+			successfulRuns: countSuccessfulNotebookRuns(notebook.document),
+		});
+	}
+	if (autonomous && !controller.completed && runError === undefined) {
+		throw new Error("RLM autonomous session ended before complete_research finalized the report.");
+	}
+}

package/src/rlm/notebook.ts

@@ -0,0 +1,108 @@
+/**
+ * RLM live notebook writer: appends executed cells to notebook.ipynb with a
+ * single per-session write queue and atomic temp-file-then-rename writes, then
+ * validates the persisted file via readNotebookDocument.
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import {
+	createEmptyNotebook,
+	createNotebookCell,
+	type NotebookDocument,
+	readNotebookDocument,
+	serializeNotebookDocument,
+	splitNotebookSource,
+} from "../edit/notebook";
+import type { RlmCellResult } from "./types";
+
+function buildCodeOutputs(result: RlmCellResult): unknown[] {
+	const outputs: unknown[] = [];
+	if (result.output.length > 0) {
+		outputs.push({
+			output_type: "stream",
+			name: result.exitCode !== undefined && result.exitCode !== 0 ? "stderr" : "stdout",
+			text: splitNotebookSource(result.output),
+		});
+	}
+	for (const display of result.displayOutputs) {
+		if (display.type === "image") {
+			outputs.push({ output_type: "display_data", data: { [display.mimeType]: display.data }, metadata: {} });
+		} else if (display.type === "json") {
+			outputs.push({ output_type: "display_data", data: { "application/json": display.data }, metadata: {} });
+		}
+	}
+	if (result.cancelled) {
+		outputs.push({ output_type: "stream", name: "stderr", text: ["[cell cancelled]\n"] });
+	}
+	if (result.truncated) {
+		outputs.push({ output_type: "stream", name: "stderr", text: ["[output truncated]\n"] });
+	}
+	return outputs;
+}
+
+export class RlmNotebookWriter {
+	readonly #notebookPath: string;
+	readonly #document: NotebookDocument;
+	#queue: Promise<void> = Promise.resolve();
+
+	constructor(notebookPath: string, initial?: NotebookDocument) {
+		this.#notebookPath = notebookPath;
+		this.#document = initial ?? createEmptyNotebook();
+	}
+
+	get document(): NotebookDocument {
+		return this.#document;
+	}
+
+	get cellCount(): number {
+		return this.#document.cells.length;
+	}
+
+	appendMarkdown(source: string): Promise<void> {
+		this.#document.cells.push(createNotebookCell("markdown", source));
+		return this.#enqueueWrite();
+	}
+
+	appendCode(code: string, result: RlmCellResult): Promise<void> {
+		const cell = createNotebookCell("code", code);
+		cell.execution_count = this.#nextExecutionCount();
+		cell.outputs = buildCodeOutputs(result);
+		this.#document.cells.push(cell);
+		return this.#enqueueWrite();
+	}
+
+	/** Resolve once all queued writes have flushed. */
+	flush(): Promise<void> {
+		return this.#queue;
+	}
+
+	#nextExecutionCount(): number {
+		let max = 0;
+		for (const cell of this.#document.cells) {
+			const count = cell.execution_count;
+			if (typeof count === "number" && count > max) max = count;
+		}
+		return max + 1;
+	}
+
+	#enqueueWrite(): Promise<void> {
+		const snapshot = serializeNotebookDocument(this.#document);
+		this.#queue = this.#queue.then(() => this.#atomicWrite(snapshot));
+		return this.#queue;
+	}
+
+	async #atomicWrite(content: string): Promise<void> {
+		const dir = path.dirname(this.#notebookPath);
+		const base = path.basename(this.#notebookPath);
+		const tmp = path.join(dir, `.${base}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2, 8)}.tmp`);
+		await Bun.write(tmp, content);
+		try {
+			await fs.rename(tmp, this.#notebookPath);
+		} catch (error) {
+			await fs.rm(tmp, { force: true });
+			throw error;
+		}
+		// Post-write validation: surfaces corruption immediately.
+		await readNotebookDocument(this.#notebookPath, this.#notebookPath);
+	}
+}

package/src/rlm/preset.ts

@@ -0,0 +1,76 @@
+/**
+ * RLM research preset: the static research system prompt, the exact tool
+ * allowlist, and a hard boundary assertion that fails launch if any
+ * non-allowlisted tool is active.
+ */
+import rlmResearchPrompt from "../prompts/system/rlm-research.md" with { type: "text" };
+import type { RlmDataContext } from "./data-context";
+
+/**
+ * tool; `read` and `web_search` are the existing built-ins. `bash` is exposed
+ * through the read-only restriction profile below for inspection commands only,
+ * and `goal` is required so RLM sessions cannot finish without explicit goal
+ * completion. Everything else (edit, write, task, skill, browser, eval-js, ...) is excluded.
+ */
+export const RLM_READ_ONLY_BASH_PREFIXES: readonly string[] = [
+	"grep",
+	"rg",
+	"tree",
+	"ls",
+	"pwd",
+	"wc",
+	"du",
+	"file",
+	"stat",
+];
+export const RLM_TOOL_ALLOWLIST: readonly string[] = [
+	"python",
+	"read",
+	"web_search",
+	"search_tool_bm25",
+	"bash",
+	"goal",
+	"complete_research",
+];
+
+export function isRlmToolAllowed(name: string): boolean {
+	return RLM_TOOL_ALLOWLIST.includes(name.toLowerCase());
+}
+
+/**
+ * Hard boundary: throws if any active tool is outside the allowlist. Call this
+ * after the session's tool registry is fully assembled and before running, so a
+ * tool leaked in by defaults/discovery/extensions fails the launch loudly.
+ */
+export function assertRlmToolAllowlist(activeToolNames: readonly string[]): void {
+	const leaked = activeToolNames.filter(name => !isRlmToolAllowed(name));
+	if (leaked.length > 0) {
+		throw new Error(
+			`RLM tool boundary violation: non-allowlisted active tool(s) [${leaked.join(", ")}]. ` +
+				`RLM mode allows only: ${RLM_TOOL_ALLOWLIST.join(", ")}.`,
+		);
+	}
+}
+
+/** The research prompt text (exported for testing / prompt assembly). */
+export const RLM_RESEARCH_PROMPT: string = rlmResearchPrompt;
+
+/**
+ * Build the systemPrompt transform for createAgentSession: appends the research
+ * prompt, data context, and prior-notebook replay context to the default blocks.
+ */
+export function buildRlmSystemPrompt(
+	dataContext: RlmDataContext | null,
+	resumeContext?: string,
+): (defaultPrompt: string[]) => string[] {
+	return (defaultPrompt: string[]): string[] => {
+		const blocks = [...defaultPrompt, rlmResearchPrompt];
+		if (dataContext) {
+			blocks.push(`# Data context (from ${dataContext.path})\n\n${dataContext.content}`);
+		}
+		if (resumeContext && resumeContext.trim().length > 0) {
+			blocks.push(`# Prior notebook replay context\n\n${resumeContext}`);
+		}
+		return blocks;
+	};
+}

package/src/rlm/python-tool.ts

@@ -0,0 +1,68 @@
+/**
+ * RLM `python` tool: the model-facing research execution tool. Wraps the shared
+ * persistent Python kernel executor and records every call as a notebook cell.
+ */
+import type { AgentToolResult } from "@gajae-code/agent-core";
+import { type Static, z } from "@gajae-code/ai";
+import { executePython } from "../eval/py/executor";
+import { RLM_MANAGED_PYTHON_PACKAGES } from "../eval/py/runtime";
+import type { CustomTool } from "../extensibility/custom-tools/types";
+import type { RlmNotebookWriter } from "./notebook";
+import type { RlmCellResult } from "./types";
+
+export const RLM_PYTHON_TOOL_NAME = "python";
+
+export interface RlmPythonToolContext {
+	cwd: string;
+	sessionId: string;
+	artifactsDir: string;
+	notebook: RlmNotebookWriter;
+	managedWorkspaceVenv?: boolean;
+}
+
+const paramsSchema = z.object({
+	code: z
+		.string()
+		.describe("Python source to execute in the persistent research kernel. State persists across calls."),
+});
+
+export function createRlmPythonTool(rlm: RlmPythonToolContext): CustomTool<typeof paramsSchema> {
+	return {
+		name: RLM_PYTHON_TOOL_NAME,
+		label: "Python",
+		description:
+			"Execute Python in the persistent research kernel. Variables, imports, and loaded data persist across calls like notebook cells. Every call is recorded as a cell in the session notebook.",
+		parameters: paramsSchema,
+		strict: true,
+		concurrency: "exclusive",
+		async execute(
+			_toolCallId: string,
+			params: Static<typeof paramsSchema>,
+			_onUpdate,
+			_ctx,
+			signal?: AbortSignal,
+		): Promise<AgentToolResult> {
+			const result = await executePython(params.code, {
+				cwd: rlm.cwd,
+				kernelMode: "session",
+				sessionId: `rlm:${rlm.sessionId}`,
+				kernelOwnerId: `rlm:${rlm.sessionId}`,
+				artifactsDir: rlm.artifactsDir,
+				runtimeOptions: rlm.managedWorkspaceVenv
+					? { managedWorkspaceVenv: true, seedPackages: RLM_MANAGED_PYTHON_PACKAGES }
+					: undefined,
+				signal,
+			});
+			const cell: RlmCellResult = {
+				output: result.output,
+				exitCode: result.exitCode,
+				cancelled: result.cancelled,
+				truncated: result.truncated,
+				displayOutputs: result.displayOutputs,
+			};
+			await rlm.notebook.appendCode(params.code, cell);
+			const text = result.output.length > 0 ? result.output : "(no output)";
+			return { content: [{ type: "text", text }] };
+		},
+	};
+}

package/src/rlm/report.ts

@@ -0,0 +1,70 @@
+/**
+ * Deterministic RLM report synthesis: turns the accumulated notebook (plus an
+ * optional model-provided summary) into a Markdown research report.
+ */
+import type { NotebookCell, NotebookDocument } from "../edit/notebook";
+
+export interface RlmReportInput {
+	title: string;
+	summary?: string;
+	notebook: NotebookDocument;
+	dataPath?: string | null;
+	generatedAt?: string;
+	maxOutputChars?: number;
+}
+
+function cellText(value: string | string[] | undefined): string {
+	if (value === undefined) return "";
+	return Array.isArray(value) ? value.join("") : value;
+}
+
+function streamOutputText(cell: NotebookCell): string {
+	const outputs = Array.isArray(cell.outputs) ? cell.outputs : [];
+	const parts: string[] = [];
+	for (const out of outputs) {
+		if (out && typeof out === "object" && (out as Record<string, unknown>).output_type === "stream") {
+			parts.push(cellText((out as Record<string, unknown>).text as string | string[] | undefined));
+		}
+	}
+	return parts.join("");
+}
+
+export function synthesizeRlmReport(input: RlmReportInput): string {
+	const generatedAt = input.generatedAt ?? new Date().toISOString();
+	const maxOutput = input.maxOutputChars ?? 4000;
+	const codeCells = input.notebook.cells.filter(cell => cell.cell_type === "code");
+
+	const lines: string[] = [];
+	lines.push(`# ${input.title}`, "");
+	lines.push(`- Generated: ${generatedAt}`);
+	lines.push(`- Cells executed: ${codeCells.length}`);
+	if (input.dataPath) {
+		lines.push(`- Data context: ${input.dataPath}`);
+	}
+	lines.push("");
+
+	if (input.summary && input.summary.trim().length > 0) {
+		lines.push("## Summary", "", input.summary.trim(), "");
+	}
+
+	lines.push("## Notebook", "");
+	let codeIndex = 0;
+	for (const cell of input.notebook.cells) {
+		if (cell.cell_type === "markdown") {
+			const text = cellText(cell.source).trim();
+			if (text.length > 0) {
+				lines.push(text, "");
+			}
+		} else if (cell.cell_type === "code") {
+			codeIndex += 1;
+			lines.push(`### Cell ${codeIndex}`, "", "```python", cellText(cell.source).trimEnd(), "```", "");
+			const output = streamOutputText(cell).trimEnd();
+			if (output.length > 0) {
+				const shown = output.length > maxOutput ? `${output.slice(0, maxOutput)}\n... [truncated]` : output;
+				lines.push("```", shown, "```", "");
+			}
+		}
+	}
+
+	return `${lines.join("\n").trimEnd()}\n`;
+}

package/src/rlm/types.ts

@@ -0,0 +1,40 @@
+/**
+ * Shared types for RLM (research) mode.
+ */
+import type { KernelDisplayOutput } from "../eval/py/kernel";
+
+export interface RlmArtifactPaths {
+	/** Absolute session directory: <cwd>/.gjc/rlm/<sessionId>/ */
+	dir: string;
+	/** Absolute path to the live notebook.ipynb */
+	notebookPath: string;
+	/** Absolute path to the synthesized report.md */
+	reportPath: string;
+	/** Absolute path to the session metadata.json */
+	metadataPath: string;
+	/** Directory for the underlying GJC conversation session files. */
+	agentSessionDir: string;
+}
+
+/** Outcome of a single RLM python cell execution. */
+export interface RlmCellResult {
+	output: string;
+	exitCode: number | undefined;
+	cancelled: boolean;
+	truncated: boolean;
+	displayOutputs: KernelDisplayOutput[];
+}
+
+export interface RlmSessionMetadata {
+	sessionId: string;
+	createdAt: string;
+	cwd: string;
+	dataPath: string | null;
+	cellCount: number;
+	mode?: "interactive" | "autonomous";
+	resumedFrom?: string | null;
+	completedAt?: string | null;
+	finalSummary?: string | null;
+	minSuccessfulRuns?: number;
+	successfulRuns?: number;
+}