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

package/dist/types/session/agent-session-events.d.ts

@@ -0,0 +1,84 @@
+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.js";
+import type { RecoveredRetryError } from "../extensibility/shared-events.js";
+import type { Goal, GoalModeState } from "../goals/state.js";
+import type { ConfiguredThinkingLevel } from "../thinking.js";
+import type { TodoItem } from "../tools/todo.js";
+import type { CustomMessage } from "./messages.js";
+/** 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/dist/types/session/agent-session-types.d.ts

@@ -0,0 +1,314 @@
+import type { Agent, AgentMessage, AgentTool, StreamFn, ThinkingLevel } from "@oh-my-pi/pi-agent-core";
+import type { Context, ImageContent, Message, MessageAttribution, Model, ServiceTierByFamily, SimpleStreamOptions, ToolChoice } from "@oh-my-pi/pi-ai";
+import type { postmortem } from "@oh-my-pi/pi-utils";
+import type { AdvisorConfig } from "../advisor/index.js";
+import type { AsyncJob, AsyncJobDeliveryState, AsyncJobManager } from "../async/index.js";
+import type { ModelRegistry } from "../config/model-registry.js";
+import type { PromptTemplate } from "../config/prompt-templates.js";
+import type { Settings, SkillsSettings } from "../config/settings.js";
+import type { RawSseDebugBuffer } from "../debug/raw-sse-buffer.js";
+import type { TtsrManager } from "../export/ttsr.js";
+import type { LoadedCustomCommand } from "../extensibility/custom-commands/index.js";
+import type { ExtensionRunner } from "../extensibility/extensions/index.js";
+import type { ContextUsage } from "../extensibility/extensions/types.js";
+import type { Skill, SkillWarning } from "../extensibility/skills.js";
+import type { FileSlashCommand } from "../extensibility/slash-commands.js";
+import type { SecretObfuscator } from "../secrets/obfuscator.js";
+import type { ConfiguredThinkingLevel } from "../thinking.js";
+import type { XdevRegistry } from "../tools/xdev.js";
+import type { SessionManager } from "./session-manager.js";
+/** Maximum time the interactive shutdown path waits for Mnemopi consolidation. */
+export declare const SHUTDOWN_CONSOLIDATE_BUDGET_MS = 1500;
+/** 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.js";
+/**
+ * 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[]>;
+    /** 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;
+}
+/** 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[];
+};