@oh-my-pi/pi-coding-agent 15.1.1 → 15.1.3

package/dist/types/extensibility/shared-events.d.ts

@@ -0,0 +1,279 @@
+/**
+ * Event payload and result shapes shared between the extensions and hooks
+ * subsystems.
+ *
+ * Both subsystems observe the same agent/session lifecycle, so the *event*
+ * payloads (what happened) and the simpler *result* shapes (handler return
+ * values that don't depend on subsystem-specific identifiers like
+ * `AgentMessage` vs `Message`) are intentionally identical.
+ *
+ * Anything that diverges between the two subsystems — UI context, runtime
+ * context, command context, tool-call discrimination, or return shapes that
+ * carry subsystem-specific message types — lives in the per-subsystem
+ * `types.ts` files and is documented there.
+ */
+import type { AgentMessage } from "@oh-my-pi/pi-agent-core";
+import type { CompactionPreparation, CompactionResult } from "@oh-my-pi/pi-agent-core/compaction";
+import type { ImageContent, TextContent, ToolResultMessage } from "@oh-my-pi/pi-ai";
+import type { Rule } from "../capability/rule";
+import type { Goal, GoalModeState } from "../goals/state";
+import type { BranchSummaryEntry, CompactionEntry, SessionEntry } from "../session/session-manager";
+import type { TodoItem } from "../tools/todo-write";
+/** Fired on initial session load */
+export interface SessionStartEvent {
+    type: "session_start";
+}
+/** Fired before switching to another session (can be cancelled) */
+export interface SessionBeforeSwitchEvent {
+    type: "session_before_switch";
+    /** Reason for the switch */
+    reason: "new" | "resume" | "fork";
+    /** Session file we're switching to (only for "resume") */
+    targetSessionFile?: string;
+}
+/** Fired after switching to another session */
+export interface SessionSwitchEvent {
+    type: "session_switch";
+    /** Reason for the switch */
+    reason: "new" | "resume" | "fork";
+    /** Session file we came from */
+    previousSessionFile: string | undefined;
+}
+/** Fired before branching a session (can be cancelled) */
+export interface SessionBeforeBranchEvent {
+    type: "session_before_branch";
+    /** ID of the entry to branch from */
+    entryId: string;
+}
+/** Fired after branching a session */
+export interface SessionBranchEvent {
+    type: "session_branch";
+    previousSessionFile: string | undefined;
+}
+/** Fired before context compaction (can be cancelled or customized) */
+export interface SessionBeforeCompactEvent {
+    type: "session_before_compact";
+    /** Compaction preparation with messages to summarize, file ops, previous summary, etc. */
+    preparation: CompactionPreparation;
+    /** Branch entries (root to current leaf). Use to inspect custom state or previous compactions. */
+    branchEntries: SessionEntry[];
+    /** Optional user-provided instructions for the summary */
+    customInstructions?: string;
+    /** Abort signal - handlers should pass this to LLM calls and check it periodically */
+    signal: AbortSignal;
+}
+/** Fired before compaction summarization to customize prompts/context */
+export interface SessionCompactingEvent {
+    type: "session.compacting";
+    sessionId: string;
+    messages: AgentMessage[];
+}
+/** Fired after context compaction */
+export interface SessionCompactEvent {
+    type: "session_compact";
+    compactionEntry: CompactionEntry;
+    /** Whether the compaction entry was provided by an extension/hook */
+    fromExtension: boolean;
+}
+/** Fired on process exit (SIGINT/SIGTERM) */
+export interface SessionShutdownEvent {
+    type: "session_shutdown";
+}
+/** Preparation data for tree navigation (used by session_before_tree event) */
+export interface TreePreparation {
+    /** Node being switched to */
+    targetId: string;
+    /** Current active leaf (being abandoned), null if no current position */
+    oldLeafId: string | null;
+    /** Common ancestor of target and old leaf, null if no common ancestor */
+    commonAncestorId: string | null;
+    /** Entries to summarize (old leaf back to common ancestor or compaction) */
+    entriesToSummarize: SessionEntry[];
+    /** Whether user chose to summarize */
+    userWantsSummary: boolean;
+}
+/** Fired before navigating to a different node in the session tree (can be cancelled) */
+export interface SessionBeforeTreeEvent {
+    type: "session_before_tree";
+    /** Preparation data for the navigation */
+    preparation: TreePreparation;
+    /** Abort signal - honors Escape during summarization (model available via ctx.model) */
+    signal: AbortSignal;
+}
+/** Fired after navigating to a different node in the session tree */
+export interface SessionTreeEvent {
+    type: "session_tree";
+    /** The new active leaf, null if navigated to before first entry */
+    newLeafId: string | null;
+    /** Previous active leaf, null if there was no position */
+    oldLeafId: string | null;
+    /** Branch summary entry if one was created */
+    summaryEntry?: BranchSummaryEntry;
+    /** Whether summary came from extension/hook */
+    fromExtension?: boolean;
+}
+/** Union of all session event types */
+export interface GoalUpdatedEvent {
+    type: "goal_updated";
+    goal: Goal | null;
+    state?: GoalModeState;
+}
+export type SessionEvent = SessionStartEvent | SessionBeforeSwitchEvent | SessionSwitchEvent | SessionBeforeBranchEvent | SessionBranchEvent | SessionBeforeCompactEvent | SessionCompactingEvent | SessionCompactEvent | SessionShutdownEvent | SessionBeforeTreeEvent | SessionTreeEvent | GoalUpdatedEvent;
+/**
+ * Fired before each LLM call.
+ *
+ * Original session messages are NOT modified - only the messages sent to the
+ * LLM are affected when a handler returns a replacement (the return shape
+ * differs between extensions and hooks; see each subsystem's
+ * `ContextEventResult`).
+ */
+export interface ContextEvent {
+    type: "context";
+    /** Messages about to be sent to the LLM (deep copy, safe to modify) */
+    messages: AgentMessage[];
+}
+/**
+ * Fired when an agent loop starts (once per user prompt).
+ */
+export interface AgentStartEvent {
+    type: "agent_start";
+}
+/** Fired when an agent loop ends */
+export interface AgentEndEvent {
+    type: "agent_end";
+    messages: AgentMessage[];
+}
+/** Fired at the start of each turn */
+export interface TurnStartEvent {
+    type: "turn_start";
+    turnIndex: number;
+    timestamp: number;
+}
+/** Fired at the end of each turn */
+export interface TurnEndEvent {
+    type: "turn_end";
+    turnIndex: number;
+    message: AgentMessage;
+    toolResults: ToolResultMessage[];
+}
+/** Fired when auto-compaction starts */
+export interface AutoCompactionStartEvent {
+    type: "auto_compaction_start";
+    reason: "threshold" | "overflow" | "idle";
+    action: "context-full" | "handoff";
+}
+/** Fired when auto-compaction ends */
+export interface AutoCompactionEndEvent {
+    type: "auto_compaction_end";
+    action: "context-full" | "handoff";
+    result: CompactionResult | undefined;
+    aborted: boolean;
+    willRetry: boolean;
+    errorMessage?: string;
+    /** True when compaction was skipped for a benign reason (no model, no candidates, nothing to compact). */
+    skipped?: boolean;
+}
+/** Fired when auto-retry starts */
+export interface AutoRetryStartEvent {
+    type: "auto_retry_start";
+    attempt: number;
+    maxAttempts: number;
+    delayMs: number;
+    errorMessage: string;
+}
+/** Fired when auto-retry ends */
+export interface AutoRetryEndEvent {
+    type: "auto_retry_end";
+    success: boolean;
+    attempt: number;
+    finalError?: string;
+}
+/** Fired when TTSR rule matching interrupts generation */
+export interface TtsrTriggeredEvent {
+    type: "ttsr_triggered";
+    rules: Rule[];
+}
+/** Fired when todo reminder logic detects unfinished todos */
+export interface TodoReminderEvent {
+    type: "todo_reminder";
+    todos: TodoItem[];
+    attempt: number;
+    maxAttempts: number;
+}
+/**
+ * Return type for `tool_call` handlers.
+ * Allows handlers to block tool execution.
+ */
+export interface ToolCallEventResult {
+    /** If true, block the tool from executing */
+    block?: boolean;
+    /** Reason for blocking (returned to LLM as error) */
+    reason?: string;
+}
+/**
+ * Return type for `tool_result` handlers.
+ * Allows handlers to modify tool results.
+ */
+export interface ToolResultEventResult {
+    /** Replacement content array (text and images) */
+    content?: (TextContent | ImageContent)[];
+    /** Replacement details */
+    details?: unknown;
+    /** Override isError flag */
+    isError?: boolean;
+}
+/** Return type for `session_before_switch` handlers */
+export interface SessionBeforeSwitchResult {
+    /** If true, cancel the switch */
+    cancel?: boolean;
+}
+/** Return type for `session_before_branch` handlers */
+export interface SessionBeforeBranchResult {
+    /**
+     * If true, abort the branch entirely. No new session file is created,
+     * conversation stays unchanged.
+     */
+    cancel?: boolean;
+    /**
+     * If true, the branch proceeds (new session file created, session state updated)
+     * but the in-memory conversation is NOT rewound to the branch point.
+     *
+     * Use case: git-checkpoint handler that restores code state separately.
+     * The handler handles state restoration itself, so it doesn't want the
+     * agent's conversation to be rewound (which would lose recent context).
+     *
+     * - `cancel: true` → nothing happens, user stays in current session
+     * - `skipConversationRestore: true` → branch happens, but messages stay as-is
+     * - neither → branch happens AND messages rewind to branch point (default)
+     */
+    skipConversationRestore?: boolean;
+}
+/** Return type for `session_before_compact` handlers */
+export interface SessionBeforeCompactResult {
+    /** If true, cancel the compaction */
+    cancel?: boolean;
+    /** Custom compaction result - SessionManager adds id/parentId */
+    compaction?: CompactionResult;
+}
+/** Return type for `session.compacting` handlers */
+export interface SessionCompactingResult {
+    /** Additional context lines to include in summary */
+    context?: string[];
+    /** Override the default compaction prompt */
+    prompt?: string;
+    /** Custom data to store in compaction entry */
+    preserveData?: Record<string, unknown>;
+}
+/** Return type for `session_before_tree` handlers */
+export interface SessionBeforeTreeResult {
+    /** If true, cancel the navigation entirely */
+    cancel?: boolean;
+    /**
+     * Custom summary (skips default summarizer).
+     * Only used if preparation.userWantsSummary is true.
+     */
+    summary?: {
+        summary: string;
+        details?: unknown;
+    };
+}

