@iowarp/clio-coder 0.3.0 → 0.3.2

package/src/engine/acp/types.ts

@@ -0,0 +1,196 @@
+import type { AgentMessage } from "../types.js";
+
+/**
+ * ACP extensibility reserves `_meta` for non-spec data. Clio namespaces its
+ * extensions so a strict client (Zed/serde) never sees an unknown top-level
+ * field on a standard response.
+ */
+export const ACP_USAGE_META_KEY = "clio-coder/usage";
+export const ACP_SESSION_META_KEY = "clio-coder/session";
+
+/**
+ * Wire bounds for one prompt turn (CONTRACT C001 §3). A client renders every
+ * frame it receives, so an unbounded one is a denial-of-service on the client
+ * and a disclosure surface on the server: `rawInput` for a `write` carries the
+ * whole file body and for `bash` the whole command line.
+ *
+ * Every cap is UTF-8 bytes, which is what the peer's read buffer and any
+ * intermediary actually spend. `String.length` counts UTF-16 code units, so
+ * measuring with it let a chunk of CJK text reach three times its stated bound
+ * and a chunk of emoji twice.
+ */
+export const ACP_MAX_STRING_BYTES = 4096;
+export const ACP_MAX_RAW_RECORD_BYTES = 32768;
+export const ACP_MAX_CHUNK_BYTES = 16384;
+
+/**
+ * Upper bound on a `toolCallId` this server puts on the wire, in UTF-8 bytes
+ * (CONTRACT C001 §3). Identity is one call per id in both directions: an engine
+ * id over this bound, missing, or already claimed by another call this turn
+ * travels under a `clio-tool-<n>` alias, and an engine id starting a second call
+ * mints a fresh alias rather than reusing the first call's wire id. A permission
+ * request binds only to an id the client already received a `tool_call` for and
+ * has not yet seen finish; nothing is minted on that path.
+ */
+export const ACP_MAX_TOOL_CALL_ID_BYTES = 128;
+
+/** ACP v1 `ToolKind` closed enum (schema 0.4.5). */
+export type AcpToolKind =
+	| "read"
+	| "edit"
+	| "delete"
+	| "move"
+	| "search"
+	| "execute"
+	| "think"
+	| "fetch"
+	| "switch_mode"
+	| "other";
+
+/** ACP v1 `ToolCallStatus` closed enum (schema 0.4.5). */
+export type AcpToolCallStatus = "pending" | "in_progress" | "completed" | "failed";
+
+export interface AcpJsonRpcRequest {
+	jsonrpc: "2.0";
+	id: string | number;
+	method: string;
+	params?: unknown;
+}
+
+export interface AcpJsonRpcNotification {
+	jsonrpc: "2.0";
+	method: string;
+	params?: unknown;
+}
+
+export interface AcpJsonRpcSuccess {
+	jsonrpc: "2.0";
+	id: string | number;
+	result: unknown;
+}
+
+export interface AcpJsonRpcFailure {
+	jsonrpc: "2.0";
+	id: string | number | null;
+	error: {
+		code: number;
+		message: string;
+		data?: unknown;
+	};
+}
+
+export type AcpJsonRpcMessage = AcpJsonRpcRequest | AcpJsonRpcNotification | AcpJsonRpcSuccess | AcpJsonRpcFailure;
+
+export interface AcpImplementationInfo {
+	name?: string;
+	title?: string;
+	version?: string;
+}
+
+export interface AcpInitializeResponse {
+	protocolVersion?: number;
+	agentCapabilities?: Record<string, unknown>;
+	agentInfo?: AcpImplementationInfo;
+	authMethods?: unknown[];
+}
+
+export interface AcpSessionInfo {
+	sessionId: string;
+	title?: string;
+	cwd?: string;
+	updatedAt?: string;
+	messageCount?: number;
+}
+
+export interface AcpContentText {
+	type: "text";
+	text: string;
+}
+
+export interface AcpContentResourceLink {
+	type: "resource_link";
+	uri: string;
+	name?: string;
+	mimeType?: string;
+}
+
+export type AcpContentBlock = AcpContentText | AcpContentResourceLink | Record<string, unknown>;
+
+/** ACP v1 `ToolCallLocation` (schema 0.4.5). */
+export interface AcpToolCallLocation {
+	/** The file path being accessed or modified. */
+	path: string;
+	/** Optional zero-based line number within the file. */
+	line?: number | null;
+	/** ACP extension point. */
+	_meta?: unknown;
+}
+
+export interface AcpToolCallUpdate {
+	sessionUpdate?: "tool_call" | "tool_call_update";
+	toolCallId?: string;
+	title?: string;
+	kind?: string;
+	status?: "pending" | "in_progress" | "completed" | "failed" | "cancelled" | string;
+	content?: unknown;
+	locations?: AcpToolCallLocation[] | null;
+	rawInput?: Record<string, unknown>;
+	rawOutput?: Record<string, unknown>;
+}
+
+export interface AcpSessionUpdateParams {
+	sessionId?: string;
+	update?: Record<string, unknown>;
+}
+
+export type AcpPermissionOptionKind = "allow_once" | "allow_always" | "reject_once" | "reject_always" | string;
+
+export interface AcpPermissionOption {
+	optionId: string;
+	name?: string;
+	kind: AcpPermissionOptionKind;
+}
+
+export interface AcpRequestPermissionParams {
+	sessionId?: string;
+	toolCall?: AcpToolCallUpdate;
+	options?: AcpPermissionOption[];
+}
+
+export type AcpPermissionOutcome = { outcome: "selected"; optionId: string } | { outcome: "cancelled" };
+
+export interface AcpRequestPermissionResponse {
+	outcome: AcpPermissionOutcome;
+}
+
+export interface AcpPromptResponse {
+	stopReason?: string;
+	usage?: unknown;
+	tokenUsage?: unknown;
+	_meta?: unknown;
+}
+
+export interface AcpDelegationUsage {
+	inputTokens: number;
+	outputTokens: number;
+	cacheReadTokens: number;
+	cacheWriteTokens: number;
+	reasoningTokens: number;
+}
+
+export interface AcpDelegationResult {
+	messages: AgentMessage[];
+	exitCode: number;
+	stopReason: string;
+	/** True when the turn request hit its configured timeout. */
+	timedOut?: boolean;
+	failureMessage?: string;
+	usage: AcpDelegationUsage;
+	delegation: {
+		acpSessionId: string | null;
+		initialize: AcpInitializeResponse | null;
+		toolCallsRequested: number;
+		toolCallsApproved: number;
+		toolCallsDenied: number;
+	};
+}

