/**
 * createAgentSession —— 用 pi-agent-core.Agent + pi-ai Models 装配一个最小 agent session。
 *
 * 背景:旧实现依赖 `@earendil-works/pi-coding-agent` 的 `createAgentSession`,但该包
 * 的 core/* 静态 import 了 modes/interactive(含 utils/changelog.js);而 changelog.js
 * 在 Appwrite Functions 的 build 流程里被内置 MODCLEAN 裁掉,导致运行时
 * ERR_MODULE_NOT_FOUND。pi-agent-core 的 Agent 是 pi-coding-agent createAgentSession
 * 内部装配的核心组件(pi-coding-agent/sdk.js 直接 `new Agent({...})`),其事件类型
 * `AgentEvent` 与旧 `AgentSessionEvent` 同源,依赖图干净(0 命中 modes/interactive)。
 *
 * 本工厂只复刻 linkque-agent-runtime 真正用到的最小能力:把 Agent 包成暴露
 * subscribe/prompt/dispose 三方法的 session(与 StreamBridge 契约对齐),不套
 * pi-coding-agent 的 IAgentSession(compaction/branch/exportHtml/skills 等高阶能力本
 * runtime 都不用)。
 *
 * 认证:apiKey 经 `Agent.getApiKey` 回调注入(每次 LLM 调用前 agent-loop 解析),
 * 经 models.streamSimple → applyAuth → resolveProviderAuth 合成 credential 透传,
 * 无需 CredentialStore、不落盘(见 anthropicProviderBase 的 ApiKeyAuth.resolve)。
 */
import type { AgentTool } from '@earendil-works/pi-agent-core';
import type { Api, Model, MutableModels, AgentEvent, ThinkingLevel } from './types.js';
import type { IAgentToolDescriptor } from '../../../core/ports.js';
/**
 * 创建 agent session 的入参(重新定义,不再从 pi-coding-agent import)。
 *
 * 与旧 `ICreateAgentSessionOptions` 的差异:
 * - `modelRuntime` → `models`:pi-ai Models 实例(provider 注册其上,streamFn 委托它)。
 * - `sessionManager` 移除:本 runtime 每次 streamChat 独立 in-memory session,Agent
 *   自持 `_state.messages`,无持久化。
 * - 新增 `getApiKey`:运行时 apiKey 注入回调。
 * - `tools` 语义变化:上层传入环境无关 Descriptor，本工厂统一转换为
 *   pi-agent-core 的 `AgentTool[]`(带 execute 闭包)；缺省仍是纯对话。
 */
export interface ICreateAgentSessionOptions {
    /** 工作目录(本 runtime 默认不挂工具时仅作上下文,目前未实际透传给 Agent)。 */
    cwd?: string;
    /** 主模型(pi-ai Model 对象,由调用方从 Models 解析)。 */
    model: Model<Api>;
    /** 思考强度。缺省 'off'。 */
    thinkingLevel?: ThinkingLevel;
    /** Agent 系统提示词。缺省为空字符串。 */
    systemPrompt?: string;
    /**
     * 启用的环境无关工具描述；由本工厂转换成 pi-agent-core AgentTool。
     */
    tools?: IAgentToolDescriptor[];
    /** pi-ai Models 实例(provider 注册其上,streamFn 委托它做 streamSimple)。 */
    models: MutableModels;
    /** 运行时 apiKey 注入回调:每次 LLM 调用前由 agent-loop 解析。 */
    getApiKey: (provider: string) => Promise<string | undefined> | string | undefined;
}
/**
 * session 句柄:暴露 subscribe/prompt/dispose 三方法,与 StreamBridge 契约对齐。
 *
 * subscribe 对外暴露 pi-agent-core 的 {@link AgentEvent}(与旧 AgentSessionEvent 同源,
 * 但缺 agent_settled、agent_end 无 willRetry)。
 */
export interface IAgentSession {
    subscribe(listener: (event: AgentEvent) => void): () => void;
    prompt(text: string): Promise<void>;
    dispose(): void;
}
/** createAgentSession 的结果(保持与旧 API 形状兼容,modelFallbackMessage 预留)。 */
export interface ICreateAgentSessionResult {
    session: IAgentSession;
    /** 模型降级提示(当前恒为 undefined,保持与旧 API 形状兼容)。 */
    modelFallbackMessage?: string;
}
/** 建 session 的工厂类型(抽出便于单测注入 spy/stub)。 */
export type CreateAgentSession = (options: ICreateAgentSessionOptions) => Promise<ICreateAgentSessionResult>;
/**
 * 装配一个最小 agent session。
 *
 * streamFn 委托 `options.models.streamSimple`,保证 provider 注册 + auth 注入走 pi-ai
 * 路径;getApiKey 透传给 Agent,agent-loop 在每次 LLM 调用前解析 key 注入 streamFn
 * options.apiKey。initialState.tools 传空数组(对应纯对话)。
 *
 * @param options 见 {@link ICreateAgentSessionOptions}
 * @returns 含 session 句柄的结果
 */
export declare function createAgentSession(options: ICreateAgentSessionOptions): Promise<ICreateAgentSessionResult>;
/** 把环境无关 Tool Descriptor 转为 Pi AgentTool，保留执行信号与 UI details。 */
export declare function toPiAgentTools(descriptors: IAgentToolDescriptor[]): AgentTool[];