package/dist/types/extensibility/skills.d.ts

@@ -0,0 +1,57 @@
+import type { SourceMeta } from "../capability/types";
+import type { SkillsSettings } from "../config/settings";
+import type { SkillPromptDetails } from "../session/messages";
+export interface Skill {
+    name: string;
+    description: string;
+    filePath: string;
+    baseDir: string;
+    source: string;
+    /**
+     * When `true`, the skill is loaded and reachable via `skill://<name>` and
+     * (when enabled) `/skill:<name>`, but is excluded from the rendered system
+     * prompt's `<skills>` listing.
+     */
+    hide?: boolean;
+    /** Source metadata for display */
+    _source?: SourceMeta;
+}
+export interface SkillWarning {
+    skillPath: string;
+    message: string;
+}
+export interface LoadSkillsResult {
+    skills: Skill[];
+    warnings: SkillWarning[];
+}
+/**
+ * Process-global snapshot of skills the active session loaded.
+ * Read by internal URL protocol handlers (skill://).
+ */
+export declare function getActiveSkills(): readonly Skill[];
+/** Replace the active skill snapshot. Called once per top-level session. */
+export declare function setActiveSkills(value: readonly Skill[]): void;
+/** Reset the active skill snapshot. Test-only. */
+export declare function resetActiveSkillsForTests(): void;
+export interface LoadSkillsFromDirOptions {
+    /** Directory to scan for skills */
+    dir: string;
+    /** Source identifier for these skills */
+    source: string;
+}
+export declare function loadSkillsFromDir(options: LoadSkillsFromDirOptions): Promise<LoadSkillsResult>;
+export interface LoadSkillsOptions extends SkillsSettings {
+    /** Working directory for project-local skills. Default: getProjectDir() */
+    cwd?: string;
+}
+/**
+ * Load skills from all configured locations.
+ * Returns skills and any validation warnings.
+ */
+export declare function loadSkills(options?: LoadSkillsOptions): Promise<LoadSkillsResult>;
+export interface BuiltSkillPromptMessage {
+    message: string;
+    details: SkillPromptDetails;
+}
+export declare function getSkillSlashCommandName(skill: Pick<Skill, "name">): string;
+export declare function buildSkillPromptMessage(skill: Pick<Skill, "name" | "filePath">, args: string): Promise<BuiltSkillPromptMessage>;

