@xeno-corporation/xeno-agent-sdk 0.5.0

package/dist/electron/index.d.ts

@@ -0,0 +1,1166 @@
+interface ToolDefinition {
+    name: string;
+    description: string;
+    input_schema: {
+        type: "object";
+        properties: Record<string, unknown>;
+        required?: string[];
+    };
+}
+interface ImageUrlBlock {
+    type: "image_url";
+    image_url: {
+        url: string;
+        detail?: "auto" | "low" | "high";
+    };
+}
+interface ResourceContentBlock {
+    type: "resource";
+    uri?: string;
+    mimeType?: string;
+    text?: string;
+    data?: string;
+}
+type ToolAssistantContentBlock = TextBlock | ImageUrlBlock | ResourceContentBlock;
+type ToolResultContent = string | ToolAssistantContentBlock[];
+interface ToolResult {
+    success: boolean;
+    output: string;
+    error?: string;
+    assistantContent?: ToolAssistantContentBlock[];
+    assistantOnlyContent?: ToolAssistantContentBlock[];
+}
+type ToolExecutor = (input: Record<string, unknown>) => Promise<ToolResult>;
+interface RegisteredTool {
+    definition: ToolDefinition;
+    execute: ToolExecutor;
+}
+interface TextBlock {
+    type: "text";
+    text: string;
+}
+interface ToolUseBlock {
+    type: "tool_use";
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+}
+interface ToolResultBlock {
+    type: "tool_result";
+    tool_use_id: string;
+    content: string;
+    assistant_content?: ToolAssistantContentBlock[];
+    assistant_only_content?: ToolAssistantContentBlock[];
+    is_error?: boolean;
+}
+type ContentBlock = TextBlock | ToolUseBlock;
+interface Message {
+    role: "user" | "assistant";
+    content: string | ContentBlock[] | ToolResultBlock[];
+}
+type PermissionDecision = "allow" | "ask" | "deny";
+type ExecutionMode = "agent" | "chatOnly";
+interface PermissionRule {
+    tool: string;
+    pattern?: string;
+    decision: PermissionDecision;
+}
+interface PermissionConfig {
+    mode: "default" | "acceptEdits" | "bypassPermissions" | "plan";
+    rules: PermissionRule[];
+}
+type PermissionPromptOperation = "generic" | "filesystem" | "write" | "edit" | "bash";
+interface PermissionPromptPreviewLine {
+    kind: "meta" | "context" | "add" | "remove";
+    text: string;
+}
+interface PermissionPromptPreview {
+    title: string;
+    summary?: string;
+    lines: PermissionPromptPreviewLine[];
+    truncated?: boolean;
+}
+interface PermissionPromptInfo {
+    toolName: string;
+    detail: string;
+    description?: string;
+    operation?: PermissionPromptOperation;
+    preview?: PermissionPromptPreview;
+    commandPrefix?: string;
+    approvalKey?: string;
+    requesterLabel?: string;
+    requesterSummary?: string;
+    directory?: string;
+    filePath?: string;
+}
+type PermissionPromptFn = (info: PermissionPromptInfo) => Promise<"allow" | "always" | "deny">;
+type SessionStatus = "creating" | "active" | "paused" | "completed" | "abandoned" | "archived";
+interface SessionMeta {
+    id: string;
+    role: string;
+    name?: string;
+    status: SessionStatus;
+    createdAt: string;
+    updatedAt: string;
+    lastActivity: string;
+    workingDirectory: string;
+    model: string;
+    parentSession?: string;
+    checkpoints: string[];
+    messageCount: number;
+    tokenUsage: {
+        input: number;
+        output: number;
+        total: number;
+    };
+    formatVersion?: number;
+}
+type TranscriptEventType = "session_start" | "user_message" | "assistant_message" | "tool_call" | "tool_result" | "delegation_summary" | "checkpoint" | "context_compressed" | "session_end" | "error";
+interface SessionStartData {
+    sessionId: string;
+    role: string;
+    model: string;
+    workingDirectory: string;
+    formatVersion?: number;
+}
+interface ToolCallData {
+    toolName: string;
+    input: Record<string, unknown>;
+}
+interface ToolResultData {
+    toolName: string;
+    success: boolean;
+    output: string;
+    error?: string;
+    assistantContent?: ToolAssistantContentBlock[];
+    assistantOnlyContent?: ToolAssistantContentBlock[];
+}
+interface CheckpointData {
+    id?: string;
+    checkpointId?: string;
+    action?: "create" | "restore" | "delete";
+    name?: string;
+    trigger?: CheckpointTrigger;
+    messageCount: number;
+}
+interface DelegationSummaryData {
+    selectedRole?: string;
+    selectedTaskId?: string;
+    elapsedMs: number;
+    totalTokens: number;
+    okBranches: number;
+    errorBranches: number;
+    totalBranches: number;
+    roleSummaries: Record<string, {
+        status: "ok" | "error" | "timeout";
+        tokensUsed: number;
+        outputPreview?: string;
+        error?: string;
+    }>;
+}
+interface ContextCompressedData {
+    messagesRemoved: number;
+    tokensSaved: number;
+}
+interface SessionEndData {
+    reason: "user_exit" | "error" | "completed";
+    messageCount: number;
+    totalTokens: number;
+}
+interface ErrorData {
+    message: string;
+    code?: string;
+    stack?: string;
+}
+type TranscriptEventData = {
+    type: "session_start";
+    data: SessionStartData;
+} | {
+    type: "user_message";
+    data: Message;
+} | {
+    type: "assistant_message";
+    data: Message;
+} | {
+    type: "tool_call";
+    data: ToolCallData;
+} | {
+    type: "tool_result";
+    data: ToolResultData;
+} | {
+    type: "delegation_summary";
+    data: DelegationSummaryData;
+} | {
+    type: "checkpoint";
+    data: CheckpointData;
+} | {
+    type: "context_compressed";
+    data: ContextCompressedData;
+} | {
+    type: "session_end";
+    data: SessionEndData;
+} | {
+    type: "error";
+    data: ErrorData;
+};
+interface TranscriptEvent {
+    id: string;
+    type: TranscriptEventType;
+    timestamp: string;
+    sequence: number;
+    data: TranscriptEventData["data"];
+    tokenCount?: number;
+}
+type CheckpointTrigger = "auto" | "manual" | "pre_dangerous" | "milestone";
+interface CheckpointInfo {
+    id: string;
+    name?: string;
+    trigger: CheckpointTrigger;
+    createdAt: string;
+    messageCount: number;
+    tokenCount: number;
+}
+interface PermissionRequestContext {
+    toolName: string;
+    path: string;
+    directory: string;
+    reason: string;
+}
+interface PermissionRequestResult {
+    granted: boolean;
+    allowedDirectory?: string;
+}
+interface AgentCapabilities {
+    terminal: boolean;
+    fileRead: boolean;
+    fileWrite: boolean;
+    appLaunch: boolean;
+}
+interface AgentSandbox {
+    allowedDirectories: string[];
+    workingDirectory?: string;
+    capabilities: AgentCapabilities;
+    temporaryDirectories?: string[];
+    workspace?: {
+        id: string;
+        name: string;
+    };
+    team?: {
+        id: string;
+        name: string;
+    };
+}
+interface ToolRegistryOptions {
+    validateInputs?: boolean;
+}
+declare class ToolRegistry {
+    private tools;
+    private changeListeners;
+    private aliasNames;
+    private validateInputs;
+    constructor(options?: ToolRegistryOptions);
+    setValidateInputs(enabled: boolean): this;
+    get inputValidationEnabled(): boolean;
+    register(tool: RegisteredTool): void;
+    registerAlias(tool: RegisteredTool): void;
+    registerAll(tools: Iterable<RegisteredTool>): void;
+    unregister(name: string): boolean;
+    onChange(listener: () => void): () => void;
+    private emitChange;
+    get(name: string): RegisteredTool | undefined;
+    getDefinitions(): ToolDefinition[];
+    private static namespaceOf;
+    getDefinitionsByNamespace(namespace: string): ToolDefinition[];
+    listNamespaces(): string[];
+    execute(name: string, input: Record<string, unknown>): Promise<ToolResult>;
+    listNames(): string[];
+    has(name: string): boolean;
+    get size(): number;
+}
+interface PermissionDecisionEvent {
+    traceId?: string;
+    toolName: string;
+    input: Record<string, unknown>;
+    allowed: boolean;
+    reason: string;
+    mode: PermissionConfig["mode"];
+    requesterLabel?: string;
+}
+type PermissionDecisionHook = (event: PermissionDecisionEvent) => Promise<void> | void;
+interface PersistentPermissionState {
+    allowedTools?: string[];
+    allowedDirectories?: string[];
+}
+interface PermissionCheckContext {
+    traceId?: string;
+    requesterLabel?: string;
+}
+declare class PermissionEngine {
+    private config;
+    private workingDirectory;
+    private sessionAllowed;
+    private sessionAllowedDirectories;
+    private persistentAllowed;
+    private persistentAllowedDirectories;
+    private promptFn?;
+    private decisionHook?;
+    constructor(config?: Partial<PermissionConfig>, promptFn?: PermissionPromptFn, decisionHook?: PermissionDecisionHook);
+    get mode(): PermissionConfig["mode"];
+    setMode(mode: PermissionConfig["mode"]): void;
+    setWorkingDirectory(cwd: string): void;
+    loadPersistentState(state: PersistentPermissionState): void;
+    allowDirectory(directory: string): void;
+    isPathInAllowedDirectory(filePath: string): boolean;
+    check(toolName: string, input: Record<string, unknown>, context?: PermissionCheckContext): Promise<{
+        allowed: boolean;
+        reason: string;
+    }>;
+    private finalizeDecision;
+    private getCacheKey;
+    private isPathInPersistentAllowedDirectory;
+    private extractFilePath;
+    private extractDirectory;
+    private normalizeDirectory;
+    private promptUser;
+    private getToolDetail;
+    private getCommandPrefix;
+    private matchesRule;
+    private matchesBashPattern;
+    private hasBashApproval;
+    private extractBashCommandPrefix;
+    private normalizeCommandText;
+    private resolveTargetPath;
+}
+type XenoRuntimeEventType = "thread.started" | "turn.started" | "turn.completed" | "turn.failed" | "turn.interrupted" | "model.text.delta" | "tool.started" | "tool.permission" | "tool.completed" | "diff.completed";
+interface XenoRuntimeEventBase {
+    id: string;
+    sequence: number;
+    type: XenoRuntimeEventType;
+    timestamp: string;
+    threadId?: string;
+    turnId?: string;
+}
+type XenoRuntimeEvent = (XenoRuntimeEventBase & {
+    type: "thread.started";
+    cwd: string;
+    model: string;
+}) | (XenoRuntimeEventBase & {
+    type: "turn.started";
+    model: string;
+    promptPreview: string;
+}) | (XenoRuntimeEventBase & {
+    type: "turn.completed";
+    outputPreview: string;
+    tokenUsage: {
+        input: number;
+        output: number;
+        total: number;
+    };
+}) | (XenoRuntimeEventBase & {
+    type: "turn.failed" | "turn.interrupted";
+    error: string;
+}) | (XenoRuntimeEventBase & {
+    type: "model.text.delta";
+    text: string;
+    iteration?: number;
+}) | (XenoRuntimeEventBase & {
+    type: "tool.started";
+    toolName: string;
+    inputPreview: Record<string, unknown>;
+    iteration?: number;
+}) | (XenoRuntimeEventBase & {
+    type: "tool.permission";
+    toolName: string;
+    allowed: boolean;
+    reason: string;
+    layer: "sandbox" | "permission";
+    iteration?: number;
+}) | (XenoRuntimeEventBase & {
+    type: "tool.completed";
+    toolName: string;
+    success: boolean;
+    outputPreview: string;
+    error?: string;
+    elapsedMs: number;
+    iteration?: number;
+}) | (XenoRuntimeEventBase & {
+    type: "diff.completed";
+    filesChanged: number;
+    summary: string;
+});
+type XenoRuntimeEventSink = (event: XenoRuntimeEvent) => void | Promise<void>;
+type XenoRuntimeEventDraft = XenoRuntimeEvent extends infer Event ? Event extends XenoRuntimeEvent ? Omit<Event, "id" | "sequence" | "timestamp"> & Partial<Pick<XenoRuntimeEvent, "id" | "sequence" | "timestamp">> : never : never;
+declare class XenoRuntimeEventBus {
+    private readonly maxHistory;
+    private listeners;
+    private history;
+    private sequence;
+    constructor(maxHistory?: number);
+    subscribe(listener: XenoRuntimeEventSink): () => void;
+    nextSequence(): number;
+    emit(event: XenoRuntimeEventDraft): void;
+    snapshot(): XenoRuntimeEvent[];
+}
+type AuditRiskLevel = "none" | "low" | "medium" | "high" | "critical";
+type AuditDecision = "allow" | "ask" | "deny";
+type AuditStatus = "ok" | "error";
+interface AuditEvent {
+    id: string;
+    sequence: number;
+    timestamp: string;
+    trace_id: string;
+    session_id?: string;
+    event_type: string;
+    actor: "user" | "assistant" | "system";
+    risk_level: AuditRiskLevel;
+    tool_name?: string;
+    decision?: AuditDecision;
+    status?: AuditStatus;
+    reason?: string;
+    metadata?: Record<string, unknown>;
+}
+interface AuditLoggerOptions {
+    filePath: string;
+    sessionId?: string;
+}
+declare class AuditLogger {
+    private filePath;
+    private sessionId?;
+    private sequence;
+    private writeQueue;
+    constructor(options: AuditLoggerOptions);
+    get path(): string;
+    append(event: Omit<AuditEvent, "id" | "sequence" | "timestamp" | "session_id"> & {
+        session_id?: string;
+    }): Promise<string>;
+    read(options?: {
+        limit?: number;
+        eventType?: string;
+        traceId?: string;
+    }): Promise<AuditEvent[]>;
+    tail(limit?: number): Promise<AuditEvent[]>;
+    exportJson(targetPath: string): Promise<number>;
+    flush(): Promise<void>;
+}
+interface FileSnapshot {
+    path: string;
+    exists: boolean;
+    size: number;
+    mtimeMs: number;
+    text?: string;
+    binary?: boolean;
+    truncated?: boolean;
+}
+interface TurnFileDiff {
+    path: string;
+    status: "created" | "modified" | "deleted" | "unchanged";
+    before?: FileSnapshot;
+    after?: FileSnapshot;
+    patch?: string;
+}
+interface TurnDiffSummary {
+    turnId: string;
+    startedAt: string;
+    completedAt: string;
+    files: TurnFileDiff[];
+}
+interface TurnDiffTrackerOptions {
+    maxFileBytes?: number;
+    cwd?: string;
+}
+declare class TurnDiffTracker {
+    private active?;
+    private readonly maxFileBytes;
+    private readonly cwd;
+    constructor(options?: TurnDiffTrackerOptions);
+    beginTurn(turnId: string): void;
+    observeBefore(paths: Iterable<string | null | undefined>): void;
+    observeAfter(paths: Iterable<string | null | undefined>): void;
+    endTurn(): TurnDiffSummary | undefined;
+    inferToolPaths(toolName: string, input: Record<string, unknown>): string[];
+    private resolvePath;
+    private snapshot;
+}
+declare class TranscriptWriter {
+    private sessionDir;
+    private sessionId;
+    private transcriptPath;
+    private markdownPath;
+    private workspaceMarkdownPath;
+    private markdownHeaderWritten;
+    private workspaceHeaderWritten;
+    private workspaceMirrorDisabled;
+    private sequence;
+    private writeQueue;
+    private pendingWrites;
+    constructor(sessionDir: string);
+    append(event: Omit<TranscriptEvent, "id" | "timestamp" | "sequence">): Promise<string>;
+    private stringify;
+    private formatMessageContent;
+    private formatEventMarkdown;
+    private ensureMarkdownHeader;
+    private resolveWorkspaceMarkdownPath;
+    private appendMarkdownEvent;
+    private buildMarkdownDocument;
+    read(options?: {
+        types?: TranscriptEventType[];
+        limit?: number;
+        offset?: number;
+    }): Promise<TranscriptEvent[]>;
+    private isMessageData;
+    getMessages(): Promise<Message[]>;
+    replaceMessages(messages: Message[]): Promise<void>;
+    truncateAfterMessageCount(messageCount: number): Promise<void>;
+    getSequence(): number;
+    initialize(): Promise<void>;
+    flush(): Promise<void>;
+}
+declare class CheckpointManager {
+    private sessionDir;
+    private checkpointsDir;
+    private autoInterval;
+    private lastCheckpointMessageCount;
+    constructor(sessionDir: string, options?: {
+        autoInterval?: number;
+    });
+    initialize(): Promise<void>;
+    create(options: {
+        trigger: CheckpointTrigger;
+        messages: Message[];
+        description?: string;
+    }): Promise<CheckpointInfo>;
+    list(): Promise<CheckpointInfo[]>;
+    restore(checkpointId: string): Promise<{
+        messages: Message[];
+        info: CheckpointInfo;
+    }>;
+    shouldAutoCheckpoint(currentMessageCount: number): boolean;
+    static isDangerousOperation(toolName: string, input: unknown): boolean;
+    delete(checkpointId: string): Promise<void>;
+    private estimateTokens;
+}
+interface SessionCreateOptions {
+    role?: string;
+    parentSession?: string;
+    workingDirectory: string;
+    model: string;
+}
+interface SessionResumeOptions {
+    sessionId: string;
+    fromCheckpoint?: string;
+}
+declare class SessionManager {
+    private sessionDir;
+    private _meta;
+    private _transcript;
+    private _checkpoints;
+    private _lock;
+    private constructor();
+    static create(options: SessionCreateOptions): Promise<SessionManager>;
+    static resume(options: SessionResumeOptions): Promise<SessionManager>;
+    get meta(): SessionMeta;
+    get transcript(): TranscriptWriter;
+    get checkpoints(): CheckpointManager;
+    updateMeta(partial: Partial<SessionMeta>): Promise<void>;
+    end(status?: "completed" | "abandoned"): Promise<void>;
+    recordUserMessage(content: string): Promise<void>;
+    recordAssistantMessage(content: string | ContentBlock[] | ToolResultBlock[], tokenCount?: number): Promise<void>;
+    recordTokenUsage(input: number, output: number): Promise<void>;
+    recordDelegationSummary(data: DelegationSummaryData): Promise<void>;
+    updateMessageCount(count: number): Promise<void>;
+}
+interface ApiTextContentBlock {
+    type: "text";
+    text: string;
+}
+interface ApiToolUseContentBlock {
+    type: "tool_use";
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+}
+interface ApiToolResultContentBlock {
+    type: "tool_result";
+    tool_use_id: string;
+    content: ToolResultContent;
+    assistant_content?: ToolAssistantContentBlock[];
+    assistant_only_content?: ToolAssistantContentBlock[];
+    is_error?: boolean;
+}
+type ApiMessage = {
+    role: "user" | "assistant";
+    content: string | Array<ApiTextContentBlock | ApiToolUseContentBlock | ApiToolResultContentBlock>;
+};
+type XenoChatMessage = {
+    role: "system" | "user" | "assistant" | "tool";
+    content: string | null | Array<{
+        type: "text";
+        text: string;
+    } | {
+        type: "image_url";
+        image_url: {
+            url: string;
+            detail?: "auto" | "low" | "high";
+        };
+    }>;
+    tool_call_id?: string;
+    tool_calls?: Array<{
+        id: string;
+        type: "function";
+        function: {
+            name: string;
+            arguments: string;
+        };
+    }>;
+};
+interface StreamResult {
+    content: ContentBlock[];
+    stopReason: "end_turn" | "tool_use" | "max_tokens" | "stop_sequence";
+    inputTokens: number;
+    outputTokens: number;
+}
+interface ApiRequestFailureDiagnostics {
+    model: string;
+    requestUrl: string;
+    stream: boolean;
+    messageCount: number;
+    toolCount: number;
+    requestBytes: number;
+    promptTokenEstimate: number;
+    statusCode?: number;
+    requestId?: string;
+    cfRay?: string;
+    retryAfterMs?: number;
+    detailPreview?: string;
+    errorMessage?: string;
+}
+interface LlmClientDeps {
+    readonly baseURL: string;
+    readonly ollamaBaseUrl: string;
+    readonly apiKey?: string;
+    readonly maxTokens: number;
+    getApiRequestTimeoutMs(): number;
+    buildRuntimeSystemPrompt(): string;
+    reportFailure(diagnostics: ApiRequestFailureDiagnostics): Promise<void>;
+}
+declare class LlmClient {
+    private readonly deps;
+    private ollamaMode;
+    constructor(deps: LlmClientDeps);
+    readonly id = "xeno-llm-client";
+    complete(model: string, messages: ApiMessage[], tools: ToolDefinition[], onText?: (text: string) => void, signal?: AbortSignal): Promise<StreamResult>;
+    completeLocal(model: string, messages: ApiMessage[], tools: ToolDefinition[], onText?: (text: string) => void, signal?: AbortSignal): Promise<StreamResult>;
+    toOllamaMessages(apiMessages: ApiMessage[]): Array<{
+        role: "system" | "user" | "assistant" | "tool";
+        content: string;
+        tool_call_id?: string;
+        tool_calls?: Array<{
+            id: string;
+            type: "function";
+            function: {
+                name: string;
+                arguments: string;
+            };
+        }>;
+    }>;
+    toXenoMessages(apiMessages: ApiMessage[], options?: {
+        allowImages?: boolean;
+    }): XenoChatMessage[];
+    private buildStructuredToolContextMessage;
+    private modelSupportsImageInputs;
+    private describeSuppressedImageBlock;
+    getChatCompletionsBaseUrl(): string;
+    private condenseToolResultForModel;
+    buildXenoToolDefinitions(tools: ToolDefinition[]): Array<{
+        type: "function";
+        function: {
+            name: string;
+            description: string;
+            parameters: ToolDefinition["input_schema"];
+        };
+    }>;
+    private buildChatCompletionsRequestBody;
+    private parseXenoCompletion;
+    static parseRetryAfterSeconds(value: string | null): number | undefined;
+    private static getHeaderValue;
+    private static stripHtml;
+    private static summarizeErrorBody;
+    private createApiRequestSignal;
+    callChatCompletionsNonStream(model: string, apiMessages: ApiMessage[], tools: ToolDefinition[], onText?: (text: string) => void, signal?: AbortSignal): Promise<StreamResult>;
+    callChatCompletions(model: string, apiMessages: ApiMessage[], tools: ToolDefinition[], onText?: (text: string) => void, signal?: AbortSignal): Promise<StreamResult>;
+    callOllama(model: string, apiMessages: ApiMessage[], tools: ToolDefinition[], onText?: (text: string) => void, signal?: AbortSignal): Promise<StreamResult>;
+    private callOllamaOpenAI;
+    private callOllamaNative;
+}
+interface ToolMiddlewareContext {
+    readonly toolName: string;
+    readonly toolCallId: string;
+    input: Record<string, unknown>;
+    readonly iteration: number;
+    readonly traceId: string;
+    readonly signal: AbortSignal;
+    addGuidance(text: string): void;
+}
+type ToolMiddleware = (ctx: ToolMiddlewareContext, next: () => Promise<ToolResult>) => Promise<ToolResult>;
+interface PromptSectionContext {
+    readonly systemPrompt: string;
+    readonly taskPrompt?: string;
+    readonly iteration: number;
+    readonly model: string;
+}
+interface PromptSectionProvider {
+    name: string;
+    order?: number;
+    provide(ctx: PromptSectionContext): string | null | undefined;
+}
+type CompletionGuardStopReason = "end_turn" | "tool_use" | "max_tokens" | "stop_sequence" | "empty_response" | "progress_checkpoint";
+interface CompletionGuardTurnStats {
+    readonly iteration: number;
+    readonly maxIterations: number;
+    readonly toolCalls: number;
+    readonly toolFailures: number;
+    readonly failuresByTool: Readonly<Record<string, number>>;
+}
+interface CompletionGuardEvaluationContext {
+    readonly finalText: string;
+    readonly iteration: number;
+    readonly maxIterations: number;
+    readonly messages: Message[];
+    readonly stopReason: CompletionGuardStopReason;
+    readonly stats: CompletionGuardTurnStats;
+}
+type CompletionGuardDecision = {
+    allow: true;
+} | {
+    allow: false;
+    guidance: string;
+    stop?: boolean;
+};
+interface CompletionGuard {
+    name: string;
+    order?: number;
+    evaluate(ctx: CompletionGuardEvaluationContext): CompletionGuardDecision | null | undefined | Promise<CompletionGuardDecision | null | undefined>;
+}
+type LLMProviderMessage = ApiMessage;
+type LLMCompletionResult = StreamResult;
+interface LLMProviderCapabilities {
+    readonly streaming?: boolean;
+    readonly tools?: boolean;
+    readonly vision?: boolean;
+    readonly [capability: string]: boolean | undefined;
+}
+interface LLMProvider {
+    readonly id: string;
+    readonly model?: string;
+    readonly capabilities?: LLMProviderCapabilities;
+    complete(model: string, messages: LLMProviderMessage[], tools: ToolDefinition[], onText?: (text: string) => void, signal?: AbortSignal): Promise<LLMCompletionResult>;
+    completeLocal?(model: string, messages: LLMProviderMessage[], tools: ToolDefinition[], onText?: (text: string) => void, signal?: AbortSignal): Promise<LLMCompletionResult>;
+}
+interface ModeSwitchRequest {
+    from: ExecutionMode;
+    to: ExecutionMode;
+    requestedTools: string[];
+    reason: string;
+}
+interface AgentLoopConfig {
+    apiKey?: string;
+    baseURL: string;
+    ollamaBaseURL?: string;
+    model: string;
+    maxTokens: number;
+    maxIterations: number;
+    systemPrompt: string;
+    requesterLabel?: string;
+    executionMode?: ExecutionMode;
+    permissionEngine: PermissionEngine;
+    toolRegistry?: ToolRegistry;
+    onText?: (text: string) => void;
+    onToolStart?: (name: string, input: Record<string, unknown>) => void;
+    onToolWillExecute?: (name: string, input: Record<string, unknown>) => void | Promise<void>;
+    onToolEnd?: (name: string, result: ToolResult) => void;
+    onIteration?: (iteration: number, totalTokens: number) => void;
+    onError?: (error: Error, context: string) => void;
+    onTranscriptError?: (error: Error, context: string) => void;
+    onModeSwitchRequest?: (request: ModeSwitchRequest) => Promise<boolean>;
+    onExecutionModeChanged?: (mode: ExecutionMode, reason: string) => void;
+    onContextCompressed?: (messagesRemoved: number, tokensSaved: number) => void;
+    onRuntimeEvent?: XenoRuntimeEventSink;
+    runtimeEventBus?: XenoRuntimeEventBus;
+    turnDiffTracker?: TurnDiffTracker;
+    completionGuard?: (context: CompletionGuardContext) => Promise<CompletionGuardResult | null> | CompletionGuardResult | null;
+    maxCompletionGuardReminders?: number;
+    progressGuardEveryIterations?: number;
+    apiRequestTimeoutMs?: number;
+    runStartedAtMs?: number;
+    externalTimeoutMs?: number;
+    apiDeadlineFinalBufferMs?: number;
+    backgroundTaskDrainMaxWaitMs?: number;
+    backgroundTaskDrainPollIntervalMs?: number;
+    backgroundTaskDrainExtraIterations?: number;
+    sandbox?: AgentSandbox;
+    onPermissionRequest?: (context: PermissionRequestContext) => Promise<PermissionRequestResult> | PermissionRequestResult;
+    toolMiddleware?: ToolMiddleware[];
+    promptSections?: PromptSectionProvider[];
+    promptSectionsTokenBudget?: number;
+    completionGuards?: CompletionGuard[];
+    provider?: LLMProvider;
+    transcript?: TranscriptWriter;
+    checkpoints?: CheckpointManager;
+    sessionManager?: SessionManager;
+    autoCheckpointInterval?: number;
+    maxContextTokens?: number;
+    historyMarkdownPath?: string;
+    compressionKeepRecentMessages?: number;
+    auditLogger?: AuditLogger;
+}
+interface CompletionGuardContext {
+    finalText: string;
+    iteration: number;
+    messages: Message[];
+    stopReason: StreamResult["stopReason"] | "empty_response" | "progress_checkpoint";
+}
+interface RunStreamOptions {
+    signal?: AbortSignal;
+}
+interface CompletionGuardResultObject {
+    message: string;
+    blocking?: boolean;
+    stop?: boolean;
+    toolPolicy?: CompletionGuardToolPolicy;
+}
+type CompletionGuardResult = string | CompletionGuardResultObject;
+type CompletionGuardToolPolicyMode = "require_output_checkpoint";
+interface CompletionGuardToolPolicy {
+    mode: CompletionGuardToolPolicyMode;
+    requiredOutputPaths?: string[];
+    message?: string;
+}
+type AgentRunTerminationStatus = "completed" | "incomplete" | "interrupted" | "error";
+type AgentRunTerminationReason = "end_turn" | "empty_response" | "max_tokens" | "completion_guard_stop" | "max_iterations" | "interrupted" | "error";
+interface AgentRunTermination {
+    status: AgentRunTerminationStatus;
+    reason: AgentRunTerminationReason;
+    iteration: number;
+    maxIterations: number;
+    finalStateVerified: boolean;
+    message: string;
+}
+interface SessionIntegrationConfig {
+    transcript?: TranscriptWriter;
+    checkpoints?: CheckpointManager;
+    sessionManager?: SessionManager;
+    historyMarkdownPath?: string;
+    auditLogger?: AuditLogger;
+}
+declare class AgentLoop {
+    private config;
+    private toolRegistry;
+    private _messages;
+    private totalInputTokens;
+    private totalOutputTokens;
+    private lastCheckpointMessageCount;
+    private ollamaBaseUrl;
+    private activeAbortController;
+    private interruptionRequested;
+    private currentTraceId;
+    private lastRunTraceId;
+    private lastRunTerminationInfo;
+    private activeTaskPrompt;
+    private activeToolPolicy;
+    private apiFailureDiagnosticsLogged;
+    private readonly runtimeEventBus;
+    private readonly threadId;
+    private readonly turnDiffTracker?;
+    private readonly llm;
+    private readonly messageFlow;
+    private readonly middleware;
+    private readonly promptSections;
+    private readonly completionGuards;
+    private turnToolCalls;
+    private turnToolFailures;
+    private turnFailuresByTool;
+    private turnIteration;
+    constructor(config: AgentLoopConfig);
+    get tokenUsage(): {
+        input: number;
+        output: number;
+        total: number;
+    };
+    get lastTraceId(): string | null;
+    get lastRunTermination(): AgentRunTermination | null;
+    get model(): string;
+    set model(value: string);
+    get executionMode(): ExecutionMode;
+    set executionMode(value: ExecutionMode);
+    get systemPrompt(): string;
+    set systemPrompt(value: string);
+    use(middleware: ToolMiddleware): this;
+    registerPromptSection(provider: PromptSectionProvider): this;
+    registerCompletionGuard(guard: CompletionGuard): this;
+    attachSessionIntegration(config: SessionIntegrationConfig): void;
+    cancelCurrentTurn(): boolean;
+    private emitRuntimeEvent;
+    private handleTextDelta;
+    private handleContextCompressed;
+    private isAbortError;
+    private toolRiskLevel;
+    private isParallelSafeTool;
+    private pathAliasesForToolPolicy;
+    private toolPolicyMentionsRequiredPath;
+    private toolPolicyTargetsRequiredPath;
+    private bashCommandCanCreateRequiredOutput;
+    private toolCallSatisfiesToolPolicy;
+    private maybeBlockActiveToolPolicy;
+    private getCompressedSourceSizeLimit;
+    private isSourceLikePath;
+    private isBinaryReimplementationContractTask;
+    private getOriginalBinaryAliases;
+    private textMentionsOriginalBinary;
+    private sourceContainsOriginalBinaryBypass;
+    private sourceGenerationCommandContainsOriginalBinaryBypass;
+    private buildSourceIndependenceBlock;
+    private maybeBlockSourceIndependenceViolation;
+    private maybeBlockKnownInvalidWrite;
+    private maybeBlockKnownInvalidBashSourceGeneration;
+    private recordToolEventsToTranscript;
+    protected callChatCompletions(model: string, apiMessages: ApiMessage[], tools: ToolDefinition[], onText?: (text: string) => void, signal?: AbortSignal): Promise<StreamResult>;
+    protected callOllama(model: string, apiMessages: ApiMessage[], tools: ToolDefinition[], onText?: (text: string) => void, signal?: AbortSignal): Promise<StreamResult>;
+    protected toXenoMessages(apiMessages: ApiMessage[]): ReturnType<LlmClient["toXenoMessages"]>;
+    protected toOllamaMessages(apiMessages: ApiMessage[]): ReturnType<LlmClient["toOllamaMessages"]>;
+    private executeToolCall;
+    private recordTurnToolStats;
+    private currentTurnStats;
+    private appendAuditEvent;
+    private setExecutionModeInternal;
+    private maybeAppendApiRequestFailureAudit;
+    private static parsePositiveInteger;
+    private sleep;
+    private getApiDeadlineFinalBufferMs;
+    private getExternalDeadlineMs;
+    private getBackgroundTaskDrainMaxWaitMs;
+    private getBackgroundTaskDrainPollIntervalMs;
+    private getBackgroundTaskDrainExtraIterations;
+    private getBackgroundTaskDrainBudgetMs;
+    private getDrainableBackgroundTasks;
+    private summarizeBackgroundTaskSnapshot;
+    private maybeDrainBackgroundTasksAtIterationBudget;
+    private getApiRequestTimeoutMs;
+    private createApiRequestSignal;
+    private buildRuntimeSystemPrompt;
+    get messages(): Message[];
+    set messages(value: Message[]);
+    private shouldAutoCheckpoint;
+    private getApiMessagesForRequest;
+    private appendSyntheticUserMessage;
+    run(userMessage: string): Promise<string>;
+    runStream(prompt: string, options?: RunStreamOptions): AsyncIterable<XenoRuntimeEvent>;
+    private createRuntimeEventIterator;
+    private runInternal;
+    clearHistory(): void;
+}
+type AppType = "pixel" | "motion" | "sound";
+interface DocumentContext {
+    name: string;
+    path?: string;
+    modified: boolean;
+}
+interface LayerContext {
+    id: string;
+    name: string;
+    type: string;
+}
+interface ClipContext {
+    id: string;
+    name: string;
+    type: string;
+}
+interface TrackContext {
+    id: string;
+    name: string;
+}
+interface CanvasSize {
+    width: number;
+    height: number;
+}
+interface AppContext {
+    app: AppType;
+    document?: DocumentContext;
+    activeLayer?: LayerContext;
+    selectedTool?: string;
+    canvasSize?: CanvasSize;
+    currentFrame?: number;
+    selectedClip?: ClipContext;
+    timelineLength?: number;
+    bpm?: number;
+    currentPosition?: number;
+    selectedTrack?: TrackContext;
+    isRecording?: boolean;
+}
+type AppContextProvider = () => AppContext;
+declare class AppContextManager {
+    private provider;
+    setProvider(provider: AppContextProvider): void;
+    getContext(): AppContext;
+    formatForPrompt(): string;
+}
+interface PermissionInfo {
+    toolName: string;
+    input: unknown;
+    riskLevel: "low" | "medium" | "high";
+}
+interface AgentStreamCallbacks {
+    onText: (text: string) => void;
+    onToolStart: (name: string, input: unknown) => void;
+    onToolEnd: (name: string, result: unknown) => void;
+    onComplete: () => void;
+    onError: (error: Error) => void;
+}
+interface ElectronAgentConfig {
+    apiKey: string;
+    baseURL: string;
+    model: string;
+    app: AppType;
+    tools: RegisteredTool[];
+    appContext: () => AppContext;
+    onPermissionRequest?: (info: PermissionInfo) => Promise<"allow" | "deny">;
+    maxTokens?: number;
+    maxIterations?: number;
+}
+declare class ElectronAgentBridge {
+    private agent;
+    private readonly contextManager;
+    private readonly config;
+    private readonly toolRegistry;
+    private readonly permissionEngine;
+    private pendingPermissions;
+    constructor(config: ElectronAgentConfig);
+    private buildSystemPrompt;
+    sendMessage(text: string, callbacks: AgentStreamCallbacks): Promise<void>;
+    cancel(): boolean;
+    getHistory(): Message[];
+    clearHistory(): void;
+    updateContext(): void;
+    respondToPermission(id: string, decision: "allow" | "deny"): void;
+    getAgentLoop(): AgentLoop;
+    getContextManager(): AppContextManager;
+    getToolRegistry(): ToolRegistry;
+}
+interface PermissionRequestInfo {
+    id: string;
+    toolName: string;
+    input: unknown;
+    riskLevel: "low" | "medium" | "high";
+    description?: string;
+}
+interface AgentToAppMessages {
+    "agent:text": {
+        text: string;
+    };
+    "agent:tool-start": {
+        name: string;
+        input: unknown;
+    };
+    "agent:tool-end": {
+        name: string;
+        result: unknown;
+        success: boolean;
+    };
+    "agent:complete": Record<string, never>;
+    "agent:error": {
+        message: string;
+        code?: string;
+    };
+    "agent:permission-request": PermissionRequestInfo;
+}
+interface AppToAgentMessages {
+    "agent:send-message": {
+        text: string;
+    };
+    "agent:cancel": Record<string, never>;
+    "agent:clear": Record<string, never>;
+    "agent:permission-response": {
+        id: string;
+        decision: "allow" | "deny";
+    };
+}
+type AgentToAppChannel = keyof AgentToAppMessages;
+type AppToAgentChannel = keyof AppToAgentMessages;
+type AgentIpcChannel = AgentToAppChannel | AppToAgentChannel;
+type IpcHandler<C extends string, M extends Record<string, unknown>> = C extends keyof M ? (payload: M[C]) => void : never;
+type DualLLMMode = "auto" | "local" | "cloud";
+interface ChatParams {
+    messages: Array<{
+        role: "system" | "user" | "assistant";
+        content: string;
+    }>;
+    model?: string;
+    maxTokens?: number;
+    temperature?: number;
+    systemPrompt?: string;
+    jsonMode?: boolean;
+    stop?: string[];
+}
+interface ChatResponse {
+    success: boolean;
+    content: string;
+    endpoint: "local" | "cloud";
+    model: string;
+    usage: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+    error?: string;
+}
+interface DualLLMStatus {
+    mode: DualLLMMode;
+    localAvailable: boolean;
+    activeEndpoint: "local" | "cloud";
+    localModel?: string;
+    localUrl: string;
+    cloudUrl: string;
+}
+interface DualLLMProviderConfig {
+    localUrl?: string;
+    cloudUrl?: string;
+    cloudApiKey?: string;
+    mode?: DualLLMMode;
+    localModel?: string;
+    cloudModel?: string;
+}
+declare class DualLLMProvider {
+    private localUrl;
+    private cloudUrl;
+    private cloudApiKey;
+    private mode;
+    private defaultLocalModel;
+    private defaultCloudModel;
+    private localAvailable;
+    private localModelName;
+    private lastHealthCheck;
+    constructor(config?: DualLLMProviderConfig);
+    chat(params: ChatParams): Promise<ChatResponse>;
+    chatStream(params: ChatParams): AsyncGenerator<string>;
+    isLocalAvailable(forceRefresh?: boolean): Promise<boolean>;
+    setMode(mode: DualLLMMode): void;
+    getMode(): DualLLMMode;
+    setLocalUrl(url: string): void;
+    setCloudApiKey(apiKey: string): void;
+    getStatus(): Promise<DualLLMStatus>;
+    asLLMProvider(options?: {
+        id?: string;
+        model?: string;
+    }): LLMProvider;
+    private shouldUseLocal;
+    private chatLocal;
+    private chatCloud;
+}
+type IpcHandleFunction = (channel: string, handler: (event: unknown, ...args: unknown[]) => unknown) => void;
+interface SetupAIHandlersOptions {
+    ipcHandle?: IpcHandleFunction;
+    config?: DualLLMProviderConfig;
+    provider?: DualLLMProvider;
+}
+declare function setupAIHandlers(options?: SetupAIHandlersOptions): DualLLMProvider;
+declare function readXenoApiKey(): string | undefined;
+export { type AgentIpcChannel, type AgentStreamCallbacks, type AgentToAppChannel, type AgentToAppMessages, type AppToAgentChannel, type AppToAgentMessages, ElectronAgentBridge, type ElectronAgentConfig, type IpcHandler, type PermissionInfo, type PermissionRequestInfo, type SetupAIHandlersOptions, readXenoApiKey, setupAIHandlers };