@mu-agent/mu 0.0.1

package/dist/types/core/extensions.d.ts

@@ -0,0 +1,97 @@
+import type { ModelInfo, Provider } from "../ai/index.js";
+import { type Command, CommandRegistry } from "./commands.js";
+import type { AgentEvent } from "./events.js";
+import type { AgentMessage } from "./messages.js";
+import type { AnyTool, ToolResult } from "./tools.js";
+export interface ToolCallDirective {
+    block?: boolean;
+    reason?: string;
+    args?: Record<string, unknown>;
+}
+export interface ToolResultDirective {
+    content?: ToolResult["content"];
+    isError?: boolean;
+}
+export interface InputDirective {
+    consume?: boolean;
+    text?: string;
+}
+export interface ToolCallHookInfo {
+    toolName: string;
+    toolCallId: string;
+    args: Record<string, unknown>;
+}
+export interface ToolResultHookInfo {
+    toolName: string;
+    toolCallId: string;
+    result: ToolResult;
+    isError: boolean;
+}
+export type LifecycleNotification = {
+    type: "session_start";
+    sessionId: string;
+} | {
+    type: "session_shutdown";
+    sessionId: string;
+} | {
+    type: "input";
+    text: string;
+} | {
+    type: "model_select";
+    model: string;
+};
+export type LifecycleEvent = LifecycleNotification["type"];
+export type ExtensionEvent = AgentEvent | LifecycleNotification;
+export type ExtensionEventType = ExtensionEvent["type"];
+export type ExtensionEventFor<T extends ExtensionEventType> = Extract<ExtensionEvent, {
+    type: T;
+}>;
+export interface ToolRenderer {
+    render: (info: {
+        toolName: string;
+        args: unknown;
+        result?: ToolResult;
+    }) => string[];
+}
+export interface ExtensionAPI {
+    on<T extends ExtensionEventType>(event: T, handler: (event: ExtensionEventFor<T>) => void): void;
+    onToolCall(handler: (info: ToolCallHookInfo) => ToolCallDirective | undefined | Promise<ToolCallDirective | undefined>): void;
+    onToolResult(handler: (info: ToolResultHookInfo) => ToolResultDirective | undefined | Promise<ToolResultDirective | undefined>): void;
+    onContext(handler: (messages: AgentMessage[]) => AgentMessage[] | Promise<AgentMessage[]>): void;
+    onInput(handler: (text: string) => InputDirective | undefined | Promise<InputDirective | undefined>): void;
+    registerTool(tool: AnyTool): void;
+    registerCommand(command: Command): void;
+    registerProvider(provider: Provider): void;
+    registerModels(models: ModelInfo[]): void;
+    registerRenderer(toolName: string, renderer: ToolRenderer): void;
+    log(message: string): void;
+}
+export interface Extension {
+    name: string;
+    activate: (api: ExtensionAPI) => void | Promise<void>;
+    deactivate?: () => void | Promise<void>;
+}
+export declare class ExtensionHost {
+    readonly tools: Map<string, AnyTool>;
+    readonly commands: CommandRegistry;
+    readonly providers: Map<string, Provider>;
+    readonly models: Map<string, ModelInfo>;
+    readonly renderers: Map<string, ToolRenderer>;
+    readonly logs: string[];
+    private extensions;
+    private eventHandlers;
+    private toolCallHooks;
+    private toolResultHooks;
+    private contextHooks;
+    private inputHooks;
+    register(extension: Extension): Promise<void>;
+    shutdown(): Promise<void>;
+    emit(event: AgentEvent): void;
+    emitLifecycle(event: LifecycleNotification): void;
+    findModel(ref: string): ModelInfo | undefined;
+    runToolCallHooks(info: ToolCallHookInfo): Promise<ToolCallDirective | undefined>;
+    runToolResultHooks(info: ToolResultHookInfo): Promise<ToolResultDirective | undefined>;
+    runContextHooks(messages: AgentMessage[]): Promise<AgentMessage[]>;
+    runInputHooks(text: string): Promise<InputDirective | undefined>;
+    get hasContextHooks(): boolean;
+}

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