package/dist/types/extensibility/slash-commands.d.ts

@@ -0,0 +1,48 @@
+import type { AutocompleteItem } from "@oh-my-pi/pi-tui";
+import { type BuiltinSlashCommand } from "../slash-commands/builtin-registry";
+export type SlashCommandSource = "extension" | "prompt" | "skill";
+export type SlashCommandLocation = "user" | "project" | "path";
+export interface SlashCommandInfo {
+    name: string;
+    description?: string;
+    source: SlashCommandSource;
+    location?: SlashCommandLocation;
+    path?: string;
+}
+export type { BuiltinSlashCommand, SubcommandDef } from "../slash-commands/builtin-registry";
+/**
+ * Materialized builtin slash commands with completion functions derived from
+ * declarative subcommand/hint definitions.
+ */
+export declare const BUILTIN_SLASH_COMMANDS: ReadonlyArray<BuiltinSlashCommand & {
+    getArgumentCompletions?: (prefix: string) => AutocompleteItem[] | null;
+    getInlineHint?: (argumentText: string) => string | null;
+}>;
+/**
+ * Represents a custom slash command loaded from a file
+ */
+export interface FileSlashCommand {
+    name: string;
+    description: string;
+    content: string;
+    source: string;
+    /** Source metadata for display */
+    _source?: {
+        providerName: string;
+        level: "user" | "project" | "native";
+    };
+}
+export interface LoadSlashCommandsOptions {
+    /** Working directory for project-local commands. Default: getProjectDir() */
+    cwd?: string;
+}
+/**
+ * Load all custom slash commands using the capability API.
+ * Loads from all registered providers (builtin, user, project).
+ */
+export declare function loadSlashCommands(options?: LoadSlashCommandsOptions): Promise<FileSlashCommand[]>;
+/**
+ * Expand a slash command if it matches a file-based command.
+ * Returns the expanded content or the original text if not a slash command.
+ */
+export declare function expandSlashCommand(text: string, fileCommands: FileSlashCommand[]): string;

