@zpi-dev/agent-sdk 0.0.0-stage → 0.1.60

package/dist/types/coding-agent/src/core/commands.d.ts

@@ -0,0 +1,19 @@
+export declare const localCommands: readonly [{
+    readonly name: "compact";
+    readonly description: "摘要旧对话，保留完整历史";
+}];
+export declare function listCommands(commands?: readonly {
+    name: string;
+    description: string;
+}[]): {
+    name: string;
+    description: string;
+}[];
+export type ParsedInput = {
+    kind: "prompt";
+    text: string;
+} | {
+    kind: "compact";
+    args: string;
+};
+export declare function parseInput(text: string): ParsedInput;

package/dist/types/coding-agent/src/core/compaction-utils.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Shared utilities for compaction and branch summarization.
+ */
+import type { Message as AgentMessage } from "../../../ai/src/index.js";
+import { type Message } from "../../../ai/src/index.js";
+export interface FileOperations {
+    read: Set<string>;
+    written: Set<string>;
+    edited: Set<string>;
+}
+export declare function createFileOps(): FileOperations;
+/**
+ * Extract file operations from tool calls in an assistant message.
+ */
+export declare function extractFileOpsFromMessage(message: AgentMessage, fileOps: FileOperations): void;
+/**
+ * Compute final file lists from file operations.
+ * Returns readFiles (files only read, not modified) and modifiedFiles.
+ */
+export declare function computeFileLists(fileOps: FileOperations): {
+    readFiles: string[];
+    modifiedFiles: string[];
+};
+/**
+ * Format file operations as XML tags for summary.
+ */
+export declare function formatFileOperations(readFiles: string[], modifiedFiles: string[]): string;
+/**
+ * Serialize LLM messages to text for summarization.
+ * This prevents the model from treating it as a conversation to continue.
+ * Call convertToLlm() first to handle custom message types.
+ *
+ * Tool results are truncated to keep the summarization request within
+ * reasonable token budgets. Full content is not needed for summarization.
+ */
+export declare function serializeConversation(messages: Message[]): string;
+export declare const SUMMARIZATION_SYSTEM_PROMPT = "You are a context summarization assistant. Your task is to read a conversation between a user and an AI assistant, then produce a structured summary following the exact format specified.\n\nDo NOT continue the conversation. Do NOT respond to any questions in the conversation. ONLY output the structured summary.";

