@oh-my-pi/pi-coding-agent 17.0.9 → 17.1.1

package/src/session/acp-permission-gate.ts

@@ -0,0 +1,165 @@
+import { Patch } from "@oh-my-pi/hashline";
+import { isRecord, stringProperty } from "@oh-my-pi/pi-utils";
+import { expandApplyPatchToEntries } from "../edit";
+import { resolveToCwd } from "../tools/path-utils";
+import type { ClientBridgePermissionOption } from "./client-bridge";
+
+/** Tools that require user permission before execution when an ACP client is connected. */
+export const PERMISSION_REQUIRED_TOOLS: Record<string, true> = {
+	bash: true,
+	edit: true,
+	delete: true,
+	move: true,
+};
+
+/** Permission options presented to the client on each gated tool call. */
+export const PERMISSION_OPTIONS: ClientBridgePermissionOption[] = [
+	{ optionId: "allow_once", name: "Allow once", kind: "allow_once" },
+	{ optionId: "allow_always", name: "Always allow", kind: "allow_always" },
+	{ optionId: "reject_once", name: "Reject", kind: "reject_once" },
+	{ optionId: "reject_always", name: "Always reject", kind: "reject_always" },
+];
+
+/** Permission options indexed by their wire identifiers; unknown IDs miss and fail closed. */
+export const PERMISSION_OPTIONS_BY_ID = new Map(PERMISSION_OPTIONS.map(option => [option.optionId, option]));
+
+function getEditDestructiveIntent(args: unknown): { kind: "delete" | "move"; paths: string[] } | undefined {
+	if (!isRecord(args)) return undefined;
+
+	const edits = Array.isArray(args.edits) ? args.edits : undefined;
+	if (edits) {
+		const filePath = stringProperty(args, "path");
+		if (filePath) {
+			for (const edit of edits) {
+				if (!isRecord(edit)) continue;
+				if (stringProperty(edit, "op") === "delete") return { kind: "delete", paths: [filePath] };
+			}
+		}
+		for (const edit of edits) {
+			if (!isRecord(edit)) continue;
+			const op = stringProperty(edit, "op");
+			const rename = stringProperty(edit, "rename");
+			if (op !== "create" && rename) return { kind: "move", paths: filePath ? [filePath, rename] : [rename] };
+		}
+	}
+
+	const input = stringProperty(args, "input");
+	if (input) {
+		try {
+			const patch = Patch.parse(input);
+			for (const section of patch.sections) {
+				if (section.fileOp?.kind === "rem") return { kind: "delete", paths: [section.path] };
+				if (section.fileOp?.kind === "move") return { kind: "move", paths: [section.path, section.fileOp.dest] };
+			}
+		} catch {
+			// Not a hashline patch — fall through to apply_patch parsing.
+		}
+		try {
+			const entries = expandApplyPatchToEntries({ input });
+			const deleteEntry = entries.find(entry => entry.op === "delete");
+			if (deleteEntry) return { kind: "delete", paths: [deleteEntry.path] };
+			const moveEntry = entries.find(entry => entry.rename);
+			if (moveEntry?.rename) return { kind: "move", paths: [moveEntry.path, moveEntry.rename] };
+		} catch {
+			// If the edit input is not an apply-patch envelope, it is not a delete/move operation.
+		}
+	}
+
+	return undefined;
+}
+
+/** Describes the permission prompt required for a destructive tool call. */
+export function getPermissionIntent(
+	toolName: string,
+	args: unknown,
+): { toolName: string; title: string; paths?: string[]; cacheKey: string } | undefined {
+	const input = isRecord(args) ? args : {};
+	if (toolName === "bash") {
+		const command = stringProperty(input, "command")?.slice(0, 80);
+		return { toolName, title: command || toolName, cacheKey: toolName };
+	}
+	if (toolName === "delete") {
+		const filePath = stringProperty(input, "path");
+		return {
+			toolName,
+			title: filePath ? `Delete ${filePath}` : toolName,
+			paths: filePath ? [filePath] : undefined,
+			cacheKey: toolName,
+		};
+	}
+	if (toolName === "move") {
+		const from = stringProperty(input, "oldPath") ?? stringProperty(input, "path") ?? stringProperty(input, "from");
+		const to =
+			stringProperty(input, "newPath") ?? stringProperty(input, "to") ?? stringProperty(input, "destination");
+		if (from && to) return { toolName, title: `Move ${from} to ${to}`, paths: [from, to], cacheKey: toolName };
+		return {
+			toolName,
+			title: from ? `Move ${from}` : toolName,
+			paths: from ? [from] : undefined,
+			cacheKey: toolName,
+		};
+	}
+	if (toolName === "edit") {
+		const intent = getEditDestructiveIntent(args);
+		if (!intent) return undefined;
+		if (intent.kind === "delete") {
+			return {
+				toolName,
+				title: `Delete ${intent.paths[0] ?? "edit target"}`,
+				paths: intent.paths,
+				cacheKey: "edit:delete",
+			};
+		}
+		const from = intent.paths[0];
+		const to = intent.paths[1];
+		return {
+			toolName,
+			title: from && to ? `Move ${from} to ${to}` : `Move ${from ?? to ?? "edit target"}`,
+			paths: intent.paths,
+			cacheKey: "edit:move",
+		};
+	}
+	return undefined;
+}
+
+/** Converts tool path arguments into absolute ACP editor locations. */
+export function extractPermissionLocations(
+	args: unknown,
+	cwd: string,
+	explicitPaths?: string[],
+): { path: string; line?: number }[] {
+	if (!isRecord(args)) return [];
+	const out: { path: string; line?: number }[] = [];
+	const pushPath = (value: unknown) => {
+		if (typeof value !== "string" || value.length === 0) return;
+		// ACP locations carry file paths that the editor host will open or focus;
+		// they must be absolute or the client cannot resolve them. Resolve raw
+		// tool args (often cwd-relative) against the session cwd before sending.
+		let resolved: string;
+		try {
+			resolved = resolveToCwd(value, cwd);
+		} catch {
+			return;
+		}
+		if (out.some(location => location.path === resolved)) return;
+		out.push({ path: resolved });
+	};
+	if (explicitPaths) {
+		for (const filePath of explicitPaths) pushPath(filePath);
+		return out;
+	}
+	pushPath(args.path);
+	pushPath(args.file);
+	if (Array.isArray(args.paths)) {
+		for (const filePath of args.paths) {
+			if (typeof filePath === "string") pushPath(filePath);
+		}
+	}
+	pushPath(args.oldPath);
+	pushPath(args.newPath);
+	pushPath(args.from);
+	pushPath(args.to);
+	pushPath(args.source);
+	pushPath(args.destination);
+	return out;
+}