package/src/engine/agent.ts

@@ -0,0 +1,29 @@
+/**
+ * Thin wrapper over Clio's engine Agent class.
+ *
+ * The engine Agent owns its own state (exposed via `agent.state`). There is no
+ * separate state factory. AgentOptions drives the construction; the state is derived
+ * from options.initialState on instantiation.
+ *
+ * pi-agent-core 0.84 requires an explicit stream function on every agent.
+ * Clio's default is the compat `streamSimple` dispatcher (the same function the
+ * pre-0.81 engine used implicitly); callers may override it for tests.
+ */
+
+import { Agent, type AgentOptions, type StreamFn } from "@earendil-works/pi-agent-core";
+import { engineStreamSimple } from "./api-registry.js";
+
+export type EngineAgentOptions = Omit<AgentOptions, "streamFn"> & { streamFn?: StreamFn };
+
+export interface EngineAgentHandle {
+	agent: Agent;
+	state(): Agent["state"];
+}
+
+export function createEngineAgent(options: EngineAgentOptions = {}): EngineAgentHandle {
+	const agent = new Agent({ streamFn: engineStreamSimple, ...options });
+	return {
+		agent,
+		state: () => agent.state,
+	};
+}

package/src/engine/ai.ts

@@ -0,0 +1,207 @@
+/**
+ * Thin wrapper over @earendil-works/pi-ai. Domains consume this module, not
+ * pi-ai directly. The model-lookup side-registry that used to live here is
+ * gone; runtime descriptors under `src/domains/providers/runtimes/` own
+ * model synthesis via `RuntimeDescriptor.synthesizeModel()`.
+ *
+ * pi-ai's provider registry is process-global. Calling
+ * `registerBuiltInApiProviders()` multiple times is safe; we still gate on a
+ * module-local flag to keep startup hot paths predictable.
+ */
+
+import {
+	type Api,
+	type AssistantMessage,
+	fauxAssistantMessage,
+	type KnownProvider,
+	type Model,
+	type ModelThinkingLevel,
+	calculateCost as piCalculateCost,
+	cleanupSessionResources as piCleanupSessionResources,
+	getSupportedThinkingLevels as piGetSupportedThinkingLevels,
+	isContextOverflow as piIsContextOverflow,
+	isRetryableAssistantError as piIsRetryableAssistantError,
+	validateToolArguments as piValidateToolArguments,
+	StringEnum,
+	type Tool,
+	type ToolCall,
+	type Usage,
+} from "@earendil-works/pi-ai";
+import {
+	completeEngineSimple,
+	engineStream,
+	registerEngineBuiltins,
+	registerEngineFauxProvider,
+} from "./api-registry.js";
+import { engineModelProviders, engineModelsFor, getEngineModel } from "./models.js";
+import type { EngineModel } from "./types.js";
+
+export { StringEnum };
+
+export const stream = engineStream;
+
+export interface EngineTextCompletionInput {
+	model: EngineModel;
+	systemPrompt: string;
+	userPrompt: string;
+	maxTokens: number;
+	thinkingLevel: ModelThinkingLevel;
+	signal: AbortSignal;
+	timeoutMs: number;
+	apiKey?: string;
+}
+
+export interface EngineTextCompletionResult {
+	text: string;
+	inputTokens: number;
+	outputTokens: number;
+}
+
+/** Run one tool-free completion while keeping pi message types at the engine boundary. */
+export async function completeEngineText(input: EngineTextCompletionInput): Promise<EngineTextCompletionResult> {
+	const response = await completeEngineSimple(
+		input.model,
+		{
+			systemPrompt: input.systemPrompt,
+			messages: [{ role: "user", content: input.userPrompt, timestamp: Date.now() }],
+		},
+		{
+			maxTokens: input.maxTokens,
+			signal: input.signal,
+			timeoutMs: input.timeoutMs,
+			...(input.thinkingLevel === "off" ? {} : { reasoning: input.thinkingLevel }),
+			...(input.apiKey === undefined ? {} : { apiKey: input.apiKey }),
+		},
+	);
+	if (response.stopReason === "error" || response.stopReason === "aborted") {
+		throw new Error(response.errorMessage ?? `model completion ${response.stopReason}`);
+	}
+	return {
+		text: response.content
+			.filter((block): block is Extract<(typeof response.content)[number], { type: "text" }> => block.type === "text")
+			.map((block) => block.text)
+			.join(""),
+		inputTokens: response.usage.input,
+		outputTokens: response.usage.output,
+	};
+}
+
+export interface EngineAi {
+	listProviders(): KnownProvider[];
+	listModels<TProvider extends KnownProvider>(provider: TProvider): EngineModel[];
+	getModel<TProvider extends KnownProvider>(provider: TProvider, modelId: string): EngineModel | undefined;
+}
+
+let registered = false;
+
+export function ensurePiAiRegistered(): void {
+	if (registered) return;
+	registerEngineBuiltins();
+	registered = true;
+}
+
+export function createEngineAi(): EngineAi {
+	ensurePiAiRegistered();
+	return {
+		listProviders: () => engineModelProviders(),
+		listModels: (provider) => engineModelsFor(provider) as EngineModel[],
+		getModel: (provider, modelId) => {
+			try {
+				return getEngineModel(provider, modelId) as EngineModel | undefined;
+			} catch {
+				return undefined;
+			}
+		},
+	};
+}
+
+function emptyUsage(): Usage {
+	return {
+		input: 0,
+		output: 0,
+		cacheRead: 0,
+		cacheWrite: 0,
+		totalTokens: 0,
+		cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+	};
+}
+
+export function getEngineSupportedThinkingLevels<TApi extends Api>(model: Model<TApi>): ModelThinkingLevel[] {
+	return piGetSupportedThinkingLevels(model);
+}
+
+export function cleanupEngineSessionResources(sessionId?: string): void {
+	piCleanupSessionResources(sessionId);
+}
+
+export function isEngineContextOverflow(errorMessage: string, contextWindow?: number): boolean {
+	const message: AssistantMessage = {
+		role: "assistant",
+		content: [],
+		api: "clio",
+		provider: "clio",
+		model: "unknown",
+		usage: emptyUsage(),
+		stopReason: "error",
+		errorMessage,
+		timestamp: Date.now(),
+	};
+	return piIsContextOverflow(message, contextWindow);
+}
+
+/** Classify one provider error through pi-ai without leaking its message shape across the engine boundary. */
+export function isEngineRetryableAssistantError(errorMessage: string): boolean {
+	const message: AssistantMessage = {
+		role: "assistant",
+		content: [],
+		api: "clio",
+		provider: "clio",
+		model: "unknown",
+		usage: emptyUsage(),
+		stopReason: "error",
+		errorMessage,
+		timestamp: Date.now(),
+	};
+	return piIsRetryableAssistantError(message);
+}
+
+export function validateEngineToolArguments(tool: Tool, toolCall: ToolCall): unknown {
+	return piValidateToolArguments(tool, toolCall);
+}
+
+export function calculateEngineCost<TApi extends Api>(model: Model<TApi>, usage: Usage): Usage["cost"] {
+	return piCalculateCost(model, usage);
+}
+
+/**
+ * When `CLIO_CODER_WORKER_FAUX=1`, register the pi-ai faux provider and queue a
+ * single deterministic assistant response. Used by the worker-entry diag so
+ * the worker subprocess can run end-to-end without provider credentials.
+ *
+ * Env vars (all optional except the gate):
+ *   CLIO_CODER_WORKER_FAUX               must equal "1" to arm registration
+ *   CLIO_CODER_WORKER_FAUX_MODEL         model id registered under the faux provider (default "faux-model")
+ *   CLIO_CODER_WORKER_FAUX_TEXT          assistant response text (default "ok")
+ *   CLIO_CODER_WORKER_FAUX_STOP_REASON   assistant stopReason (default "stop")
+ *   CLIO_CODER_WORKER_FAUX_ERROR_MESSAGE optional assistant errorMessage
+ */
+export function registerFauxFromEnv(): EngineModel | null {
+	if (process.env.CLIO_CODER_WORKER_FAUX !== "1") return null;
+	const modelId = process.env.CLIO_CODER_WORKER_FAUX_MODEL ?? "faux-model";
+	const text = process.env.CLIO_CODER_WORKER_FAUX_TEXT ?? "ok";
+	const stopReason = (process.env.CLIO_CODER_WORKER_FAUX_STOP_REASON ?? "stop") as AssistantMessage["stopReason"];
+	const errorMessage = process.env.CLIO_CODER_WORKER_FAUX_ERROR_MESSAGE;
+	const reg = registerEngineFauxProvider({
+		provider: "faux",
+		models: [{ id: modelId }],
+	});
+	const response = { stopReason } as {
+		stopReason: AssistantMessage["stopReason"];
+		errorMessage?: string;
+	};
+	if (errorMessage && errorMessage.length > 0) {
+		response.errorMessage = errorMessage;
+	}
+	reg.setResponses([fauxAssistantMessage(text, response)]);
+	return reg.getModel(modelId) as EngineModel;
+}