package/dist/types/coding-agent/src/core/compaction.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Context compaction for long sessions.
+ *
+ * Pure functions for compaction logic. The session manager handles I/O,
+ * and after compaction the session is reloaded.
+ */
+import type { AgentMessage, StreamFn, ThinkingLevel } from "../../../agent/src/index.js";
+import type { AssistantMessage, Model, SimpleStreamOptions, TranscriptContext, Usage } from "../../../ai/src/index.js";
+import { calculateContextTokens, type RetryCallbacks, type RetryPolicy } from "../../../ai/src/index.js";
+import { type FileOperations } from "./compaction-utils.js";
+import { type SessionEntry } from "./session-manager.js";
+/** Details stored in CompactionEntry.details for file tracking */
+export interface CompactionDetails {
+    readFiles: string[];
+    modifiedFiles: string[];
+}
+/** Result from compact() - SessionManager adds uuid/parentUuid when saving */
+export interface CompactionResult<T = unknown> {
+    summary: string;
+    firstKeptEntryId: string;
+    tokensBefore: number;
+    estimatedTokensAfter?: number;
+    /** Usage from the LLM call(s) that generated this summary, if available */
+    usage?: Usage;
+    /** Extension-specific data (e.g., ArtifactIndex, version markers for structured compaction) */
+    details?: T;
+}
+export interface CompactionSettings {
+    enabled: boolean;
+    reserveTokens: number;
+    keepRecentTokens: number;
+}
+export declare const DEFAULT_COMPACTION_SETTINGS: CompactionSettings;
+export { calculateContextTokens };
+export interface ContextUsageEstimate {
+    tokens: number;
+    usageTokens: number;
+    trailingTokens: number;
+    lastUsageIndex: number | null;
+}
+/**
+ * Estimate context tokens from messages, using the last assistant usage when available.
+ * If there are messages after the last usage, estimate their tokens with estimateTokens.
+ */
+export declare function estimateContextTokens(messages: AgentMessage[]): ContextUsageEstimate;
+/**
+ * Check if compaction should trigger based on context usage.
+ */
+export declare function shouldCompact(contextTokens: number, contextWindow: number, settings: CompactionSettings): boolean;
+/**
+ * Estimate token count for a message using chars/4 heuristic.
+ * This is conservative (overestimates tokens).
+ */
+export declare function estimateTokens(message: AgentMessage): number;
+/**
+ * Find the context-visible user-role message that starts the turn containing the given entry index.
+ * Returns -1 if no turn start found before the index.
+ */
+export declare function findTurnStartIndex(entries: SessionEntry[], entryIndex: number, startIndex: number): number;
+export interface CutPointResult {
+    /** Index of first entry to keep */
+    firstKeptEntryIndex: number;
+    /** Index of user message that starts the turn being split, or -1 if not splitting */
+    turnStartIndex: number;
+    /** Whether this cut splits a turn (cut point is not a user message) */
+    isSplitTurn: boolean;
+}
+/**
+ * Find the cut point in session entries that keeps approximately `keepRecentTokens`.
+ *
+ * Algorithm: Walk backwards from newest, accumulating estimated message sizes.
+ * Stop when we've accumulated >= keepRecentTokens. Cut at that point.
+ *
+ * Can cut at user OR assistant messages (never tool results). When cutting at an
+ * assistant message with tool calls, its tool results come after and will be kept.
+ *
+ * Returns CutPointResult with:
+ * - firstKeptEntryIndex: the entry index to start keeping from
+ * - turnStartIndex: if cutting mid-turn, the user message that started that turn
+ * - isSplitTurn: whether we're cutting in the middle of a turn
+ *
+ * Only considers entries between `startIndex` and `endIndex` (exclusive).
+ */
+export declare function findCutPoint(entries: SessionEntry[], startIndex: number, endIndex: number, keepRecentTokens: number, forceProgress?: boolean): CutPointResult;
+/**
+ * Returns an error message when a summarization response cannot safely be persisted.
+ * A length stop contains partial text and must not become a session checkpoint.
+ */
+export declare function getSummarizationFailure(response: AssistantMessage, label: string): string | undefined;
+/**
+ * Shared choke point for every compaction/branch-summary summarization call. Wraps the
+ * single LLM call in {@link retryAssistantCall} so transient stream drops (e.g.
+ * `terminated`, socket close) honor the configured retry policy instead of failing
+ * the whole compaction on the first attempt. Deterministic errors and aborts return
+ * immediately (see {@link retryAssistantCall}).
+ */
+export declare function completeSummarization(model: Model, context: TranscriptContext, options: SimpleStreamOptions, streamFn?: StreamFn, retry?: RetryPolicy, callbacks?: RetryCallbacks): Promise<AssistantMessage>;
+/** Generate or update a conversation summary and return its provider usage. */
+export declare function generateSummaryWithUsage(currentMessages: AgentMessage[], model: Model, reserveTokens: number, apiKey: string | undefined, headers?: Record<string, string>, signal?: AbortSignal, customInstructions?: string, previousSummary?: string, thinkingLevel?: ThinkingLevel, streamFn?: StreamFn, retry?: RetryPolicy, callbacks?: RetryCallbacks, sessionId?: string, onMediaProjection?: SimpleStreamOptions["onMediaProjection"]): Promise<{
+    text: string;
+    usage: Usage;
+}>;
+export interface CompactionPreparation {
+    /** UUID of first entry to keep */
+    firstKeptEntryId: string;
+    /** Messages that will be summarized and discarded */
+    messagesToSummarize: AgentMessage[];
+    /** Messages that will be turned into turn prefix summary (if splitting) */
+    turnPrefixMessages: AgentMessage[];
+    /** Whether this is a split turn (cut point in middle of turn) */
+    isSplitTurn: boolean;
+    tokensBefore: number;
+    /** Summary from previous compaction, for iterative update */
+    previousSummary?: string;
+    /** File operations extracted from messagesToSummarize */
+    fileOps: FileOperations;
+    /** Compaction settions from settings.jsonl	*/
+    settings: CompactionSettings;
+}
+export declare function prepareCompaction(pathEntries: SessionEntry[], settings: CompactionSettings): CompactionPreparation | undefined;
+/**
+ * Generate summaries for compaction using prepared data.
+ * Returns CompactionResult - SessionManager adds uuid/parentUuid when saving.
+ *
+ * @param preparation - Pre-calculated preparation from prepareCompaction()
+ * @param customInstructions - Optional custom focus for the summary
+ * @param sessionId - Optional routing session ID forwarded without enabling prompt caching
+ */
+export declare function compact(preparation: CompactionPreparation, model: Model, apiKey: string | undefined, headers?: Record<string, string>, customInstructions?: string, signal?: AbortSignal, thinkingLevel?: ThinkingLevel, streamFn?: StreamFn, retry?: RetryPolicy, callbacks?: RetryCallbacks, sessionId?: string, onMediaProjection?: SimpleStreamOptions["onMediaProjection"]): Promise<CompactionResult>;
+export interface CompactionOptions {
+    microcompact?: import("./microcompact.js").MicrocompactConfig;
+    enabled?: boolean;
+    reserveTokens?: number;
+    keepRecentTokens?: number;
+    modelOverrides?: Record<string, {
+        reserveTokens?: number;
+        keepRecentTokens?: number;
+    }>;
+}