package/src/session/agent-session-error-log.test.ts

@@ -7,7 +7,7 @@
 import { afterAll, afterEach, describe, expect, it } from "bun:test";
 import type { AssistantMessage } from "@oh-my-pi/pi-ai";
 import { logger } from "@oh-my-pi/pi-utils";
-import { logProviderTurnError } from "./agent-session";
+import { logProviderTurnError } from "./messages";
 
 function makeMessage(overrides: Partial<AssistantMessage>): AssistantMessage {
 	return {

package/src/session/agent-session-events.ts

@@ -0,0 +1,66 @@
+import type { AgentEvent, ThinkingLevel } from "@oh-my-pi/pi-agent-core";
+import type { CompactionResult } from "@oh-my-pi/pi-agent-core/compaction";
+import type { Effort } from "@oh-my-pi/pi-ai";
+import type { Rule } from "../capability/rule";
+import type { RecoveredRetryError } from "../extensibility/shared-events";
+import type { Goal, GoalModeState } from "../goals/state";
+import type { ConfiguredThinkingLevel } from "../thinking";
+import type { TodoItem } from "../tools/todo";
+import type { CustomMessage } from "./messages";
+
+/** Session-specific events that extend the core AgentEvent. */
+export type AgentSessionEvent =
+	| Exclude<AgentEvent, { type: "agent_end" }>
+	| (Extract<AgentEvent, { type: "agent_end" }> & {
+			/** False when an async delivery will resume the session before its true final settle. */
+			isTerminal?: boolean;
+	  })
+	| {
+			type: "auto_compaction_start";
+			reason: "threshold" | "overflow" | "idle" | "incomplete";
+			action: "context-full" | "handoff" | "shake" | "snapcompact";
+	  }
+	| {
+			type: "auto_compaction_end";
+			action: "context-full" | "handoff" | "shake" | "snapcompact";
+			result: CompactionResult | undefined;
+			aborted: boolean;
+			willRetry: boolean;
+			errorMessage?: string;
+			/** True when compaction was skipped for a benign reason. */
+			skipped?: boolean;
+	  }
+	| {
+			type: "auto_retry_start";
+			attempt: number;
+			maxAttempts: number;
+			delayMs: number;
+			errorMessage: string;
+			errorId?: number;
+	  }
+	| {
+			type: "auto_retry_end";
+			success: boolean;
+			attempt: number;
+			finalError?: string;
+			recoveredErrors?: RecoveredRetryError[];
+	  }
+	| { type: "retry_fallback_applied"; from: string; to: string; role: string }
+	| { type: "retry_fallback_succeeded"; model: string; role: string }
+	| { type: "ttsr_triggered"; rules: Rule[] }
+	| { type: "todo_reminder"; todos: TodoItem[]; attempt: number; maxAttempts: number }
+	| { type: "todo_auto_clear" }
+	| { type: "irc_message"; message: CustomMessage }
+	| { type: "notice"; level: "info" | "warning" | "error"; message: string; source?: string }
+	| {
+			type: "thinking_level_changed";
+			thinkingLevel: ThinkingLevel | undefined;
+			/** The user-configured selector when it differs from the effective level. */
+			configured?: ConfiguredThinkingLevel;
+			/** The level `auto` resolved to this turn, once classified. */
+			resolved?: Effort;
+	  }
+	| { type: "goal_updated"; goal: Goal | null; state?: GoalModeState };
+
+/** Listener function for agent session events. */
+export type AgentSessionEventListener = (event: AgentSessionEvent) => void;

package/src/session/agent-session-types.ts

@@ -0,0 +1,343 @@
+import type { Agent, AgentMessage, AgentTool, StreamFn, ThinkingLevel } from "@oh-my-pi/pi-agent-core";
+import type {
+	Context,
+	ImageContent,
+	Message,
+	MessageAttribution,
+	Model,
+	OAuthAccountSummary,
+	ServiceTierByFamily,
+	SimpleStreamOptions,
+	ToolChoice,
+} from "@oh-my-pi/pi-ai";
+import type { postmortem } from "@oh-my-pi/pi-utils";
+import type { AdvisorConfig } from "../advisor";
+import type { AsyncJob, AsyncJobDeliveryState, AsyncJobManager } from "../async";
+import type { ModelRegistry } from "../config/model-registry";
+import type { PromptTemplate } from "../config/prompt-templates";
+import type { Settings, SkillsSettings } from "../config/settings";
+import type { RawSseDebugBuffer } from "../debug/raw-sse-buffer";
+import type { TtsrManager } from "../export/ttsr";
+import type { LoadedCustomCommand } from "../extensibility/custom-commands";
+import type { ExtensionRunner } from "../extensibility/extensions";
+import type { ContextUsage } from "../extensibility/extensions/types";
+import type { Skill, SkillWarning } from "../extensibility/skills";
+import type { FileSlashCommand } from "../extensibility/slash-commands";
+import type { SecretObfuscator } from "../secrets/obfuscator";
+import type { ConfiguredThinkingLevel } from "../thinking";
+import type { XdevRegistry } from "../tools/xdev";
+import type { SessionManager } from "./session-manager";
+
+/** Maximum time the interactive shutdown path waits for Mnemopi consolidation. */
+export const SHUTDOWN_CONSOLIDATE_BUDGET_MS = 1_500;
+
+/** Options controlling session disposal. */
+export interface AgentSessionDisposeOptions {
+	mnemopiConsolidateTimeoutMs?: number;
+	/**
+	 * Postmortem reason that triggered this dispose (signal/fatal teardown
+	 * paths). When set, the persisted `session_exit` diagnostic records it
+	 * instead of the generic `"dispose"` used for normal programmatic disposal
+	 * (`/quit`, test teardown, subagent completion).
+	 */
+	reason?: postmortem.Reason;
+}
+
+/** Listener notified when command metadata changes. */
+export type CommandMetadataChangedListener = () => void | Promise<void>;
+/** Public summary of an asynchronous job. */
+export type AsyncJobSnapshotItem = Pick<AsyncJob, "id" | "type" | "status" | "label" | "startTime">;
+
+/** Snapshot of running, recent, and pending-delivery asynchronous jobs. */
+export interface AsyncJobSnapshot {
+	running: AsyncJobSnapshotItem[];
+	recent: AsyncJobSnapshotItem[];
+	delivery: AsyncJobDeliveryState;
+}
+
+export type { ShakeMode, ShakeResult } from "./shake-types";
+
+/**
+ * Prewalk switches an active session one-way from its starting model to a
+ * fast/cheap target after implementation begins.
+ */
+export interface Prewalk {
+	target: Model;
+	thinkingLevel?: ConfiguredThinkingLevel;
+}
+
+/**
+ * PlanYolo starts in read-only plan mode, auto-approves the proposal, then
+ * switches to a target model for implementation.
+ */
+export interface PlanYolo {
+	target: Model;
+	thinkingLevel?: ConfiguredThinkingLevel;
+}
+
+/** Details shown when confirming a usage-reserve-triggered model fallback. */
+export interface UsageFallbackConfirmation {
+	from: string;
+	to: string;
+	remainingPercent: number | undefined;
+}
+
+/** Identifies a retry fallback chain already entered during startup model resolution. */
+export interface InitialRetryFallbackState {
+	/** Role whose configured primary was unavailable. */
+	role: string;
+	/** Configured primary selector retained for restoration when it becomes available. */
+	originalSelector: string;
+	/** Thinking selector configured for the unavailable primary. */
+	originalThinkingLevel: ConfiguredThinkingLevel | undefined;
+	/** Prevent cooldown restoration when startup selected this fallback from live usage health. */
+	pinned?: boolean;
+}
+
+/** Dependencies and initial state used to construct an AgentSession. */
+export interface AgentSessionConfig {
+	agent: Agent;
+	sessionManager: SessionManager;
+	settings: Settings;
+	/** Whether the caller explicitly requested yolo/auto-approve behavior for this session. */
+	autoApprove?: boolean;
+	/** Models to cycle through with Ctrl+P (from --models flag). */
+	scopedModels?: Array<{ model: Model; thinkingLevel?: ThinkingLevel }>;
+	/** Initial session thinking selector. */
+	thinkingLevel?: ConfiguredThinkingLevel;
+	/** Retry chain ownership when startup selected one of its fallback entries. */
+	initialRetryFallback?: InitialRetryFallbackState;
+	/** Prewalk from the starting model to a fast/cheap target after implementation begins. */
+	prewalk?: Prewalk;
+	/** Force read-only plan mode at start, auto-approve, then switch to the target. */
+	planYolo?: PlanYolo;
+	/** Initial per-family service tiers for the live session. */
+	serviceTierByFamily?: ServiceTierByFamily;
+	/** Prompt templates for expansion. */
+	promptTemplates?: PromptTemplate[];
+	/** File-based slash commands for expansion. */
+	slashCommands?: FileSlashCommand[];
+	/** Extension runner created with wrapped tools. */
+	extensionRunner?: ExtensionRunner;
+	/** Loaded skills already discovered by the SDK. */
+	skills?: Skill[];
+	/** Skill loading warnings already captured by the SDK. */
+	skillWarnings?: SkillWarning[];
+	/** Whether runtime reloads may rediscover disk-backed skills. */
+	skillsReloadable?: boolean;
+	/** Custom TypeScript slash commands. */
+	customCommands?: LoadedCustomCommand[];
+	skillsSettings?: SkillsSettings;
+	/** Agent directory used when changing memory backends in a live session. */
+	memoryAgentDir?: string;
+	/** Recursion depth used to suppress live backend replacement in subagents. */
+	memoryTaskDepth?: number;
+	/** Creates built-in memory tools for the current backend. */
+	createMemoryTools?: () => Promise<AgentTool[]>;
+	/** Creates the built-in `computer` tool for session-scoped runtime enablement (see {@link AgentSession.setComputerToolEnabled}). */
+	createComputerTool?: () => Promise<AgentTool | null>;
+	/** Model registry for API key resolution and model discovery. */
+	modelRegistry: ModelRegistry;
+	/** Tool registry for LSP and settings. */
+	toolRegistry?: Map<string, AgentTool>;
+	/** Creates tools registered only while vibe mode is active. */
+	createVibeTools?: () => AgentTool[];
+	/** Names whose current registry entry is the built-in implementation. */
+	builtInToolNames?: Iterable<string>;
+	/** Updates tool-session predicates from the live active tool set. */
+	setActiveToolNames?: (names: Iterable<string>) => void;
+	/** Registers the write transport when runtime xdev mounts first need it. */
+	ensureWriteRegistered?: () => Promise<boolean>;
+	/** Current session pre-LLM message transform pipeline. */
+	transformContext?: (messages: AgentMessage[], signal?: AbortSignal) => AgentMessage[] | Promise<AgentMessage[]>;
+	/** Provider request transform applied after message conversion. */
+	transformProviderContext?: (context: Context, model: Model) => Context | Promise<Context>;
+	/** Stream wrapper for side-channel requests. */
+	sideStreamFn?: StreamFn;
+	/** Stream wrapper for advisor requests. */
+	advisorStreamFn?: StreamFn;
+	/** Prefer websocket transport for OpenAI Codex requests when supported. */
+	preferWebsockets?: boolean;
+	/** Provider payload hook used by the active session request path. */
+	onPayload?: SimpleStreamOptions["onPayload"];
+	/** Provider response hook used by the active session request path. */
+	onResponse?: SimpleStreamOptions["onResponse"];
+	/** Raw SSE hook used by the active session request path. */
+	onSseEvent?: SimpleStreamOptions["onSseEvent"];
+	/** Per-session raw SSE diagnostic buffer. */
+	rawSseDebugBuffer?: RawSseDebugBuffer;
+	/** Current session message-to-LLM conversion pipeline. */
+	convertToLlm?: (messages: AgentMessage[]) => Message[] | Promise<Message[]>;
+	/** System prompt builder that can consider tool availability. */
+	rebuildSystemPrompt?: (toolNames: string[], tools: Map<string, AgentTool>) => Promise<{ systemPrompt: string[] }>;
+	/** Local calendar date provider used by prompt-cache invalidation. */
+	getLocalCalendarDate?: () => string;
+	/** Tools mounted under `xd://`, for `/tools` display. */
+	getXdevToolEntries?: () => Array<{ name: string; summary: string }>;
+	/** Session-owned `xd://` registry. */
+	xdevRegistry?: XdevRegistry;
+	/** Discoverable tools mounted under `xd://` in the initial enabled set. */
+	initialMountedXdevToolNames?: string[];
+	/** Names pinned top-level during runtime repartitioning. */
+	presentationPinnedToolNames?: ReadonlySet<string>;
+	/** Accessor for live MCP server instructions. */
+	getMcpServerInstructions?: () => Map<string, string> | undefined;
+	/** Time-traveling stream-rule manager. */
+	ttsrManager?: TtsrManager;
+	/** Secret obfuscator for provider and edit content. */
+	obfuscator?: SecretObfuscator;
+	/** Inherited eval executor session id from a parent agent. */
+	parentEvalSessionId?: string;
+	/** Logical owner for retained eval kernels created by this session. */
+	evalKernelOwnerId?: string;
+	/** Async job manager owned and disposed by this session. */
+	ownedAsyncJobManager?: AsyncJobManager;
+	/** Async job manager visible to this session. */
+	asyncJobManager?: AsyncJobManager;
+	/** Registry identity used for IRC routing. */
+	agentId?: string;
+	/** Whether this is a top-level or subagent session. */
+	agentKind?: "main" | "sub";
+	/** Provider-facing session ID override. */
+	providerSessionId?: string;
+	/** Whether the provider prompt-cache key was explicit or fork-inherited. */
+	providerPromptCacheKeySource?: "explicit" | "fork";
+	/** Full advisor toolset built against an advisor-scoped tool session. */
+	advisorTools?: AgentTool[];
+	/** Preloaded watchdog prompt content for the advisor. */
+	advisorWatchdogPrompt?: string;
+	/** Shared advisor instructions loaded from WATCHDOG.yml. */
+	advisorSharedInstructions?: string;
+	/** Project context rendered for advisor sessions. */
+	advisorContextPrompt?: string;
+	/** Advisors discovered from WATCHDOG.yml. */
+	advisorConfigs?: AdvisorConfig[];
+	/** Strip tool descriptions from provider-bound side-request tool specs. */
+	pruneToolDescriptions?: boolean;
+	/** Disconnect the MCP manager owned by this session during disposal. */
+	disconnectOwnedMcpManager?: () => Promise<void>;
+	/** System prompt used by automatic session-title generation. */
+	titleSystemPrompt?: string;
+}
+
+/** Options for AgentSession.prompt(). */
+export interface PromptOptions {
+	/** Whether to expand file-based prompt templates (default: true). */
+	expandPromptTemplates?: boolean;
+	/** Image attachments. */
+	images?: ImageContent[];
+	/** Queue behavior while streaming. */
+	streamingBehavior?: "steer" | "followUp";
+	/** Optional tool choice override for the next LLM call. */
+	toolChoice?: ToolChoice;
+	/** Send as a developer/system message instead of user. */
+	synthetic?: boolean;
+	/** Whether this prompt is a deliberate user action. */
+	userInitiated?: boolean;
+	/** Explicit billing/initiator attribution. */
+	attribution?: MessageAttribution;
+	/** Skip pre-send compaction checks for this prompt. */
+	skipCompactionCheck?: boolean;
+}
+
+/** Options for AgentSession.followUp(). */
+export interface FollowUpOptions {
+	/** Enqueue as a hidden developer message instead of a user follow-up. */
+	synthetic?: boolean;
+	/** Whether to expand file-based prompt templates (default: true). */
+	expandPromptTemplates?: boolean;
+	/** Explicit billing/initiator attribution. */
+	attribution?: MessageAttribution;
+}
+
+/** Result from a handoff operation. */
+export interface HandoffResult {
+	document: string;
+	savedPath?: string;
+}
+
+/** Options controlling handoff generation. */
+export interface SessionHandoffOptions {
+	autoTriggered?: boolean;
+	signal?: AbortSignal;
+	onSwitchCancelled?: () => void;
+}
+
+/** Result from cycleModel(). */
+export interface ModelCycleResult {
+	model: Model;
+	thinkingLevel: ThinkingLevel | undefined;
+	/** Whether cycling through scoped models or all available models. */
+	isScoped: boolean;
+}
+
+/** Result from cycleRoleModels(). */
+export interface RoleModelCycleResult {
+	model: Model;
+	thinkingLevel: ThinkingLevel | undefined;
+	role: string;
+}
+
+/** A configured role resolved to a concrete model. */
+export interface ResolvedRoleModel {
+	role: string;
+	model: Model;
+	thinkingLevel?: ConfiguredThinkingLevel;
+	explicitThinkingLevel: boolean;
+}
+
+/** Resolvable role models and the currently active index. */
+export interface RoleModelCycle {
+	models: ResolvedRoleModel[];
+	currentIndex: number;
+}
+
+/** Token breakdown for the current provider context. */
+export interface ContextUsageBreakdown {
+	contextWindow: number;
+	anchored: boolean;
+	usedTokens: number;
+	systemPromptTokens: number;
+	systemToolsTokens: number;
+	systemContextTokens: number;
+	skillsTokens: number;
+	messagesTokens: number;
+}
+
+/** Session statistics for the `/session` command. */
+export interface SessionStats {
+	sessionFile: string | undefined;
+	sessionId: string;
+	userMessages: number;
+	assistantMessages: number;
+	toolCalls: number;
+	toolResults: number;
+	totalMessages: number;
+	tokens: {
+		input: number;
+		output: number;
+		reasoning: number;
+		cacheRead: number;
+		cacheWrite: number;
+		total: number;
+	};
+	premiumRequests: number;
+	cost: number;
+	contextUsage?: ContextUsage;
+}
+
+/** Stored OAuth accounts available to the current model provider. */
+export interface SessionOAuthAccountList {
+	provider: string;
+	accounts: OAuthAccountSummary[];
+}
+
+/** IDs for a newly created session and the session it replaced. */
+export interface FreshSessionResult {
+	previousSessionId: string;
+	sessionId: string;
+	closedProviderSessions: number;
+}
+
+/** Queued user content restored to the editor. */
+export type RestoredQueuedMessage = { text: string; images?: ImageContent[] };