package/src/engine/alcf-oauth.ts

@@ -0,0 +1,205 @@
+/**
+ * ALCF / Argonne inference-gateway authentication via Globus Auth.
+ *
+ * The ALCF inference gateway exposes OpenAI-compatible model endpoints behind
+ * Globus. This provider implements the native-app PKCE paste-the-code flow so
+ * it works from local terminals and SSH login nodes without a localhost
+ * callback.
+ */
+
+import type { OAuthCredentials, OAuthLoginCallbacks } from "@earendil-works/pi-ai";
+import type { EngineOAuthProvider } from "./oauth.js";
+
+export const AUTH_CLIENT_ID = "58fdd3bc-e1c3-4ce5-80ea-8d6b87cfb944";
+export const GATEWAY_CLIENT_ID = "681c10cc-f684-4540-bcd7-0b4df3bc26ef";
+export const GATEWAY_SCOPE = `https://auth.globus.org/scopes/${GATEWAY_CLIENT_ID}/action_all`;
+export const ALLOWED_DOMAINS = "anl.gov,alcf.anl.gov";
+
+const AUTHORIZE_URL = "https://auth.globus.org/v2/oauth2/authorize";
+const TOKEN_URL = "https://auth.globus.org/v2/oauth2/token";
+const REDIRECT_URI = "https://auth.globus.org/v2/web/auth-code";
+const EXPIRY_SKEW_MS = 5 * 60 * 1000;
+
+function base64Url(bytes: Uint8Array): string {
+	let binary = "";
+	for (const byte of bytes) binary += String.fromCharCode(byte);
+	return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
+}
+
+async function generatePkce(): Promise<{ verifier: string; challenge: string }> {
+	const verifierBytes = new Uint8Array(32);
+	crypto.getRandomValues(verifierBytes);
+	const verifier = base64Url(verifierBytes);
+	const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier));
+	return { verifier, challenge: base64Url(new Uint8Array(digest)) };
+}
+
+function randomState(): string {
+	const bytes = new Uint8Array(16);
+	crypto.getRandomValues(bytes);
+	return base64Url(bytes);
+}
+
+export function buildAuthorizeUrl(params: { challenge: string; state: string }): string {
+	const query = new URLSearchParams({
+		client_id: AUTH_CLIENT_ID,
+		response_type: "code",
+		redirect_uri: REDIRECT_URI,
+		scope: GATEWAY_SCOPE,
+		state: params.state,
+		code_challenge: params.challenge,
+		code_challenge_method: "S256",
+		access_type: "offline",
+		session_required_single_domain: ALLOWED_DOMAINS,
+	});
+	return `${AUTHORIZE_URL}?${query.toString()}`;
+}
+
+export function parseAuthorizationInput(input: string): string {
+	const value = input.trim();
+	if (!value) return "";
+	try {
+		const url = new URL(value);
+		const code = url.searchParams.get("code");
+		if (code) return code;
+	} catch {
+		// Not a URL; fall through to fragment/bare-code handling.
+	}
+	if (value.includes("code=")) {
+		const params = new URLSearchParams(value.includes("?") ? value.slice(value.indexOf("?") + 1) : value);
+		const code = params.get("code");
+		if (code) return code;
+	}
+	return value;
+}
+
+interface GlobusTokenGrant {
+	access_token?: unknown;
+	refresh_token?: unknown;
+	expires_in?: unknown;
+	resource_server?: unknown;
+	scope?: unknown;
+}
+
+interface GlobusTokenResponse extends GlobusTokenGrant {
+	other_tokens?: GlobusTokenGrant[];
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}
+
+export function selectGatewayGrant(payload: GlobusTokenResponse): GlobusTokenGrant {
+	const grants: GlobusTokenGrant[] = [payload, ...(Array.isArray(payload.other_tokens) ? payload.other_tokens : [])];
+	const byResourceServer = grants.find((grant) => grant.resource_server === GATEWAY_CLIENT_ID);
+	if (byResourceServer) return byResourceServer;
+	const byScope = grants.find(
+		(grant) => typeof grant.scope === "string" && (grant.scope.includes("action_all") || grant.scope === GATEWAY_SCOPE),
+	);
+	if (byScope) return byScope;
+	if (grants.length === 1 && typeof payload.access_token === "string") return payload;
+	throw new Error(
+		`Globus token response did not include a grant for the ALCF gateway (resource_server=${GATEWAY_CLIENT_ID}).`,
+	);
+}
+
+export function grantToCredentials(grant: GlobusTokenGrant, previousRefresh?: string): OAuthCredentials {
+	const access = grant.access_token;
+	if (typeof access !== "string" || access.length === 0) {
+		throw new Error("Globus token response is missing an access token for the ALCF gateway.");
+	}
+	const refresh =
+		typeof grant.refresh_token === "string" && grant.refresh_token.length > 0 ? grant.refresh_token : previousRefresh;
+	if (typeof refresh !== "string" || refresh.length === 0) {
+		throw new Error("Globus token response is missing a refresh token; cannot persist a renewable session.");
+	}
+	const expiresInSeconds = typeof grant.expires_in === "number" && grant.expires_in > 0 ? grant.expires_in : 0;
+	return {
+		access,
+		refresh,
+		expires: Date.now() + expiresInSeconds * 1000 - EXPIRY_SKEW_MS,
+	};
+}
+
+async function postForm(body: Record<string, string>, signal?: AbortSignal): Promise<GlobusTokenResponse> {
+	const requestSignal = signal ? AbortSignal.any([signal, AbortSignal.timeout(30_000)]) : AbortSignal.timeout(30_000);
+	const response = await fetch(TOKEN_URL, {
+		method: "POST",
+		headers: {
+			"Content-Type": "application/x-www-form-urlencoded",
+			Accept: "application/json",
+		},
+		body: new URLSearchParams(body).toString(),
+		signal: requestSignal,
+	});
+	const text = await response.text();
+	if (!response.ok) {
+		throw new Error(`Globus token endpoint failed (HTTP ${response.status}): ${text.slice(0, 300)}`);
+	}
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(text);
+	} catch (err) {
+		throw new Error(`Globus token endpoint returned invalid JSON: ${err instanceof Error ? err.message : String(err)}`);
+	}
+	if (!isRecord(parsed)) throw new Error("Globus token endpoint returned a non-object response.");
+	return parsed as GlobusTokenResponse;
+}
+
+async function exchangeCode(code: string, verifier: string, signal?: AbortSignal): Promise<OAuthCredentials> {
+	const payload = await postForm(
+		{
+			grant_type: "authorization_code",
+			client_id: AUTH_CLIENT_ID,
+			code,
+			code_verifier: verifier,
+			redirect_uri: REDIRECT_URI,
+		},
+		signal,
+	);
+	return grantToCredentials(selectGatewayGrant(payload));
+}
+
+async function refreshGatewayToken(refreshToken: string, signal: AbortSignal): Promise<OAuthCredentials> {
+	const payload = await postForm(
+		{
+			grant_type: "refresh_token",
+			client_id: AUTH_CLIENT_ID,
+			refresh_token: refreshToken,
+		},
+		signal,
+	);
+	return grantToCredentials(selectGatewayGrant(payload), refreshToken);
+}
+
+export async function loginAlcf(callbacks: OAuthLoginCallbacks): Promise<OAuthCredentials> {
+	const { verifier, challenge } = await generatePkce();
+	const url = buildAuthorizeUrl({ challenge, state: randomState() });
+	callbacks.onAuth({
+		url,
+		instructions:
+			"Log in with your ALCF / anl.gov identity. Globus will show an authorization code; copy it and paste it here.",
+	});
+	const pasted = callbacks.onManualCodeInput
+		? await callbacks.onManualCodeInput()
+		: await callbacks.onPrompt({ message: "Paste the authorization code from Globus", placeholder: "code" });
+	const code = parseAuthorizationInput(pasted);
+	if (!code) throw new Error("No authorization code was provided.");
+	callbacks.onProgress?.("Exchanging authorization code for an ALCF access token...");
+	return exchangeCode(code, verifier, callbacks.signal);
+}
+
+export const alcfOAuthProvider: EngineOAuthProvider = {
+	id: "alcf",
+	name: "ALCF Inference (Globus)",
+	usesCallbackServer: false,
+	login(callbacks) {
+		return loginAlcf(callbacks);
+	},
+	refreshToken(credentials, signal) {
+		return refreshGatewayToken(credentials.refresh, signal);
+	},
+	async getApiKey(credentials) {
+		return credentials.access;
+	},
+};