@code-yeongyu/senpi-codemode 2026.7.25-2 → 2026.7.26

package/src/tool/types.ts

@@ -1,5 +1,5 @@
 import type { AgentToolResult, AgentToolUpdateCallback } from "@code-yeongyu/senpi";
-import { Type } from "typebox";
+import { type TUnsafe, Type } from "typebox";
 import type { HostToKernelMessage, KernelToHostMessage } from "../bridge/protocol.ts";
 import type { TruncationMeta } from "../output/output-meta.ts";
 
@@ -11,37 +11,75 @@ export function enabledLanguageList(enabled: EnabledEvalLanguages): EvalLanguage
 	return evalLanguageOrder.filter((language) => enabled[language]);
 }
 
+export interface EvalToolInput {
+	readonly language: EvalLanguage;
+	readonly code: string;
+	readonly action?: "run";
+	readonly title?: string;
+	readonly timeout?: number;
+	readonly on_timeout?: "detach" | "error";
+	readonly reset?: boolean;
+}
+
+export interface EvalControlInput {
+	readonly action: "peek" | "stop";
+	readonly cell_id: string;
+}
+
+export type EvalToolRequest = EvalToolInput | EvalControlInput;
+
 const fullEvalInputSchema = Type.Object({
-	language: Type.Union([Type.Literal("py"), Type.Literal("js"), Type.Literal("rb"), Type.Literal("jl")]),
-	code: Type.String({ description: "Cell body, verbatim." }),
+	action: Type.Optional(
+		Type.Union([Type.Literal("run"), Type.Literal("peek"), Type.Literal("stop")], {
+			description: "Defaults to run. peek and stop require cell_id.",
+		}),
+	),
+	language: Type.Optional(
+		Type.Union([Type.Literal("py"), Type.Literal("js"), Type.Literal("rb"), Type.Literal("jl")]),
+	),
+	code: Type.Optional(Type.String({ description: "Cell body, verbatim." })),
 	title: Type.Optional(Type.String({ description: "Short transcript label." })),
 	timeout: Type.Optional(Type.Number({ minimum: 1, description: "Timeout in seconds." })),
+	on_timeout: Type.Optional(
+		Type.Union([Type.Literal("detach"), Type.Literal("error")], {
+			description: "Timeout behavior. Interactive sessions detach by default; print/json sessions error by default.",
+		}),
+	),
 	reset: Type.Optional(Type.Boolean({ description: "Reset this language kernel before running." })),
+	cell_id: Type.Optional(Type.String({ description: "Detached eval cell id for peek or stop." })),
 });
 