package/dist/types/coding-agent/src/core/file-rewind.d.ts

@@ -0,0 +1,24 @@
+import type { FileChange } from "./tools/file-change.js";
+export interface FileRewindConflict {
+    path: string;
+    reason: string;
+}
+export interface FileRewindOptions {
+    checkPath?(path: string): void | Promise<void>;
+    readCheckpoint?(path: string): Promise<Buffer>;
+}
+interface RestoreFile {
+    path: string;
+    before: Buffer | null;
+    current: Buffer;
+    mode: number;
+}
+export interface FileRewindPlan {
+    files: RestoreFile[];
+    conflicts: FileRewindConflict[];
+}
+/** Preflight every checkpoint before touching any workspace file or conversation entry. */
+export declare function planFileRewind(changes: readonly FileChange[], options?: FileRewindOptions): Promise<FileRewindPlan>;
+/** Keep workspace and transcript together; roll workspace back if the transcript cannot commit. */
+export declare function applyFileRewind(plan: FileRewindPlan, commit: () => void | Promise<void>): Promise<FileRewindConflict[]>;
+export {};

package/dist/types/coding-agent/src/core/fs.d.ts

@@ -0,0 +1 @@
+export declare function syncDirectory(path: string): void;

package/dist/types/coding-agent/src/core/http-idle-timeout.d.ts

@@ -0,0 +1,2 @@
+/** Pi's header/body idle timeout, adapted for both Node fetch and Electron net.fetch. */
+export declare function withHttpIdleTimeout(requestFetch: typeof fetch, timeoutMs: number): typeof fetch;

package/dist/types/coding-agent/src/core/image-limits.d.ts

