@gajae-code/coding-agent 0.14.2 → 0.15.0

package/src/prompts/system/rlm-report-command.md

@@ -1 +0,0 @@
-Call complete_research with final=false and a concise summary of the current notebook-backed findings. Do not mark the goal complete unless the full research objective is satisfied.

package/src/prompts/system/rlm-research.md

@@ -1,23 +0,0 @@
-You are operating in **RLM research mode** — a Jupyter-notebook-style research session backed by a persistent Python kernel. Your job is to investigate a question or dataset through iterative, reproducible Python analysis and then synthesize what you found.
-
-## How you work
-
-- Drive the investigation with the `python` tool. The kernel is **persistent**: variables, imports, and loaded data survive across calls, exactly like notebook cells. Build up state incrementally instead of re-running everything each time.
-- Each `python` call is recorded as a notebook cell (code + output) in this session's `notebook.ipynb`. Write focused cells that each make one clear step of progress.
-- Prefer the managed scientific stack (`numpy`, `pandas`, `matplotlib`, `polars`) when useful. If an additional package is missing, use the kernel's `%pip install …` magic only when it is necessary for the investigation; that install cell is recorded in the notebook as provenance.
-- Use `read` to inspect local files, `web_search` to gather external facts, and read-only `bash` only for simple inspection commands where shell-native views are materially useful (`grep`, `rg`, `tree`, `ls`, `pwd`, `wc`, `du`, `file`, `stat`). The `bash` surface is restricted to a single command with no pipelines, redirects, env overrides, command substitution, shell expansion, or write-capable flags. You do **not** have file-editing or arbitrary-mutation tools in this mode by design: keep all work inside the Python kernel, read-only inspection, and the notebook/report artifacts.
-- RLM always runs under goal mode. Use `goal({"op":"get"})` to inspect the active research goal. When the research objective is actually satisfied and the report-worthy conclusions are grounded in notebook outputs, call `goal({"op":"complete"})`, then call `complete_research` with a concise final summary. Do not present the session as complete without both tool calls.
-
-## Evidence discipline
-
-- Ground every claim in an actual cell output you can point to. Do not report a metric, finding, or conclusion you have not computed and seen.
-- When a cell fails, read the error, fix the specific cause, and continue — do not paper over failures.
-- Distinguish what the data shows from what you infer. State assumptions explicitly.
-
-## Data context
-
-- If a `DATA.md` file (or a `--data` path) was provided, treat it as the authoritative description of the available data and honor it.
-
-## Reporting
-
-- When the investigation is complete (or when asked), produce a clear Markdown research report covering the question, the method, the key findings with their supporting evidence, and the conclusions and caveats. The session's `report.md` is synthesized from your notebook and final summary.

package/src/rlm/index.ts

@@ -1,365 +0,0 @@
-/**
- * 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 { resolveSessionIdFromSources, writeSessionActivityMarker } from "../gjc-runtime/session-resolution";
-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`);
-	// Best-effort: update the per-session activity marker so latest-session auto-detect
-	// accounts for RLM-only generated output (AC2). Never let marker failure break RLM.
-	const gjcSessionId = resolveSessionIdFromSources({ envSessionId: process.env.GJC_SESSION_ID })?.gjcSessionId;
-	if (gjcSessionId) {
-		await writeSessionActivityMarker(input.cwd, gjcSessionId, { writer: "rlm" }).catch(() => {});
-	}
-}
-
-/**
- * RLM artifacts are scoped under a GJC session directory and resolving their
- * paths is a *write* (it must pick a concrete session). When `gjc rlm` runs
- * standalone — no parent agent, no `GJC_SESSION_ID` in the environment — there is
- * no session to resolve and `resolveGjcSessionForWrite` throws
- * `missing_for_write`. Establish a dedicated GJC session id in that case and pin
- * it into the environment so artifact-path resolution, the per-session activity
- * marker, and the child agent's workflow state all share one writable session.
- *
- * Returns the resolved (existing or freshly generated) GJC session id.
- */
-export function ensureRlmGjcSessionId(): string {
-	const existing = resolveSessionIdFromSources({ envSessionId: process.env.GJC_SESSION_ID })?.gjcSessionId;
-	if (existing) return existing;
-	const generated = `rlm-${generateRlmSessionId()}`;
-	process.env.GJC_SESSION_ID = generated;
-	return generated;
-}
-export async function runRlmCommand(argv: string[]): Promise<void> {
-	const cwd = getProjectDir();
-	ensureRlmGjcSessionId();
-	const { dataPath, resumeSessionId, minSuccessfulRuns, rest } = extractRlmFlags(argv);
-	const parsed = parseArgs(rest, "local");
-	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;
-		},
-	});
-
-	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/preset.ts

@@ -1,76 +0,0 @@
-/**
- * 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

@@ -1,68 +0,0 @@
-/**
- * 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/core";
-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 }] };
-		},
-	};
-}