@@ -0,0 +1,27 @@
+export type { CheckpointDiffFile, CheckpointEntry, CheckpointProvider, } from "./checkpoint.js";
+export { CheckpointHistory } from "./checkpoint.js";
+export type { Command, CommandContext, CommandResult } from "./commands.js";
+export { CommandRegistry } from "./commands.js";
+export type { CompactionRequest, CompactionResult, CompactorOptions, ContextState, } from "./compaction.js";
+export { AUTO_COMPACT_THRESHOLD, applyCompaction, CompactionError, compact, compactionSummaryMessage, contextState, estimateTokens, formatCarryover, planCompaction, SUMMARY_PROMPT, shouldCompact, } from "./compaction.js";
+export type { AgentEndReason, AgentEvent, AgentEventType, EventSink, StreamDelta, } from "./events.js";
+export type { Extension, ExtensionAPI, ExtensionEvent, ExtensionEventFor, ExtensionEventType, InputDirective, LifecycleEvent, LifecycleNotification, ToolCallDirective, ToolCallHookInfo, ToolRenderer, ToolResultDirective, ToolResultHookInfo, } from "./extensions.js";
+export { ExtensionHost } from "./extensions.js";
+export type { AfterToolCallInfo, AgentContext, AgentRunResult, BeforeToolCallInfo, ContextPreparation, LoopConfig, NextTurnDirective, TurnInfo, } from "./loop.js";
+export { AgentEventStream, runAgent, runLoop } from "./loop.js";
+export type { AgentMessage, CustomMessage } from "./messages.js";
+export * from "./messages.js";
+export { customMessage, isCustomMessage, renderCustomMessage, toAiMessages, userMessage, } from "./messages.js";
+export type { MicrocompactionOptions, MicrocompactionResult } from "./microcompaction.js";
+export { IMAGE_TOMBSTONE, MICROCOMPACT_THRESHOLD, microcompact, TOMBSTONE, } from "./microcompaction.js";
+export type { PermissionAction, PermissionPreview, PermissionRequest, PermissionRule, ToolPermissionDetails, } from "./permission.js";
+export { evaluate } from "./permission.js";
+export type { ManagedProcessHandle, ProcessEvents, Spawner, SpawnRequest, TaskInfo, TaskStatus, } from "./process.js";
+export { exitNotification, OutputBuffer, ProcessManager } from "./process.js";
+export type { PermissionMode, Profile, ProfileFactory, ProfileRuntime, ProfileRuntimeHost, } from "./profile.js";
+export type { RecoveryAttempt } from "./recovery.js";
+export { isContextTooLongError, isContextTooLongResult, withContextRecovery, } from "./recovery.js";
+export type { NewTreeEntry, SessionEntry, SessionStore, TreeEntry } from "./session.js";
+export { isTreeEntry, MemorySessionStore, newEntryId, parseEntry, parseSession, SESSION_VERSION, SessionTree, serializeEntry, serializeSession, } from "./session.js";
+export type { AnyTool, Tool, ToolResult } from "./tools.js";
+export { concurrencySafe, errorResult, textResult } from "./tools.js";

package/dist/types/core/loop.d.ts