@@ -0,0 +1,19 @@
+export declare const READ_MAX_OUTPUT_TOKENS = 25000;
+export declare const READ_IMAGE_MAX_BASE64_BYTES: number;
+export declare const READ_IMAGE_TARGET_BYTES: number;
+export declare const READ_IMAGE_MAX_DIMENSION = 2000;
+export declare const READ_IMAGE_MAX_INPUT_BYTES: number;
+export declare const READ_IMAGE_TOKEN_TO_BASE64_CHAR_RATIO = 0.125;
+export declare const READ_IMAGE_EFFECTIVE_BASE64_BYTES: number;
+export declare const imageLimits: {
+    /** Imported and cached attachment originals. */
+    readonly sourceBytes: number;
+    /** Local/remote read-tool image inputs; attachments retain their stricter import cap. */
+    readonly readSourceBytes: number;
+    readonly count: 8;
+    readonly pixels: 40000000;
+    readonly messagePixels: 80000000;
+};
+import type { Attachment, ImageAttachment } from "../../../ai/src/index.js";
+export type { Attachment, FileAttachment, ImageAttachment } from "../../../ai/src/index.js";
+export declare function isImageAttachment(attachment: Attachment): attachment is ImageAttachment;

package/dist/types/coding-agent/src/core/images.d.ts

@@ -0,0 +1,18 @@
+import type { ImageContent } from "../../../ai/src/index.js";
+export { processImage as prepareInlineImage } from "./tools/pi/utils/image-process.js";
+export { imageFormat } from "./tools/pi/utils/image-source.js";
+/** Validate source bytes without creating a base64 copy for cache/import metadata. */
+export declare function validateImageSource(bytes: Uint8Array): Promise<{
+    mimeType: string;
+    width: number;
+    height: number;
+    warning?: string | undefined;
+}>;
+/** Validate and retain the source for previews. Use prepareInlineImage before sending to a model. */
+export declare function processImage(bytes: Uint8Array): Promise<{
+    bytes: Buffer;
+    image: ImageContent;
+    width: number;
+    height: number;
+    warning?: string;
+}>;

package/dist/types/coding-agent/src/core/input.d.ts

@@ -0,0 +1,3 @@
+export * from "./image-limits.js";
+export * from "./markdown-code.js";
+export * from "./mentions.js";

package/dist/types/coding-agent/src/core/markdown-code.d.ts

@@ -0,0 +1,7 @@
+export interface MarkdownFence {
+    marker: string;
+    length: number;
+}
+/** Return a valid opening or closing fence for the current Markdown code block. */
+export declare function markdownFence(line: string, active: MarkdownFence | null): MarkdownFence | null;
+export declare function codeRanges(content: string, includeInline?: boolean): Array<[number, number]>;

package/dist/types/coding-agent/src/core/markdown.d.ts

@@ -0,0 +1,13 @@
+import { type JsonObject } from "../../../ai/src/index.js";
+export interface MarkdownFrontmatter {
+    fields: JsonObject;
+    body: string;
+    bodyOffset: number;
+}
+/** Match closed fences without parsing YAML, including during bounded metadata discovery. */
+export declare function matchMarkdownFrontmatter(text: string): {
+    yaml: string;
+    bodyOffset: number;
+} | undefined;
+/** Syntax only: callers own required fields and whether frontmatter is mandatory. */
+export declare function parseMarkdownFrontmatter(text: string): MarkdownFrontmatter | undefined;

package/dist/types/coding-agent/src/core/mentions.d.ts

@@ -0,0 +1,12 @@
+export interface Mention {
+    kind: "file" | "skill" | "session";
+    label: string;
+    path: string;
+    start: number;
+    end: number;
+    markdown: string;
+}
+export declare function buildMentionMarkdown(label: string, path: string): string;
+export declare function buildSessionMentionMarkdown(sessionId: string, label?: string): string;
+export declare function extractSessionReferences(text: string): string[];
+export declare function parseMentions(text: string): Mention[];

package/dist/types/coding-agent/src/core/microcompact.d.ts

