@code-yeongyu/senpi-codemode 2026.7.25-2

package/src/bridges/output-bridge.ts

@@ -0,0 +1,96 @@
+import type { AgentToolResult } from "@code-yeongyu/senpi";
+import { type Static, Type } from "typebox";
+import { Check, Errors } from "typebox/value";
+import type { ExecuteTool } from "../tool/types.ts";
+
+const outputArgsSchema = Type.Object(
+	{
+		ids: Type.Array(Type.String({ minLength: 1 }), { minItems: 1 }),
+		format: Type.Optional(Type.Union([Type.Literal("raw"), Type.Literal("tail")])),
+		offset: Type.Optional(Type.Integer({ minimum: 1 })),
+		limit: Type.Optional(Type.Integer({ minimum: 1 })),
+	},
+	{ additionalProperties: false },
+);
+
+type OutputArgs = Static<typeof outputArgsSchema>;
+
+export type OutputExecuteTool = ExecuteTool & {
+	readonly isToolAvailable?: (name: string) => boolean;
+};
+
+export type MarshalledToolResult = {
+	readonly text: string;
+};
+
+export interface RunEvalOutputOptions {
+	readonly taskOutputToolName: string;
+	readonly executeTool: OutputExecuteTool;
+	readonly signal?: AbortSignal;
+	readonly marshalToolResult: (result: AgentToolResult<unknown>) => MarshalledToolResult;
+}
+
+class OutputArgumentsError extends Error {
+	readonly name = "OutputArgumentsError";
+
+	constructor(summary: string) {
+		super(`output() received invalid arguments: ${summary}`);
+	}
+}
+
+class OutputUnavailableError extends Error {
+	readonly name = "OutputUnavailableError";
+
+	constructor(toolName: string) {
+		super(`output() unavailable: no "${toolName}" tool is registered in this session`);
+	}
+}
+
+export async function runEvalOutput(args: unknown, options: RunEvalOutputOptions): Promise<string | readonly string[]> {
+	const parsed = parseOutputArgs(args);
+	if (options.executeTool.isToolAvailable?.(options.taskOutputToolName) === false) {
+		throw new OutputUnavailableError(options.taskOutputToolName);
+	}
+
+	const mode = parsed.format === "tail" ? "tail" : "full";
+	const transcripts = await Promise.all(
+		parsed.ids.map(async (id) => {
+			let result: AgentToolResult<unknown>;
+			try {
+				result = await options.executeTool(
+					options.taskOutputToolName,
+					{
+						...(id.startsWith("st_") ? { task_id: id } : { name: id }),
+						mode,
+						block: true,
+					},
+					options.signal === undefined ? undefined : { signal: options.signal },
+				);
+			} catch (error) {
+				if (isUnavailableToolError(error)) throw new OutputUnavailableError(options.taskOutputToolName);
+				throw error;
+			}
+
+			// ADAPTATION: task_output owns transcripts, so no AgentOutputManager cache or
+			// oh-my-pi query/json/stripped formats exist on this bridge.
+			const transcript = options.marshalToolResult(result).text;
+			const lines = transcript.split(/\r?\n/u);
+			const start = (parsed.offset ?? 1) - 1;
+			return lines.slice(start, parsed.limit === undefined ? undefined : start + parsed.limit).join("\n");
+		}),
+	);
+	return transcripts.length === 1 ? transcripts[0] : transcripts;
+}
+
+function parseOutputArgs(value: unknown): OutputArgs {
+	if (Check(outputArgsSchema, value)) return value;
+	const summary = Errors(outputArgsSchema, value)
+		.map((error) => `${error.instancePath || "/"} ${error.message}`)
+		.join("; ");
+	throw new OutputArgumentsError(summary || "invalid value");
+}
+
+function isUnavailableToolError(error: unknown): boolean {
+	if (typeof error !== "object" || error === null || Array.isArray(error)) return false;
+	return "code" in error && (error.code === "unknown_tool" || error.code === "inactive_tool");
+}

package/src/bridges/schema-injection.ts

@@ -0,0 +1,3 @@
+export function injectSchemaInstruction(prompt: string, schema: unknown): string {
+	return `${prompt}\n\nRespond ONLY with JSON matching this JSON-Schema:\n${JSON.stringify(schema)}`;
+}

package/src/codemode/runtime.ts

@@ -0,0 +1,258 @@
+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

@@ -0,0 +1,106 @@
+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);
+}

package/src/completion/handler.ts