@@ -0,0 +1,69 @@
+import { type AssistantMessage, EventStream, type LlmContext, type ModelInfo, type Provider, type StreamOpts, type ThinkingLevel, type ToolCallContent, type ToolResultContent, type ToolResultMessage } from "../ai/index.js";
+import type { AgentEndReason, AgentEvent, EventSink } from "./events.js";
+import type { AgentMessage } from "./messages.js";
+import { type AnyTool, type ToolResult } from "./tools.js";
+export interface AgentContext {
+    systemPrompt?: LlmContext["systemPrompt"];
+    messages: AgentMessage[];
+    tools?: AnyTool[];
+}
+export interface TurnInfo {
+    message: AssistantMessage;
+    toolResults: ToolResultMessage[];
+    context: AgentContext;
+    requestMessages: AgentMessage[];
+    newMessages: AgentMessage[];
+}
+export interface BeforeToolCallInfo {
+    assistantMessage: AssistantMessage;
+    toolCall: ToolCallContent;
+    args: Record<string, unknown>;
+    context: AgentContext;
+}
+export interface AfterToolCallInfo extends BeforeToolCallInfo {
+    result: ToolResult;
+    isError: boolean;
+}
+export interface NextTurnDirective {
+    model?: ModelInfo;
+    thinkingLevel?: ThinkingLevel;
+    context?: AgentContext;
+}
+export interface ContextPreparation {
+    messages: AgentMessage[];
+    stop?: boolean;
+}
+export interface LoopConfig {
+    provider: Provider;
+    model: ModelInfo;
+    streamOpts?: StreamOpts;
+    thinkingLevel?: ThinkingLevel;
+    maxTurns?: number;
+    getSteeringMessages?: () => AgentMessage[] | Promise<AgentMessage[]>;
+    getFollowUpMessages?: () => AgentMessage[] | Promise<AgentMessage[]>;
+    beforeToolCall?: (info: BeforeToolCallInfo, signal: AbortSignal) => {
+        block?: boolean;
+        reason?: string;
+        rewrittenArgs?: Record<string, unknown>;
+    } | undefined | Promise<{
+        block?: boolean;
+        reason?: string;
+        rewrittenArgs?: Record<string, unknown>;
+    } | undefined>;
+    afterToolCall?: (info: AfterToolCallInfo, signal: AbortSignal) => ToolResult | undefined | Promise<ToolResult | undefined>;
+    shouldStopAfterTurn?: (turn: TurnInfo) => boolean | Promise<boolean>;
+    recoverFromError?: (message: AssistantMessage) => boolean | Promise<boolean>;
+    prepareNextTurn?: (turn: TurnInfo) => NextTurnDirective | undefined | Promise<NextTurnDirective | undefined>;
+    prepareContext?: (messages: AgentMessage[]) => ContextPreparation | AgentMessage[] | Promise<ContextPreparation | AgentMessage[]>;
+    transformContext?: (messages: AgentMessage[]) => AgentMessage[] | Promise<AgentMessage[]>;
+}
+export interface AgentRunResult {
+    messages: AgentMessage[];
+    reason: AgentEndReason;
+}
+export declare class AgentEventStream extends EventStream<AgentEvent, AgentRunResult> {
+    constructor();
+}
+export declare function runAgent(prompts: AgentMessage[], context: AgentContext, config: LoopConfig, signal?: AbortSignal): AgentEventStream;
+export declare function runLoop(prompts: AgentMessage[], context: AgentContext, config: LoopConfig, emit: EventSink, signal?: AbortSignal): Promise<AgentRunResult>;
+export type { ToolResultContent };

package/dist/types/core/messages.d.ts

@@ -0,0 +1,15 @@
+import type { AiMessage, AssistantMessage, ImageContent, TextContent, ToolResultMessage, UserMessage } from "../ai/index.js";
+export type { AssistantContent, AssistantMessage, ImageContent, StopReason, TextContent, ThinkingContent, ToolCallContent, ToolResultContent, ToolResultMessage, Usage, UserContent, UserMessage, } from "../ai/index.js";
+export interface CustomMessage {
+    role: "custom";
+    customType: string;
+    content: (TextContent | ImageContent)[];
+    display?: boolean;
+    timestamp: number;
+}
+export type AgentMessage = UserMessage | AssistantMessage | ToolResultMessage | CustomMessage;
+export declare function isCustomMessage(message: AgentMessage): message is CustomMessage;
+export declare function renderCustomMessage(message: CustomMessage): UserMessage;
+export declare function toAiMessages(messages: AgentMessage[]): AiMessage[];
+export declare function userMessage(text: string): UserMessage;
+export declare function customMessage(customType: string, text: string, display?: boolean): CustomMessage;

package/dist/types/core/microcompaction.d.ts

@@ -0,0 +1,14 @@
+import type { AgentMessage } from "./messages.js";
+export declare const TOMBSTONE = "[output cleared to save context \u2014 re-run the tool if you need it]";
+export declare const IMAGE_TOMBSTONE = "[image cleared to save context]";
+export interface MicrocompactionOptions {
+    keepRecent?: number;
+    targetTokens?: number;
+}
+export interface MicrocompactionResult {
+    messages: AgentMessage[];
+    evicted: number;
+    tokensFreed: number;
+}
+export declare function microcompact(messages: AgentMessage[], options?: MicrocompactionOptions): MicrocompactionResult;
+export declare const MICROCOMPACT_THRESHOLD = 0.6;