@@ -0,0 +1,40 @@
+import { type Message } from "../../../ai/src/index.js";
+export declare const MICROCOMPACT_CLEARED_TOOL_RESULT_MESSAGE = "[Old tool result content cleared]";
+export declare const DEFAULT_MICROCOMPACT_KEEP_RECENT_TOOL_RESULTS = 5;
+export declare const DEFAULT_MICROCOMPACT_IDLE_THRESHOLD_MINUTES = 60;
+export declare const DEFAULT_MICROCOMPACT_MIN_TOKEN_SAVINGS = 256;
+export declare const DEFAULT_MICROCOMPACT_COMPACTABLE_TOOLS: readonly ["Read", "Bash", "Grep", "Glob", "WebFetch", "WebSearch", "Edit", "Write", "ApplyPatch"];
+export interface MicrocompactConfig {
+    enabled?: boolean;
+    thresholdTokens?: number;
+    idleThresholdMinutes?: number;
+    keepRecentToolResults?: number;
+    compactableToolNames?: readonly string[];
+    clearErrorResults?: boolean;
+    minTokenSavings?: number;
+}
+export interface MicrocompactBoundary {
+    trigger: "time_based" | "token_pressure";
+    strategy: "local_tool_result_clear";
+    preMicrocompactTokenCount: number;
+    postMicrocompactTokenCount: number;
+    tokensSaved: number;
+    clearedMessageCount: number;
+    clearedToolCallIds: string[];
+    keptToolCallIds: string[];
+}
+export declare function buildDefaultMicrocompactThreshold(autoCompactThreshold: number): number;
+export declare function applyMicrocompactBoundary(messages: Message[], clearedToolCallIds: readonly string[]): Message[];
+export declare function maybeMicrocompact(input: {
+    messages: Message[];
+    config?: MicrocompactConfig;
+    lastAssistantCompletedAtMs?: number;
+    nowMs?: number;
+}): {
+    messages: Message[];
+    boundary?: MicrocompactBoundary;
+};
+export declare function microcompactClearedIds(entry: {
+    type: string;
+    data?: unknown;
+}): string[];

package/dist/types/coding-agent/src/core/model-performance.d.ts

@@ -0,0 +1,57 @@
+import type { AssistantMessage, ModelPerformanceSample } from "../../../ai/src/index.js";
+export interface ModelPerformance {
+    turns?: number;
+    steps?: number;
+    llmMs?: number;
+    toolMs?: number;
+    ttftMs?: number;
+    tokensPerSecond?: number;
+    inputTokens?: number;
+    outputTokens?: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+    cacheHitRate?: number;
+}
+/** Constant-size, committed task totals. No prompts or generated content are retained. */
+export declare const emptyPerformanceTotals: () => {
+    turns: number;
+    steps: number;
+    llmMs: number;
+    toolMs: number;
+    ttftMs: number;
+    ttftCount: number;
+    decodeMs: number;
+    decodeTokens: number;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    usageCount: number;
+    cacheCount: number;
+};
+export type ModelPerformanceTotals = ReturnType<typeof emptyPerformanceTotals> & {
+    turnsKnown?: false;
+};
+export declare function validPerformanceTotals(value: unknown): value is ModelPerformanceTotals;
+export declare function modelPerformance(t: ModelPerformanceTotals): ModelPerformance;
+/** Like the Harness dock, publish settled requests; keep prior readings while streaming. */
+export declare class SessionPerformance {
+    private totals;
+    private epoch;
+    private countedTurn;
+    private tools;
+    private changed;
+    constructor(changed: (value: ModelPerformance, totals: ModelPerformanceTotals) => void, initial?: ModelPerformanceTotals);
+    get value(): ModelPerformance;
+    get snapshot(): ModelPerformanceTotals;
+    begin(): void;
+    request(): {
+        update: (next: ModelPerformanceSample) => void;
+        finish: (success: boolean, message?: Pick<AssistantMessage, "usage" | "usageAvailable" | "cacheUsageAvailable">) => void;
+    };
+    toolStart(id: string): void;
+    toolEnd(id: string): void;
+    settle(): void;
+    dispose(): void;
+    private publish;
+}

package/dist/types/coding-agent/src/core/model-runtime.d.ts