-export function createEvalInputSchema(enabled: EnabledEvalLanguages): typeof fullEvalInputSchema {
+/** Runtime accepts a discriminated run/control union. */
+export type EvalInputSchema = TUnsafe<EvalToolRequest> & Pick<typeof fullEvalInputSchema, "properties">;
+
+export function createEvalInputSchema(enabled: EnabledEvalLanguages): EvalInputSchema {
 	const languages = enabledLanguageList(enabled);
 	if (languages.length === 0) throw new Error("eval requires at least one enabled language");
 	const languageSchema =
 		languages.length === 1
 			? Type.Union([Type.Literal(languages[0])])
 			: Type.Union(languages.map((item) => Type.Literal(item)));
-	return Type.Object({
-		language: languageSchema,
-		code: Type.String({ description: "Cell body, verbatim." }),
-		title: Type.Optional(Type.String({ description: "Short transcript label." })),
-		timeout: Type.Optional(Type.Number({ minimum: 1, description: "Timeout in seconds." })),
-		reset: Type.Optional(Type.Boolean({ description: "Reset this language kernel before running." })),
-	}) as typeof fullEvalInputSchema;
-}
-
-export type EvalInputSchema = typeof fullEvalInputSchema;
-export interface EvalToolInput {
-	readonly language: EvalLanguage;
-	readonly code: string;
-	readonly title?: string;
-	readonly timeout?: number;
-	readonly reset?: boolean;
+	return Type.Unsafe<EvalToolRequest>(
+		Type.Object({
+			action: Type.Optional(
+				Type.Union([Type.Literal("run"), Type.Literal("peek"), Type.Literal("stop")], {
+					description: "Defaults to run. peek and stop require cell_id.",
+				}),
+			),
+			language: Type.Optional(languageSchema),
+			code: Type.Optional(Type.String({ description: "Cell body, verbatim." })),
+			title: Type.Optional(Type.String({ description: "Short transcript label." })),
+			timeout: Type.Optional(Type.Number({ minimum: 1, description: "Timeout in seconds." })),
+			on_timeout: Type.Optional(
+				Type.Union([Type.Literal("detach"), Type.Literal("error")], {
+					description:
+						"Timeout behavior. Interactive sessions detach by default; print/json sessions error by default.",
+				}),
+			),
+			reset: Type.Optional(Type.Boolean({ description: "Reset this language kernel before running." })),
+			cell_id: Type.Optional(Type.String({ description: "Detached eval cell id for peek or stop." })),
+		}),
+	) as EvalInputSchema;
 }
 export type EvalKernelResult = Extract<KernelToHostMessage, { type: "result" }>;
 export type EvalToolCallMessage = Extract<KernelToHostMessage, { type: "tool-call" }>;
@@ -52,9 +90,14 @@ export interface EvalKernelRunInput {
 	readonly timeoutMs?: number;
 }
 
+export interface KernelInterruptHandle {
+	/** Resolves once the kernel knows whether user state survived the interrupt. */
+	readonly stateRetained: Promise<boolean>;
+}
+
 export interface EvalKernel {
 	run(input: EvalKernelRunInput): Promise<EvalKernelResult>;
-	interrupt(reason?: string): Promise<void>;
+	interrupt(reason?: string): Promise<KernelInterruptHandle>;
 	deliverToolReply(message: Extract<HostToKernelMessage, { type: "tool-reply" }>): void;
 	reset(): Promise<void>;
 	close(): Promise<void>;
@@ -90,7 +133,7 @@ export type EvalCellResult = {
 	readonly code: string;
 	readonly language: EvalLanguage;
 	readonly output: string;
-	readonly status: "pending" | "running" | "complete" | "error";
+	readonly status: "pending" | "running" | "detached" | "complete" | "error" | "cancelled";
 	readonly exitCode?: number;
 	readonly durationMs?: number;
 	readonly statusEvents?: readonly EvalStatusEvent[];

package/src/codemode/runtime.ts

@@ -1,258 +0,0 @@
-import type { KernelToHostMessage } from "../bridge/protocol.ts";
-import type { AgentExecuteTool } from "../bridges/agent-bridge.ts";
-import { JavaScriptKernel } from "../kernels/js/context-manager.ts";
-import { marshalToolResult } from "../tool/image.ts";
-
-const MAX_ACTIVE_CELLS = 4;
-const MAX_PENDING_OUTPUT_CHARS = 100_000;
-const MAX_TERMINAL_ERROR_CHARS = 4_096;
-const RECURSIVE_TOOLS = new Set(["eval", "exec", "wait"]);
-
-export type CodeModeCellState = "yielded" | "result" | "terminated" | "error" | "missing";
-
-export interface CodeModeObservation {
-	readonly cellId: string;
-	readonly state: CodeModeCellState;
-	readonly output: string;
-	readonly error?: string;
-}
-
-export interface CodeModeRuntimeOptions {
-	readonly sessionId: string;
-	readonly cwd: string;
-	readonly parallelPoolWidth: number;
-	readonly executeTool: AgentExecuteTool;
-}
-
-export class CodeModeCapacityError extends Error {
-	readonly name = "CodeModeCapacityError";
-
-	constructor() {
-		super(`Code Mode supports at most ${MAX_ACTIVE_CELLS} active cells`);
-	}
-}
-
-export class CodeModeSessionRuntime {
-	readonly #options: CodeModeRuntimeOptions;
-	readonly #cells = new Map<string, CodeModeCell>();
-	#nextCell = 0;
-	#disposed = false;
-
-	constructor(options: CodeModeRuntimeOptions) {
-		this.#options = options;
-	}
-
-	async execute(code: string, yieldTimeMs: number, signal: AbortSignal | undefined): Promise<CodeModeObservation> {
-		this.#assertActive();
-		const cellId = `exec-${++this.#nextCell}`;
-		if (signal?.aborted) return { cellId, state: "terminated", output: "" };
-		if (this.#cells.size >= MAX_ACTIVE_CELLS) throw new CodeModeCapacityError();
-		const cell = new CodeModeCell(cellId, this.#options);
-		this.#cells.set(cellId, cell);
-		cell.start(code);
-		const observation = await cell.observe(yieldTimeMs, signal);
-		this.#releaseIfTerminal(observation);
-		return observation;
-	}
-
-	async wait(
-		cellId: string,
-		yieldTimeMs: number,
-		terminate: boolean,
-		signal: AbortSignal | undefined,
-	): Promise<CodeModeObservation> {
-		const cell = this.#cells.get(cellId);
-		if (cell === undefined) return { cellId, state: "missing", output: "" };
-		const observation = terminate ? await cell.terminate() : await cell.observe(yieldTimeMs, signal);
-		this.#releaseIfTerminal(observation);
-		return observation;
-	}
-
-	async dispose(): Promise<void> {
-		if (this.#disposed) return;
-		this.#disposed = true;
-		const cells = [...this.#cells.values()];
-		this.#cells.clear();
-		await Promise.all(cells.map((cell) => cell.terminate()));
-	}
-
-	#releaseIfTerminal(observation: CodeModeObservation): void {
-		if (observation.state !== "yielded") this.#cells.delete(observation.cellId);
-	}
-
-	#assertActive(): void {
-		if (this.#disposed) throw new Error("Code Mode session has been disposed");
-	}
-}
-
-class CodeModeCell {
-	readonly #id: string;
-	readonly #options: CodeModeRuntimeOptions;
-	readonly #kernel: JavaScriptKernel;
-	readonly #abort = new AbortController();
-	#output = "";
-	#outputTruncated = false;
-	#completion: Promise<void> | undefined;
-	#state: "running" | "result" | "terminated" | "error" = "running";
-	#error: string | undefined;
-
-	constructor(id: string, options: CodeModeRuntimeOptions) {
-		this.#id = id;
-		this.#options = options;
-		this.#kernel = new JavaScriptKernel({
-			sessionId: `${options.sessionId}:${id}`,
-			cwd: options.cwd,
-			parallelPoolWidth: options.parallelPoolWidth,
-			onMessage: (message) => this.#handleMessage(message),
-		});
-	}
-
-	start(code: string): void {
-		this.#completion = this.#kernel
-			.run({ cellId: this.#id, code })
-			.then((result) => {
-				if (this.#state !== "running") return;
-				if (result.ok) {
-					this.#state = "result";
-					if (result.valueRepr) this.#appendOutput(`${result.valueRepr}\n`);
-					return;
-				}
-				this.#state = "error";
-				this.#error = truncateTerminalError(result.error.message);
-			})
-			.catch((error: unknown) => {
-				if (this.#state !== "running") return;
-				this.#state = "error";
-				this.#error = truncateTerminalError(error instanceof Error ? error.message : String(error));
-			})
-			.finally(async () => {
-				if (this.#state !== "running") await this.#kernel.close();
-			});
-	}
-
-	async observe(yieldTimeMs: number, signal: AbortSignal | undefined): Promise<CodeModeObservation> {
-		if (signal?.aborted) return await this.terminate();
-		if (this.#state !== "running") return this.#observation();
-		const completion = this.#completion;
-		if (completion === undefined) throw new Error("Code Mode cell has not started");
-		const timeout = Math.max(1, Math.trunc(yieldTimeMs));
-		let timer: ReturnType<typeof setTimeout> | undefined;
-		let abortListener: (() => void) | undefined;
-		const timedOut = new Promise<"yielded">((resolve) => {
-			timer = setTimeout(() => resolve("yielded"), timeout);
-		});
-		const completed = completion.then(() => "completed" as const);
-		const aborted = new Promise<"aborted">((resolve) => {
-			if (!signal) return;
-			abortListener = () => resolve("aborted");
-			signal.addEventListener("abort", abortListener, { once: true });
-		});
-		try {
-			const outcome = await Promise.race([completed, timedOut, aborted]);
-			if (outcome === "aborted") return await this.terminate();
-			return this.#observation();
-		} finally {
-			if (timer !== undefined) clearTimeout(timer);
-			if (abortListener && signal) signal.removeEventListener("abort", abortListener);
-		}
-	}
-
-	async terminate(): Promise<CodeModeObservation> {
-		if (this.#state === "terminated") return this.#observation();
-		if (this.#state === "result" || this.#state === "error") return this.#observation();
-		this.#state = "terminated";
-		this.#abort.abort(new Error("Code Mode cell terminated"));
-		try {
-			await this.#kernel.interrupt("Code Mode cell terminated");
-		} finally {
-			await this.#kernel.close();
-		}
-		return this.#observation();
-	}
-
-	#handleMessage(message: KernelToHostMessage): void {
-		if (message.type === "text") {
-			this.#appendOutput(message.data);
-			return;
-		}
-		if (message.type === "display") {
-			this.#appendOutput(`[display ${message.mimeType}]\n`);
-			return;
-		}
-		if (message.type === "tool-call") void this.#invokeTool(message);
-	}
-
-	async #invokeTool(message: Extract<KernelToHostMessage, { type: "tool-call" }>): Promise<void> {
-		if (RECURSIVE_TOOLS.has(message.toolName)) {
-			this.#kernel.deliverToolReply({
-				type: "tool-reply",
-				callId: message.callId,
-				ok: false,
-				error: { message: `recursive Code Mode tool "${message.toolName}" is not allowed` },
-			});
-			return;
-		}
-		if (this.#options.executeTool.isToolAvailable?.(message.toolName) === false) {
-			this.#kernel.deliverToolReply({
-				type: "tool-reply",
-				callId: message.callId,
-				ok: false,
-				error: { message: `nested tool "${message.toolName}" is not active` },
-			});
-			return;
-		}
-		try {
-			const result = await this.#options.executeTool(message.toolName, message.args, { signal: this.#abort.signal });
-			this.#kernel.deliverToolReply({
-				type: "tool-reply",
-				callId: message.callId,
-				ok: true,
-				value: marshalToolResult(result),
-			});
-		} catch (error) {
-			this.#kernel.deliverToolReply({
-				type: "tool-reply",
-				callId: message.callId,
-				ok: false,
-				error: { message: error instanceof Error ? error.message : String(error) },
-			});
-		}
-	}
-
-	#observation(): CodeModeObservation {
-		let output = this.#output;
-		this.#output = "";
-		if (this.#outputTruncated) {
-			output += "\n[output truncated]\n";
-			this.#outputTruncated = false;
-		}
-		if (this.#state === "running") return { cellId: this.#id, state: "yielded", output };
-		if (this.#state === "terminated") return { cellId: this.#id, state: "terminated", output };
-		if (this.#state === "error") {
-			const error = this.#error ?? "Code Mode cell failed";
-			if (output !== "") output += output.endsWith("\n") ? error : `\n${error}`;
-			else output = error;
-			return { cellId: this.#id, state: "error", output, error };
-		}
-		return { cellId: this.#id, state: "result", output };
-	}
-
-	#appendOutput(value: string): void {
-		const remaining = MAX_PENDING_OUTPUT_CHARS - this.#output.length;
-		if (remaining <= 0) {
-			this.#outputTruncated = true;
-			return;
-		}
-		if (value.length > remaining) {
-			this.#output += value.slice(0, remaining);
-			this.#outputTruncated = true;
-			return;
-		}
-		this.#output += value;
-	}
-}
-
-function truncateTerminalError(message: string): string {
-	if (message.length <= MAX_TERMINAL_ERROR_CHARS) return message;
-	return `${message.slice(0, MAX_TERMINAL_ERROR_CHARS)}\n[error truncated]`;
-}

package/src/codemode/tools.ts

@@ -1,106 +0,0 @@
-import type { AgentToolResult, ToolDefinition } from "@code-yeongyu/senpi";
-import { type Static, Type } from "typebox";
-import type { CodeModeCellState, CodeModeObservation, CodeModeSessionRuntime } from "./runtime.ts";
-
-const DEFAULT_YIELD_TIME_MS = 10_000;
-
-const execInputSchema = Type.Object({
-	code: Type.String({ minLength: 1, description: "JavaScript program to execute in a dedicated Code Mode cell." }),
-	yield_time_ms: Type.Optional(
-		Type.Integer({ minimum: 1, maximum: 60_000, description: "Return a yielded cell after this many milliseconds." }),
-	),
-});
-
-const waitInputSchema = Type.Object({
-	cell_id: Type.String({ minLength: 1, description: "Code Mode cell id returned by exec." }),
-	yield_time_ms: Type.Optional(
-		Type.Integer({ minimum: 1, maximum: 60_000, description: "Return again after this many milliseconds." }),
-	),
-	terminate: Type.Optional(Type.Boolean({ description: "Interrupt and close the cell instead of waiting." })),
-});
-
-type ExecInput = Static<typeof execInputSchema>;
-type WaitInput = Static<typeof waitInputSchema>;
-
-export interface CodeModeToolDetails {
-	readonly cellId: string;
-	readonly state: CodeModeCellState;
-	readonly isError?: boolean;
-}
-
-export type CodeModeTool =
-	| ToolDefinition<typeof execInputSchema, CodeModeToolDetails>
-	| ToolDefinition<typeof waitInputSchema, CodeModeToolDetails>;
-
-export interface CreateCodeModeToolsOptions {
-	readonly runtime: CodeModeSessionRuntime;
-}
-
-export function createCodeModeTools(options: CreateCodeModeToolsOptions): {
-	readonly exec: ToolDefinition<typeof execInputSchema, CodeModeToolDetails>;
-	readonly wait: ToolDefinition<typeof waitInputSchema, CodeModeToolDetails>;
-} {
-	return {
-		exec: {
-			name: "exec",
-			label: "GPT Code Mode Exec",
-			description:
-				"Run JavaScript in a dedicated GPT Code Mode cell. Call active Senpi tools as `tools.<name>(args)`. " +
-				"If the cell yields, call wait with its cell_id.",
-			promptSnippet: "Execute JavaScript that composes active tools in a dedicated Code Mode cell.",
-			promptGuidelines: [
-				"Use exec for bounded JavaScript composition of active tools; use eval for persistent multi-language analysis.",
-				"Call wait only when exec reports a yielded cell, and terminate abandoned cells with wait({ cell_id, terminate: true }).",
-			],
-			parameters: execInputSchema,
-			executionMode: "sequential",
-			async execute(_toolCallId, params: ExecInput, signal) {
-				return resultFrom(
-					await options.runtime.execute(params.code, params.yield_time_ms ?? DEFAULT_YIELD_TIME_MS, signal),
-				);
-			},
-		},
-		wait: {
-			name: "wait",
-			label: "GPT Code Mode Wait",
-			description: "Observe a yielded GPT Code Mode cell or terminate it.",
-			promptSnippet: "Wait for, or terminate, a yielded GPT Code Mode cell.",
-			parameters: waitInputSchema,
-			executionMode: "sequential",
-			async execute(_toolCallId, params: WaitInput, signal) {
-				return resultFrom(
-					await options.runtime.wait(
-						params.cell_id,
-						params.yield_time_ms ?? DEFAULT_YIELD_TIME_MS,
-						params.terminate ?? false,
-						signal,
-					),
-				);
-			},
-		},
-	};
-}
-
-function resultFrom(observation: CodeModeObservation): AgentToolResult<CodeModeToolDetails> {
-	const text =
-		observation.output ||
-		(observation.state === "yielded"
-			? `Code Mode cell ${observation.cellId} is still running. Call wait with this cell_id.`
-			: observation.state === "missing"
-				? `Code Mode cell ${observation.cellId} does not exist.`
-				: observation.state === "terminated"
-					? `Code Mode cell ${observation.cellId} was terminated.`
-					: (observation.error ?? `Code Mode cell ${observation.cellId} completed.`));
-	return {
-		content: [{ type: "text", text }],
-		details: {
-			cellId: observation.cellId,
-			state: observation.state,
-			...(observation.state === "error" || observation.state === "missing" ? { isError: true } : {}),
-		},
-	};
-}
-
-export function isGptCodeModeModel(modelId: string | undefined): boolean {
-	return modelId !== undefined && /(^|[/.:])gpt[-.]/iu.test(modelId);
-}