package/dist/types/core/permission.d.ts

@@ -0,0 +1,27 @@
+import type { CheckpointDiffFile } from "./checkpoint.js";
+export type PermissionAction = "allow" | "ask" | "deny";
+export interface PermissionRule {
+    permission: string;
+    pattern: string;
+    action: PermissionAction;
+}
+export interface PermissionRequest {
+    id: string;
+    toolCallId: string;
+    toolName: string;
+    pattern: string;
+    description: string;
+    preview?: PermissionPreview;
+}
+export type PermissionPreview = {
+    kind: "text";
+    lines: string[];
+} | {
+    kind: "diff";
+    file: CheckpointDiffFile;
+};
+export interface ToolPermissionDetails {
+    description?: string;
+    preview?: PermissionPreview;
+}
+export declare function evaluate(rules: PermissionRule[], permission: string, pattern: string): PermissionAction;

package/dist/types/core/process.d.ts

@@ -0,0 +1,79 @@
+export interface ManagedProcessHandle {
+    write: (data: string) => void;
+    resize: (cols: number, rows: number) => void;
+    detach: () => void;
+    kill: () => void;
+    exited: Promise<number | null>;
+}
+export interface SpawnRequest {
+    command: string;
+    onOutput: (chunk: string) => void;
+    cols: number;
+    rows: number;
+}
+export type Spawner = (request: SpawnRequest) => ManagedProcessHandle;
+export type TaskStatus = "running" | "exited" | "killed";
+export interface TaskInfo {
+    id: string;
+    command: string;
+    status: TaskStatus;
+    exitCode: number | null;
+    startedAt: number;
+    endedAt?: number;
+    outputBytes: number;
+    truncated: boolean;
+    detached: boolean;
+}
+export declare class OutputBuffer {
+    private headLimit;
+    private tailLimit;
+    private head;
+    private tail;
+    private headComplete;
+    private total;
+    constructor(headLimit?: number, tailLimit?: number);
+    append(chunk: string): void;
+    get bytes(): number;
+    get truncated(): boolean;
+    read(): string;
+    readSince(position: number): {
+        text: string;
+        offset: number;
+        gap: boolean;
+    };
+    private get droppedBytes();
+}
+export interface ProcessEvents {
+    onStarted?: (task: TaskInfo) => void;
+    onOutput?: (taskId: string, chunk: string) => void;
+    onExited?: (task: TaskInfo) => void;
+}
+export declare class ProcessManager {
+    private spawn;
+    private events;
+    private tasks;
+    private counter;
+    constructor(spawn: Spawner, events?: ProcessEvents);
+    setEvents(events: ProcessEvents): void;
+    start(command: string, size?: {
+        cols?: number;
+        rows?: number;
+    }): TaskInfo;
+    get(id: string): TaskInfo | undefined;
+    list(): TaskInfo[];
+    get runningCount(): number;
+    output(id: string, since?: "start" | "new"): {
+        text: string;
+        truncated: boolean;
+    } | undefined;
+    writeStdin(id: string, data: string): boolean;
+    resize(id: string, cols: number, rows: number): boolean;
+    resizeAll(cols: number, rows: number): void;
+    detach(id: string): boolean;
+    kill(id: string): boolean;
+    stopAll(): void;
+    killAll(): Promise<void>;
+    private requestStops;
+    wait(id: string): Promise<TaskInfo | undefined>;
+}
+export declare function exitNotification(task: TaskInfo): string;

package/dist/types/core/profile.d.ts