@@ -0,0 +1,51 @@
+import type { Api, AssistantMessageEventStream, Context, MediaBudgetStats, Model, ResponsesSessionDiagnostic, ResponsesSessionOptions, SimpleStreamOptions, TranscriptContext } from "../../../ai/src/index.js";
+export interface ProviderChatModelConfig extends Omit<Model, "provider" | "api" | "baseUrl"> {
+    type?: "chat";
+    api?: Api;
+}
+export interface ProviderConfigInput {
+    name?: string;
+    baseUrl?: string;
+    api?: Api;
+    apiKey?: string;
+    /** A rejected key requests one credential recovery; other callers resolve normally. */
+    getApiKey?: (rejectedApiKey?: string) => Promise<string>;
+    headers?: Record<string, string>;
+    models?: ProviderChatModelConfig[];
+    streamSimple?: (model: Model, context: TranscriptContext, options?: SimpleStreamOptions) => AssistantMessageEventStream;
+}
+export interface MediaProjectionContext {
+    sessionId?: string;
+    provider: string;
+    modelId: string;
+}
+export interface ModelRuntimeOptions {
+    fetch?: typeof fetch;
+    /** Custom fetch implementations use HTTP unless the host explicitly enables WebSocket connections. */
+    responsesTransport?: "auto" | "http";
+    responsesProxy?: ResponsesSessionOptions["resolveProxy"];
+    /** Optional local diagnostics; the SDK has no dependency on a logging backend. */
+    onMediaProjection?: (stats: MediaBudgetStats, context: MediaProjectionContext) => void;
+    onResponsesDiagnostic?: (diagnostic: ResponsesSessionDiagnostic, context: MediaProjectionContext) => void;
+}
+export declare class ModelRuntime {
+    private providers;
+    private keys;
+    private requestFetch?;
+    private onMediaProjection?;
+    private onResponsesDiagnostic?;
+    private responsesTransport;
+    readonly responsesProxy?: ResponsesSessionOptions["resolveProxy"];
+    constructor(requestFetch?: typeof fetch, options?: ModelRuntimeOptions);
+    get fetch(): typeof fetch;
+    canUseResponsesSession(model: Model): boolean;
+    static create(options?: ModelRuntimeOptions): Promise<ModelRuntime>;
+    mediaProjectionObserver(model: Model, sessionId?: string): SimpleStreamOptions["onMediaProjection"];
+    responsesDiagnosticObserver(model: Model, sessionId?: string): ResponsesSessionOptions["onDiagnostic"];
+    clearProviders(): void;
+    registerProvider(id: string, config: ProviderConfigInput): void;
+    getModel(provider: string, id: string): Model | undefined;
+    getAvailable(): Promise<readonly Model[]>;
+    setRuntimeApiKey(provider: string, key: string): Promise<void>;
+    streamSimple(model: Model, context: Context, options?: SimpleStreamOptions): AssistantMessageEventStream;
+}

package/dist/types/coding-agent/src/core/read-file-bounded.d.ts

@@ -0,0 +1,2 @@
+/** Read at most maxBytes + 1, including when a file grows after it was inspected. */
+export declare function readFileBounded(path: string, maxBytes: number): Promise<Buffer>;

package/dist/types/coding-agent/src/core/record-validation.d.ts

@@ -0,0 +1,6 @@
+import type { Message } from "../../../ai/src/index.js";
+import type { SessionEntry, SessionHeader } from "./session-manager.js";
+export declare const maxSessionEntryBytes: number;
+export declare function isSessionHeader(value: unknown): value is SessionHeader;
+export declare function isSessionEntry(value: unknown): value is SessionEntry;
+export declare function validateMessage(value: unknown): asserts value is Message;

package/dist/types/coding-agent/src/core/resources.d.ts