package/dist/types/extensibility/tool-proxy.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Defines lazy proxy properties on a wrapper so it forwards to the underlying tool.
+ */
+export declare function applyToolProxy<TTool extends object>(tool: TTool, wrapper: object): void;

package/dist/types/extensibility/typebox.d.ts

@@ -0,0 +1,155 @@
+/**
+ * Minimal `@sinclair/typebox` runtime compatibility shim, backed by Zod.
+ *
+ * Historically the coding agent injected the real `@sinclair/typebox` (~5MB
+ * dependency) into extensions, hooks, custom tools, and custom commands so
+ * they could author parameter schemas as `Type.Object({ name: Type.String() })`.
+ * Internally everything already runs through Zod (`wire.ts`, `validation.ts`);
+ * the only reason TypeBox remained was extension-author compat.
+ *
+ * This module replaces that injection with a tiny façade whose `Type` builders
+ * return Zod schemas. Output is indistinguishable from hand-written Zod inside
+ * the agent pipeline:
+ *
+ *   - `isZodSchema()` keys off the Zod `_zod` marker that every schema carries.
+ *   - `zodToWireSchema()` emits the same draft 2020-12 JSON Schema providers expect
+ *     from TypeBox-authored tools (defaulted fields treated as optional, etc.).
+ *
+ * The surface intentionally covers only the common TypeBox builders. Plugins
+ * that reached for niche TypeBox-only APIs (`TypeCompiler`, the global
+ * `TypeRegistry`, custom `Symbol(TypeBox.Kind)` introspection) must vendor
+ * `@sinclair/typebox` directly in their own package.
+ */
+import { type ZodArray, type ZodEnum, type ZodObject, type ZodOptional, type ZodRawShape, type ZodType, z } from "zod/v4";
+export type TSchema = ZodType;
+export type Static<T extends ZodType> = z.infer<T>;
+export type TAny = ZodType;
+export type TUnknown = ZodType;
+export type TNever = ZodType;
+export type TNull = ZodType;
+export type TString = z.ZodString;
+export type TNumber = z.ZodNumber;
+export type TInteger = z.ZodNumber;
+export type TBoolean = z.ZodBoolean;
+export type TLiteral<V extends string | number | boolean> = z.ZodLiteral<V>;
+export type TArray<E extends ZodType> = ZodArray<E>;
+export type TObject<P extends ZodRawShape = ZodRawShape> = ZodObject<P>;
+export type TOptional<E extends ZodType> = ZodOptional<E>;
+export type TUnion<_T extends readonly ZodType[] = readonly ZodType[]> = ZodType;
+export type TEnum<T extends readonly (string | number)[] = readonly (string | number)[]> = ZodEnum<{
+    [K in T[number] as `${K}`]: K;
+}>;
+export type TRecord<_K extends ZodType, _V extends ZodType> = ZodType;
+interface Meta {
+    title?: string;
+    description?: string;
+    default?: unknown;
+    examples?: unknown[];
+    [key: string]: unknown;
+}
+interface StringOpts extends Meta {
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    format?: string;
+}
+interface NumberOpts extends Meta {
+    minimum?: number;
+    maximum?: number;
+    exclusiveMinimum?: number;
+    exclusiveMaximum?: number;
+    multipleOf?: number;
+}
+interface ArrayOpts extends Meta {
+    minItems?: number;
+    maxItems?: number;
+    uniqueItems?: boolean;
+}
+interface ObjectOpts extends Meta {
+    /**
+     * TypeBox default: extra keys are preserved. Set `false` to reject unknowns,
+     * `true` to allow any, or a schema to validate them.
+     */
+    additionalProperties?: boolean | ZodType;
+}
+declare function tString(opts?: StringOpts): ZodType;
+declare function tNumber(opts?: NumberOpts): ZodType;
+declare function tInteger(opts?: NumberOpts): ZodType;
+declare function tBoolean(opts?: Meta): ZodType;
+declare function tNull(opts?: Meta): ZodType;
+declare function tAny(opts?: Meta): ZodType;
+declare function tUnknown(opts?: Meta): ZodType;
+declare function tNever(opts?: Meta): ZodType;
+declare function tLiteral<V extends string | number | boolean>(value: V, opts?: Meta): ZodType;
+declare function tUnion<T extends readonly ZodType[]>(schemas: T, opts?: Meta): ZodType;
+declare function tIntersect(schemas: readonly ZodType[], opts?: Meta): ZodType;
+declare function tEnum<T extends Record<string, string | number> | readonly (string | number)[]>(values: T, opts?: Meta): ZodType;
+declare function tArray<E extends ZodType>(item: E, opts?: ArrayOpts): ZodType;
+declare function tTuple(items: readonly ZodType[], opts?: Meta): ZodType;
+declare function tObject<P extends ZodRawShape>(properties: P, opts?: ObjectOpts): ZodObject<P>;
+declare function tRecord<V extends ZodType>(key: ZodType, value: V, opts?: Meta): ZodType;
+declare function tOptional<E extends ZodType>(schema: E, _opts?: Meta): ZodOptional<E>;
+declare function tNullable<E extends ZodType>(schema: E, opts?: Meta): ZodType;
+declare function tReadonly<E extends ZodType>(schema: E): E;
+declare function tPartial<P extends ZodRawShape>(obj: ZodObject<P>): ZodObject<P>;
+declare function tRequired<P extends ZodRawShape>(obj: ZodObject<P>): ZodObject<P>;
+declare function tPick<P extends ZodRawShape, K extends keyof P>(obj: ZodObject<P>, keys: readonly K[]): ZodObject<Pick<P, K>>;
+declare function tOmit<P extends ZodRawShape, K extends keyof P>(obj: ZodObject<P>, keys: readonly K[]): ZodObject<Omit<P, K>>;
+declare function tComposite(objects: readonly ZodObject<ZodRawShape>[], opts?: Meta): ZodObject<ZodRawShape>;
+export declare const Type: {
+    readonly String: typeof tString;
+    readonly Number: typeof tNumber;
+    readonly Integer: typeof tInteger;
+    readonly Boolean: typeof tBoolean;
+    readonly Null: typeof tNull;
+    readonly Any: typeof tAny;
+    readonly Unknown: typeof tUnknown;
+    readonly Never: typeof tNever;
+    readonly Literal: typeof tLiteral;
+    readonly Union: typeof tUnion;
+    readonly Intersect: typeof tIntersect;
+    readonly Enum: typeof tEnum;
+    readonly Array: typeof tArray;
+    readonly Tuple: typeof tTuple;
+    readonly Object: typeof tObject;
+    readonly Record: typeof tRecord;
+    readonly Optional: typeof tOptional;
+    readonly Nullable: typeof tNullable;
+    readonly Readonly: typeof tReadonly;
+    readonly Partial: typeof tPartial;
+    readonly Required: typeof tRequired;
+    readonly Pick: typeof tPick;
+    readonly Omit: typeof tOmit;
+    readonly Composite: typeof tComposite;
+};
+export type TypeBuilder = typeof Type;
+/** Default namespace export so `import * as typebox from "./typebox"` still resolves the `Type` key. */
+declare const _default: {
+    Type: {
+        readonly String: typeof tString;
+        readonly Number: typeof tNumber;
+        readonly Integer: typeof tInteger;
+        readonly Boolean: typeof tBoolean;
+        readonly Null: typeof tNull;
+        readonly Any: typeof tAny;
+        readonly Unknown: typeof tUnknown;
+        readonly Never: typeof tNever;
+        readonly Literal: typeof tLiteral;
+        readonly Union: typeof tUnion;
+        readonly Intersect: typeof tIntersect;
+        readonly Enum: typeof tEnum;
+        readonly Array: typeof tArray;
+        readonly Tuple: typeof tTuple;
+        readonly Object: typeof tObject;
+        readonly Record: typeof tRecord;
+        readonly Optional: typeof tOptional;
+        readonly Nullable: typeof tNullable;
+        readonly Readonly: typeof tReadonly;
+        readonly Partial: typeof tPartial;
+        readonly Required: typeof tRequired;
+        readonly Pick: typeof tPick;
+        readonly Omit: typeof tOmit;
+        readonly Composite: typeof tComposite;
+    };
+};
+export default _default;