@@ -0,0 +1,46 @@
+import type { PromptSection } from "../ai/index.js";
+import type { CheckpointProvider } from "./checkpoint.js";
+import type { Command } from "./commands.js";
+import type { AgentEvent } from "./events.js";
+import type { ToolRenderer } from "./extensions.js";
+import type { AgentMessage } from "./messages.js";
+import type { PermissionRule } from "./permission.js";
+import type { AnyTool } from "./tools.js";
+export interface PermissionMode {
+    id: string;
+    label: string;
+    description: string;
+    rules: PermissionRule[];
+}
+export interface ProfileRuntimeHost {
+    emit: (event: AgentEvent) => void;
+    followUp: (message: string) => void;
+}
+export interface ProfileRuntime {
+    attach: (host: ProfileRuntimeHost) => void;
+    resize?: (cols: number, rows: number) => void;
+    stop?: () => void;
+    shutdown?: () => void | Promise<void>;
+}
+export interface Profile {
+    name: string;
+    toolset: AnyTool[];
+    promptFor: (modelRef: string) => PromptSection[];
+    permissionDefaults: PermissionRule[];
+    permissionModes?: PermissionMode[];
+    defaultPermissionMode?: string;
+    rememberPermission?: (permission: string, pattern: string) => void | Promise<void>;
+    renderers?: Record<string, ToolRenderer>;
+    commands?: Command[];
+    environment?: () => Promise<Record<string, string>> | Record<string, string>;
+    contextMessages?: () => Promise<AgentMessage[]> | AgentMessage[];
+    refreshContext?: (messages: AgentMessage[], context: {
+        sessionId: string;
+    }) => Promise<AgentMessage[]> | AgentMessage[];
+    diagnostics?: string[];
+    carryoverExtractor?: (messages: AgentMessage[]) => unknown;
+    checkpointProvider?: CheckpointProvider;
+    runtime?: ProfileRuntime;
+    scope?: () => Promise<string> | string;
+}
+export type ProfileFactory = (options?: Record<string, unknown>) => Profile | Promise<Profile>;

package/dist/types/core/recovery.d.ts

@@ -0,0 +1,14 @@
+export declare function isContextTooLongError(error: unknown): boolean;
+export declare function isContextTooLongResult(result: {
+    stopReason: string;
+    errorMessage?: string | undefined;
+}): boolean;
+export interface RecoveryAttempt<T> {
+    run: () => Promise<T>;
+    recover: () => Promise<void>;
+    isRecoverable: (value: T) => boolean;
+}
+export declare function withContextRecovery<T>(attempt: RecoveryAttempt<T>): Promise<{
+    value: T;
+    recovered: boolean;
+}>;

package/dist/types/core/session.d.ts

@@ -0,0 +1,103 @@
+import type { AgentMessage } from "./messages.js";
+export declare const SESSION_VERSION = 1;
+export type SessionEntry = {
+    type: "session";
+    version: number;
+    id: string;
+    createdAt: string;
+    profile: string;
+    environment: Record<string, string>;
+} | {
+    type: "message";
+    id: string;
+    parentId: string | null;
+    message: AgentMessage;
+    checkpointRef?: string;
+} | {
+    type: "compaction";
+    id: string;
+    parentId: string | null;
+    summary: string;
+    carryover?: unknown;
+    firstKeptEntryId: string | null;
+    timestamp?: number;
+} | {
+    type: "microcompaction";
+    id: string;
+    parentId: string | null;
+    replacements: {
+        entryId: string;
+        message: AgentMessage;
+    }[];
+} | {
+    type: "checkpoint";
+    id: string;
+    parentId: string | null;
+    beforeEntryId: string | null;
+    checkpointRef: string;
+    checkpointAfterRef: string;
+    label?: string;
+} | {
+    type: "settings-change";
+    id: string;
+    parentId: string | null;
+    model?: string;
+    thinkingLevel?: string;
+} | {
+    type: "custom";
+    id: string;
+    parentId: string | null;
+    customType: string;
+    data: unknown;
+};
+export type TreeEntry = Exclude<SessionEntry, {
+    type: "session";
+}>;
+type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
+export type NewTreeEntry = DistributiveOmit<TreeEntry, "id" | "parentId"> & {
+    id?: string;
+    parentId?: string | null;
+};
+export declare function isTreeEntry(entry: SessionEntry): entry is TreeEntry;
+export declare function serializeEntry(entry: SessionEntry): string;
+export declare function parseEntry(line: string): SessionEntry;
+export declare function serializeSession(entries: SessionEntry[]): string;
+export declare function parseSession(jsonl: string): SessionEntry[];
+export declare function newEntryId(): string;
+export declare class SessionTree {
+    private entries;
+    private byId;
+    private headId;
+    constructor(header?: SessionEntry & {
+        type: "session";
+    });
+    static fromJsonl(jsonl: string): SessionTree;
+    toJsonl(): string;
+    get header(): (SessionEntry & {
+        type: "session";
+    }) | undefined;
+    get head(): string | null;
+    all(): SessionEntry[];
+    get(id: string): TreeEntry | undefined;
+    has(id: string | null): boolean;
+    push(entry: SessionEntry): void;
+    append(entry: NewTreeEntry): TreeEntry;
+    appendMessage(message: AgentMessage, checkpointRef?: string): TreeEntry;
+    pathTo(id: string): TreeEntry[];
+    activePath(): TreeEntry[];
+    entryIdForMessage(message: AgentMessage): string | undefined;
+    messagesAt(id?: string | null): AgentMessage[];
+    fork(entryId: string | null): void;
+}
+export interface SessionStore {
+    load(sessionId: string): Promise<SessionTree | undefined>;
+    save(sessionId: string, tree: SessionTree): Promise<void>;
+    list(): Promise<string[]>;
+}
+export declare class MemorySessionStore implements SessionStore {
+    private sessions;
+    load(sessionId: string): Promise<SessionTree | undefined>;
+    save(sessionId: string, tree: SessionTree): Promise<void>;
+    list(): Promise<string[]>;
+}
+export {};