@@ -0,0 +1,51 @@
+import type { ResourceDiagnostic, ResourceLoader } from "./types.js";
+export interface SkillMetadata {
+    name: string;
+    description: string;
+    path: string;
+    baseDir: string;
+    source: "user" | "project" | "plugin";
+}
+export interface DiscoveredSkill extends SkillMetadata {
+    enabled: boolean;
+    overriddenBy?: string;
+}
+export interface SkillPolicyOptions {
+    projectDir: string;
+    homeDir?: string;
+    projectResources?: boolean;
+    isSkillEnabled?: (path: string) => boolean;
+}
+export interface SkillList {
+    skills: SkillMetadata[];
+    diagnostics: ResourceDiagnostic[];
+}
+export interface LoadedSkill extends SkillMetadata {
+    body: string;
+}
+export declare class SkillCatalog {
+    private discovered;
+    private winners;
+    private catalog;
+    constructor(privateOptions: SkillPolicyOptions);
+    private options;
+    reload(): Promise<void>;
+    listSkills(): SkillList;
+    listDiscoveredSkills(): DiscoveredSkill[];
+    loadSkill(name: string): Promise<LoadedSkill>;
+}
+export declare class FileResourceLoader implements ResourceLoader {
+    private options;
+    private catalog;
+    private instructions;
+    private diagnostics;
+    constructor(options: SkillPolicyOptions);
+    getBaseInstructions(): undefined;
+    getInstructions(): string[];
+    reload(): Promise<void>;
+    listSkills(): SkillList;
+    listDiscoveredSkills(): DiscoveredSkill[];
+    loadSkill(name: string): Promise<LoadedSkill>;
+    getDiagnostics(): ResourceDiagnostic[];
+}
+export declare function formatSkillsForPrompt(skills: SkillMetadata[], tool?: "read" | "bash"): string;

package/dist/types/coding-agent/src/core/sdk.d.ts

@@ -0,0 +1,50 @@
+import type { AgentTool, ThinkingLevel } from "../../../agent/src/index.js";
+import type { Context, Model } from "../../../ai/src/index.js";
+import { type SessionContributions } from "../plugins/assembly.js";
+import type { HookRegistration } from "../plugins/hooks.js";
+import { AgentSession } from "./agent-session.js";
+import type { CompactionOptions } from "./compaction.js";
+import type { ModelPerformanceTotals } from "./model-performance.js";
+import { ModelRuntime } from "./model-runtime.js";
+import { SessionManager } from "./session-manager.js";
+import { SettingsManager } from "./settings-manager.js";
+import { type PromptTemplate } from "./system-prompt.js";
+import type { ResourceLoader } from "./types.js";
+export interface SystemPromptContext {
+    tools: readonly AgentTool[];
+    pluginInstructions: readonly string[];
+    resourceLoader: ResourceLoader;
+}
+export interface CreateAgentSessionOptions extends SessionContributions {
+    /** Build tool definitions and selection once the shared resource catalog is loaded. */
+    prepareTools?: (loader: ResourceLoader) => Pick<SessionContributions, "customTools" | "tools">;
+    modelRequestOptions?: () => import("../../../ai/src/index.js").SimpleStreamOptions;
+    onCompaction?: (phase: "before" | "after", context: {
+        manual: boolean;
+        instructions: string;
+    }, signal?: AbortSignal) => Promise<void>;
+    /** Explicit complete prompt, evaluated again after resource refresh. */
+    systemPrompt?: string | ((context: SystemPromptContext) => string);
+    /** Host policy checked at each foreground model request, including continuation requests. */
+    beforeModelRequest?: (model: Model, context: Context) => void;
+    hooks?: readonly HookRegistration[];
+    modelPerformanceTotals?: ModelPerformanceTotals;
+    cwd?: string;
+    agentDir?: string;
+    modelRuntime?: ModelRuntime;
+    model?: Model;
+    thinkingLevel?: ThinkingLevel;
+    /** Literal additions, recomputed after resource reload when supplied as a function. */
+    customInstructions?: readonly string[] | (() => readonly string[]);
+    resourceLoader?: ResourceLoader;
+    sessionManager?: SessionManager;
+    homeDir?: string;
+    compaction?: CompactionOptions;
+    settingsManager?: SettingsManager;
+    promptTemplate?: () => PromptTemplate;
+    projectName?: string | (() => string);
+}
+export interface CreateAgentSessionResult {
+    session: AgentSession;
+}
+export declare function createAgentSession(options?: CreateAgentSessionOptions): Promise<CreateAgentSessionResult>;