package/dist/types/extensibility/utils.d.ts

@@ -0,0 +1,12 @@
+import type { HookUIContext } from "./hooks/types";
+/**
+ * Resolve a file path:
+ * - Absolute paths used as-is
+ * - Paths starting with ~ expanded to home directory
+ * - Relative paths resolved from cwd
+ */
+export declare function resolvePath(filePath: string, cwd: string): string;
+/**
+ * Create a no-op UI context for headless modes.
+ */
+export declare function createNoOpUIContext(): HookUIContext;

package/dist/types/goals/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./runtime";
+export * from "./state";
+export * from "./tools/goal-tool";

package/dist/types/goals/runtime.d.ts

@@ -0,0 +1,63 @@
+import type { Goal, GoalBudgetSteering, GoalModeState, GoalRuntimeEvent, GoalTokenUsage } from "./state";
+export interface GoalRuntimeHost {
+    getState(): GoalModeState | undefined;
+    setState(state: GoalModeState | undefined): void;
+    getCurrentUsage(): GoalTokenUsage;
+    emit(event: GoalRuntimeEvent): void | Promise<void>;
+    persist(mode: "goal" | "goal_paused" | "none", state?: GoalModeState): void;
+    sendHiddenMessage(message: {
+        customType: string;
+        content: string;
+        deliverAs?: "steer" | "followUp" | "nextTurn";
+    }): Promise<void>;
+    now?(): number;
+}
+export interface GoalTurnSnapshot {
+    turnId: string;
+    baselineUsage: GoalTokenUsage;
+    activeGoalId?: string;
+}
+export interface GoalWallClockSnapshot {
+    lastAccountedAt: number;
+    activeGoalId?: string;
+}
+export interface GoalRuntimeSnapshot {
+    turnSnapshot?: GoalTurnSnapshot;
+    wallClock: GoalWallClockSnapshot;
+    budgetReportedFor?: string;
+}
+export type GoalPromptKind = "active" | "continuation" | "budget-limit";
+export declare function remainingTokens(goal: Goal | null | undefined): number | null;
+export declare function escapeXmlText(input: string): string;
+export declare function renderTrustedObjective(objective: string): string;
+export declare function goalTokenDelta(current: GoalTokenUsage, baseline: GoalTokenUsage): number;
+export declare function renderGoalPrompt(kind: GoalPromptKind, goal: Goal): string;
+export declare function completionBudgetReport(goal: Goal): string | null;
+export declare class GoalRuntime {
+    #private;
+    constructor(host: GoalRuntimeHost);
+    get snapshot(): GoalRuntimeSnapshot;
+    onTurnStart(turnId: string, baselineUsage: GoalTokenUsage): void;
+    onToolCompleted(toolName: string): Promise<void>;
+    onGoalToolCompleted(): Promise<void>;
+    onAgentEnd(options?: {
+        turnCompleted?: boolean;
+        currentUsage?: GoalTokenUsage;
+    }): Promise<void>;
+    onTaskAborted(options?: {
+        reason?: "interrupted" | "internal";
+    }): Promise<void>;
+    onThreadResumed(): Promise<GoalModeState | undefined>;
+    onBudgetMutated(newBudget: number | undefined): Promise<GoalModeState | undefined>;
+    flushUsage(steering: GoalBudgetSteering, currentUsage?: GoalTokenUsage): Promise<void>;
+    createGoal(input: {
+        objective: string;
+        tokenBudget?: number;
+    }): Promise<GoalModeState>;
+    resumeGoal(): Promise<GoalModeState>;
+    pauseGoal(): Promise<GoalModeState | undefined>;
+    dropGoal(): Promise<Goal | undefined>;
+    completeGoalFromTool(): Promise<Goal>;
+    buildActivePrompt(): string | undefined;
+    buildContinuationPrompt(): string | undefined;
+}