package/dist/types/core/testing/fake-provider.d.ts

@@ -0,0 +1,19 @@
+import { type AssistantContent, AssistantStream, type LlmContext, type ModelInfo, type Provider, type StopReason, type StreamOpts, type Usage } from "../../ai/index.js";
+export interface ScriptedTurn {
+    content: AssistantContent[];
+    stopReason?: StopReason;
+    errorMessage?: string;
+    usage?: Partial<Usage>;
+    delayMs?: number;
+}
+export declare const fakeModel: ModelInfo;
+export declare class FakeProvider implements Provider {
+    private turns;
+    readonly id = "fake";
+    readonly requests: LlmContext[];
+    readonly streamOptions: (StreamOpts | undefined)[];
+    private index;
+    constructor(turns: ScriptedTurn[]);
+    get callCount(): number;
+    stream(model: ModelInfo, ctx: LlmContext, opts?: StreamOpts): AssistantStream;
+}

package/dist/types/core/tools.d.ts

@@ -0,0 +1,22 @@
+import type { ToolResultContent } from "../ai/index.js";
+import type { ToolPermissionDetails } from "./permission.js";
+export interface ToolResult {
+    content: ToolResultContent[];
+    details?: unknown;
+    isError?: boolean;
+    terminate?: boolean;
+}
+export interface Tool<Args = Record<string, unknown>> {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    isConcurrencySafe?: (args: Args) => boolean;
+    executionMode?: "sequential";
+    changesState?: boolean | ((args: Args) => boolean);
+    permissionDetails?: (args: Args) => ToolPermissionDetails | undefined | Promise<ToolPermissionDetails | undefined>;
+    execute: (toolCallId: string, args: Args, signal: AbortSignal, onUpdate?: (partial: ToolResultContent[]) => void) => Promise<ToolResult>;
+}
+export type AnyTool = Tool<any>;
+export declare function errorResult(message: string): ToolResult;
+export declare function textResult(text: string): ToolResult;
+export declare function concurrencySafe(tool: AnyTool, args: unknown): boolean;

package/dist/types/index.d.ts

@@ -0,0 +1,10 @@
+import { type CodingProfile, type CodingProfileOptions, codingProfile } from "./profile-coding/index.js";
+import { Agent, type AgentOptions, type Profile } from "./sdk/index.js";
+export * from "./sdk/index.js";
+export { codingProfile };
+export type { CodingProfile, CodingProfileOptions };
+export interface CreateAgentOptions extends AgentOptions {
+    profile?: "coding" | Profile;
+    profileOptions?: CodingProfileOptions;
+}
+export declare function createAgent(options?: CreateAgentOptions): Promise<Agent>;