@@ -0,0 +1,192 @@
+import type { ExtensionContext } from "@code-yeongyu/senpi";
+import type { Api, AssistantMessage, Context, Model, SimpleStreamOptions } from "@earendil-works/pi-ai/compat";
+import { completeSimple } from "@earendil-works/pi-ai/compat";
+import { injectSchemaInstruction } from "../bridges/schema-injection.ts";
+
+export interface CompletionRequest {
+	readonly prompt: string;
+	readonly model?: string;
+	readonly system?: string;
+	readonly schema?: unknown;
+	readonly opts?: unknown;
+}
+
+export type CompletionResult =
+	| { readonly text: string; readonly details: CompletionDetails }
+	| { readonly value: unknown; readonly details: CompletionDetails };
+
+export type CompleteSimple = (
+	model: Model<Api>,
+	context: Context,
+	options?: SimpleStreamOptions,
+) => Promise<AssistantMessage>;
+
+type CompletionDetails = {
+	readonly model: string;
+	readonly structured: boolean;
+};
+
+type CompletionTier = "smol" | "default" | "slow";
+
+class CompletionUnknownTierError extends Error {
+	readonly name = "CompletionUnknownTierError";
+
+	constructor(tier: string) {
+		super(`completion() could not resolve the "${tier}" model tier; expected "smol", "default", or "slow".`);
+	}
+}
+
+class CompletionTierUnavailableError extends Error {
+	readonly name = "CompletionTierUnavailableError";
+
+	constructor(tier: Exclude<CompletionTier, "default">) {
+		super(`completion() could not resolve the "${tier}" model tier: no configured models are available.`);
+	}
+}
+
+export function createCompletionHandler(
+	complete: CompleteSimple = completeSimple,
+): (ctx: ExtensionContext) => (request: CompletionRequest) => Promise<CompletionResult> {
+	return (ctx) => async (request) => runCompletion(ctx, normalizeRequest(request), complete);
+}
+
+async function runCompletion(
+	ctx: ExtensionContext,
+	request: CompletionRequest,
+	complete: CompleteSimple,
+): Promise<CompletionResult> {
+	const tier = resolveCompletionTier(request.model);
+	const model = resolveRequestedModel(ctx, tier);
+	if (!model) throw unavailableModelError(tier);
+	const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
+	if (!auth.ok) throw noModelCredentialsError(auth.error);
+	if (!auth.apiKey) throw noModelCredentialsError();
+	const requestModel = auth.upstreamModelId ? { ...model, id: auth.upstreamModelId } : model;
+	const structured = request.schema !== undefined;
+	const prompt = structured ? injectSchemaInstruction(request.prompt, request.schema) : request.prompt;
+	const message = await complete(
+		requestModel,
+		{
+			systemPrompt: request.system ?? "You are a helpful assistant.",
+			messages: [{ role: "user", content: [{ type: "text", text: prompt }], timestamp: Date.now() }],
+		},
+		{
+			apiKey: auth.apiKey,
+			headers: auth.headers,
+			env: auth.env,
+			extraBody: auth.extraBody,
+			signal: ctx.signal,
+		},
+	);
+	return formatCompletion(message, model, structured);
+}
+
+function normalizeRequest(request: CompletionRequest): CompletionRequest {
+	if (request.opts === undefined || !isRecord(request.opts)) return request;
+	return {
+		...request,
+		model: typeof request.opts.model === "string" ? request.opts.model : request.model,
+		system: typeof request.opts.system === "string" ? request.opts.system : request.system,
+		schema: "schema" in request.opts ? request.opts.schema : request.schema,
+	};
+}
+
+function resolveCompletionTier(requested: string | undefined): CompletionTier {
+	switch (requested) {
+		case undefined:
+		case "default":
+			return "default";
+		case "smol":
+			return "smol";
+		case "slow":
+			return "slow";
+		default:
+			throw new CompletionUnknownTierError(requested);
+	}
+}
+
+function resolveRequestedModel(ctx: ExtensionContext, tier: CompletionTier): Model<Api> | undefined {
+	switch (tier) {
+		case "default":
+			return ctx.model;
+		case "smol":
+			return lowestCostModel(ctx.modelRegistry.getAvailable());
+		case "slow":
+			return highestCostModel(ctx.modelRegistry.getAvailable());
+		default:
+			return assertNever(tier);
+	}
+}
+
+function unavailableModelError(tier: CompletionTier): Error {
+	switch (tier) {
+		case "default":
+			return noModelCredentialsError();
+		case "smol":
+		case "slow":
+			return new CompletionTierUnavailableError(tier);
+		default:
+			return assertNever(tier);
+	}
+}
+
+function lowestCostModel(models: readonly Model<Api>[]): Model<Api> | undefined {
+	let selected: Model<Api> | undefined;
+	for (const model of models) {
+		if (selected === undefined || promptAndResponseCost(model) < promptAndResponseCost(selected)) selected = model;
+	}
+	return selected;
+}
+
+function highestCostModel(models: readonly Model<Api>[]): Model<Api> | undefined {
+	let selected: Model<Api> | undefined;
+	for (const model of models) {
+		if (selected === undefined || promptAndResponseCost(model) > promptAndResponseCost(selected)) selected = model;
+	}
+	return selected;
+}
+
+function promptAndResponseCost(model: Model<Api>): number {
+	return model.cost.input + model.cost.output;
+}
+
+function formatCompletion(message: AssistantMessage, model: Model<Api>, structured: boolean): CompletionResult {
+	if (message.stopReason === "error") throw new Error(message.errorMessage ?? "completion() request failed.");
+	if (message.stopReason === "aborted") throw new Error("completion() request aborted.");
+	const text = extractText(message);
+	const details = { model: formatModel(model), structured };
+	if (!structured) return { text, details };
+	try {
+		const value: unknown = JSON.parse(text);
+		return { value, details };
+	} catch (error) {
+		if (error instanceof SyntaxError) return { value: { parseError: error.message }, details };
+		throw error;
+	}
+}
+
+function extractText(message: AssistantMessage): string {
+	const parts: string[] = [];
+	for (const part of message.content) {
+		if (part.type === "text") parts.push(part.text);
+	}
+	const text = parts.join("\n");
+	if (text.length === 0) throw new Error("completion() returned no text output.");
+	return text;
+}
+
+function noModelCredentialsError(reason?: string): Error {
+	return new Error(`completion() has no model/credentials${reason ? `: ${reason}` : ""}`);
+}
+
+function formatModel(model: Model<Api>): string {
+	return `${model.provider}/${model.id}`;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}
+
+function assertNever(value: never): never {
+	throw new CompletionUnknownTierError(String(value));
+}