package/dist/types/goals/state.d.ts

@@ -0,0 +1,35 @@
+import type { UsageStatistics } from "../session/session-manager";
+export type GoalStatus = "active" | "paused" | "budget-limited" | "complete" | "dropped";
+export interface Goal {
+    id: string;
+    objective: string;
+    status: GoalStatus;
+    tokenBudget?: number;
+    tokensUsed: number;
+    timeUsedSeconds: number;
+    createdAt: number;
+    updatedAt: number;
+}
+export interface GoalModeState {
+    enabled: boolean;
+    mode: "active" | "exiting";
+    reason?: "completed";
+    goal: Goal;
+}
+export interface GoalToolDetails {
+    op: "create" | "get" | "complete";
+    goal?: Goal | null;
+    remainingTokens?: number | null;
+    completionBudgetReport?: string | null;
+}
+export type GoalRuntimeEvent = {
+    type: "goal_updated";
+    goal: Goal | null;
+    state?: GoalModeState;
+} | {
+    type: "goal_continuation_requested";
+    prompt: string;
+};
+export type GoalTokenUsage = Pick<UsageStatistics, "input" | "output" | "cacheRead" | "cacheWrite">;
+export type GoalBudgetSteering = "allowed" | "suppressed";
+export type GoalTerminalMetricEmission = "emit" | "suppress";