package/dist/types/profile-coding/checkpoint.d.ts

@@ -0,0 +1,29 @@
+import type { CheckpointDiffFile, CheckpointProvider } from "../core/index.js";
+export interface ShadowCheckpointOptions {
+    root: string;
+    shadowDir?: string;
+    scope?: string;
+    run?: GitRunner;
+}
+export type GitRunner = (args: string[], env: Record<string, string>, cwd: string) => Promise<{
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}>;
+export declare function gitConfigNullDevice(platform?: NodeJS.Platform): string;
+export declare class ShadowCheckpointProvider implements CheckpointProvider {
+    private readonly root;
+    private readonly shadowDir;
+    private readonly run;
+    private readonly excludedPathspecs;
+    private initialized;
+    constructor(options: ShadowCheckpointOptions);
+    get directory(): string;
+    private env;
+    private git;
+    private ensure;
+    snapshot(label?: string): Promise<string | undefined>;
+    restore(ref: string): Promise<void>;
+    restoreResources(ref: string, resources: string[]): Promise<void>;
+    diff(fromRef: string, toRef?: string): Promise<CheckpointDiffFile[]>;
+}

package/dist/types/profile-coding/context.d.ts

@@ -0,0 +1,76 @@
+import { type AgentMessage } from "../core/index.js";
+export declare const DEFAULT_INSTRUCTION_MAX_BYTES: number;
+export declare const DEFAULT_PROJECT_ROOT_MARKERS: string[];
+export declare const DEFAULT_INSTRUCTION_FALLBACKS: string[];
+export declare const INSTRUCTION_PRIMARY_NAMES: string[];
+export interface InstructionSettings {
+    enabled?: boolean;
+    maxBytes?: number;
+    fallbackFilenames?: string[];
+    projectRootMarkers?: string[];
+    imports?: boolean;
+    claudeRules?: boolean;
+}
+export interface InstructionLoaderOptions extends InstructionSettings {
+    root: string;
+    home?: string;
+    managedPaths?: string[];
+}
+export type InstructionScope = "managed" | "global" | "project" | "local" | "rule" | "import";
+export interface InstructionSource {
+    path: string;
+    content: string;
+    scope: InstructionScope;
+    parent?: string;
+    truncated?: boolean;
+}
+export interface InstructionDiagnostic {
+    level: "warning";
+    path?: string;
+    message: string;
+}
+export interface InstructionSnapshot {
+    enabled: boolean;
+    projectRoot: string;
+    sources: InstructionSource[];
+    diagnostics: InstructionDiagnostic[];
+    bytes: number;
+    maxBytes: number;
+    truncated: boolean;
+    signature: string;
+}
+export declare class InstructionLoader {
+    readonly root: string;
+    readonly home: string;
+    readonly settings: Required<InstructionSettings>;
+    private readonly managedPaths;
+    private readonly settingDiagnostics;
+    private current;
+    private nestedSources;
+    private nestedSerial;
+    private activeSessionId;
+    constructor(options: InstructionLoaderOptions);
+    get snapshot(): InstructionSnapshot;
+    reload(options?: {
+        resetNested?: boolean;
+    }): Promise<InstructionSnapshot>;
+    refreshedMessages(existing: AgentMessage[], sessionId?: string): Promise<AgentMessage[]>;
+    instructionsForPath(targetPath: string): Promise<{
+        text: string;
+        sources: string[];
+    }>;
+    formatStatus(prefix?: string): string;
+    discoverPrimaryFiles(stopAt?: string): Promise<string[]>;
+    private findProjectRoot;
+    private dirsBetween;
+    private primaryForDirectory;
+    private firstReadableCandidate;
+    private ruleFiles;
+    private rulesForDirectory;
+    private loadSource;
+    private loadNested;
+}
+export declare function discoverContextFiles(root: string, stopAt?: string): Promise<string[]>;
+export declare function contextMessages(root: string): Promise<AgentMessage[]>;
+export declare function codingEnvironment(root: string): Promise<Record<string, string>>;
+export declare function environmentMessage(env: Record<string, string>): AgentMessage;