@kingdee-kcode/coding-agent 16.1.9

package/dist/types/plan-mode/approved-plan.d.ts

@@ -0,0 +1,68 @@
+/** Shape forwarded from the plan-mode resolve handler to InteractiveMode's
+ *  approval popup. Populated by the standing handler that the resolve tool
+ *  dispatches to when the agent submits `resolve { action: "apply" }`.
+ *  `planFilePath` is the agent-chosen `local://<slug>-plan.md` artifact — it is
+ *  never renamed on approval, so links to it stay valid for the session. */
+export interface PlanApprovalDetails {
+    planFilePath: string;
+    title: string;
+    planExists: boolean;
+}
+/** Validate and normalize the agent-supplied plan title into a safe filename stem.
+ *  Spaces and other URL-safe punctuation are replaced with hyphens so models that
+ *  produce natural-language titles (e.g. "My feature plan") still succeed.
+ *  Characters that cannot be safely represented after replacement are dropped.
+ *  The result is restricted to letters, numbers, underscores, and hyphens so it
+ *  is safe to splice into a `local://` URL without escaping. */
+export declare function normalizePlanTitle(title: string): {
+    title: string;
+    fileName: string;
+};
+/** Best-effort derivation of a plan title from inputs the agent already produced.
+ *  Returns the first non-empty candidate that survives `normalizePlanTitle`:
+ *    1. an explicit `suppliedTitle` (e.g. `extra.title` from the resolve call),
+ *    2. the first level-1 markdown heading inside `planContent`,
+ *    3. the filename stem of `planFilePath` (e.g. `PLAN` from `local://PLAN.md`),
+ *    4. the literal `"plan"` so callers never have to handle `null`.
+ *  The fallback exists because some grammar-constrained models cannot emit a
+ *  string into the open `extra` schema and instead drop in `{}` (issue #1179);
+ *  plan-mode would otherwise loop forever on an unreachable validation. */
+export declare function resolvePlanTitle(input: {
+    suppliedTitle?: unknown;
+    planContent: string;
+    planFilePath: string;
+}): {
+    title: string;
+    fileName: string;
+    source: "supplied" | "heading" | "filename" | "default";
+};
+/** Humanize a normalized plan title for use as a session display name.
+ *  Replaces `-`/`_` separators with spaces and capitalizes the first letter.
+ *  Returns an empty string when the input collapses to whitespace. */
+export declare function humanizePlanTitle(title: string): string;
+/** The `local://` URL a plan slug maps to. The agent writes the plan here and
+ *  passes the slug to `resolve`; the file is never renamed, so this URL — and
+ *  any hyperlink to it — stays valid for the life of the session. */
+export declare function planFileUrlForSlug(slug: string): string;
+export interface ResolveApprovedPlanInput {
+    /** The agent's `extra.title` from the `resolve` call, if any. */
+    suppliedTitle?: unknown;
+    /** The plan path recorded in plan-mode state (the entry default or a prior plan). */
+    statePlanFilePath: string;
+    /** Read a plan `local://` URL, returning null when the file does not exist. */
+    readPlan: (planUrl: string) => Promise<string | null>;
+    /** Optional fallback: list candidate plan `local://` URLs (newest first) so a
+     *  plan whose name can't be reconstructed (e.g. a dropped `extra.title`) is
+     *  still found. */
+    listPlanFiles?: () => Promise<string[]>;
+}
+export interface ResolvedApprovedPlan {
+    planFilePath: string;
+    planContent: string;
+    title: string;
+}
+/** Locate the plan file the agent wrote and finalize its title — without
+ *  renaming anything. Tries, in order: the slug derived from `extra.title`
+ *  (`local://<slug>-plan.md`), the plan path from plan-mode state, then a scan
+ *  of recent plan files. Throws a `ToolError` guiding the agent when none exist. */
+export declare function resolveApprovedPlan(input: ResolveApprovedPlanInput): Promise<ResolvedApprovedPlan>;

package/dist/types/plan-mode/plan-handoff.d.ts

@@ -0,0 +1,20 @@
+import { type LocalProtocolOptions } from "../internal-urls";
+/** The session's active plan, resolved for handoff into a subagent's context. */
+export interface OverallPlanReference {
+    /** The `local://` reference path (e.g. `local://my-feature.md`), kept for display. */
+    path: string;
+    /** The full plan markdown, as written to disk. */
+    content: string;
+}
+/**
+ * Load the session's active overall plan for subagent handoff.
+ *
+ * Returns the plan referenced by `planReferencePath` when it exists on disk with
+ * non-empty content, or `undefined` when there is no plan (the file is absent or
+ * empty). This mirrors `AgentSession.#buildPlanReferenceMessage`'s gating so a
+ * subagent sees exactly the plan the main agent treats as its active reference.
+ *
+ * Callers MUST skip this during plan mode itself — read-only plan exploration
+ * uses a different prompt and a draft plan should not be handed off as approved.
+ */
+export declare function loadOverallPlanReference(planReferencePath: string, localProtocolOptions: LocalProtocolOptions): Promise<OverallPlanReference | undefined>;

package/dist/types/plan-mode/plan-protection.d.ts

@@ -0,0 +1,12 @@
+import { type ProtectedToolContext } from "@oh-my-pi/pi-agent-core/compaction/tool-protection";
+/**
+ * Build a compaction protection matcher that keeps `read` results for the active
+ * plan file intact through prune/shake — the plan analog of skill-read
+ * protection. Matches both the canonical `local://PLAN.md` alias and the
+ * session's current plan reference path (the agent-chosen `local://<slug>-plan.md`),
+ * so the plan survives compaction whether the agent reads it by alias or by name.
+ *
+ * `getPlanReferencePath` is evaluated at match time so the plan path set on
+ * approval is honored immediately.
+ */
+export declare function createPlanReadMatcher(getPlanReferencePath: () => string): (context: ProtectedToolContext) => boolean;

package/dist/types/plan-mode/state.d.ts

@@ -0,0 +1,6 @@
+export interface PlanModeState {
+    enabled: boolean;
+    planFilePath: string;
+    workflow?: "parallel" | "iterative";
+    reentry?: boolean;
+}

package/dist/types/registry/agent-lifecycle.d.ts

@@ -0,0 +1,66 @@
+/**
+ * AgentLifecycleManager - Owns the idle → parked → revived lifecycle of
+ * adopted subagents.
+ *
+ * The task executor hands a finished agent over via {@link AgentLifecycleManager.adopt};
+ * from then on the manager arms a TTL timer whenever the agent goes `idle`,
+ * parks it on expiry (disposes the live session, keeps the AgentRef +
+ * sessionFile), and revives it on demand through
+ * {@link AgentLifecycleManager.ensureLive}. Only this manager flips
+ * `parked` ↔ `idle`.
+ */
+import type { AgentSession } from "../session/agent-session";
+import { type AgentRef, AgentRegistry } from "./agent-registry";
+export type AgentReviver = () => Promise<AgentSession>;
+/**
+ * Builds a reviver for a `parked` ref restored from disk (Agent Hub scan,
+ * collab mirror, resumed process) that carries a sessionFile but no in-memory
+ * adoption. Returns undefined when the ref cannot be faithfully rebuilt (no
+ * persisted session contract, or its workspace is gone). Injected from the
+ * top-level session so this manager stays free of sdk/SessionManager imports.
+ */
+export type PersistedSubagentReviverFactory = (ref: AgentRef) => Promise<AgentReviver | undefined>;
+export interface AdoptOptions {
+    /** TTL before an idle agent is parked. <= 0 disables parking. */
+    idleTtlMs: number;
+    /** Recreates a live AgentSession from the ref's sessionFile. Absent => not resumable after park (e.g. isolated runs). */
+    revive?: AgentReviver;
+}
+export declare class AgentLifecycleManager {
+    #private;
+    static global(): AgentLifecycleManager;
+    /** Reset the global manager. Test-only. */
+    static resetGlobalForTests(): void;
+    constructor(registry?: AgentRegistry);
+    /**
+     * Install the factory used to cold-revive `parked` refs restored from disk
+     * (Agent Hub scan, collab mirror, resumed process) — they carry a sessionFile
+     * but no adoption. Set by the top-level session, which owns the ambient deps
+     * (auth, models, MCP, artifacts) the factory needs at revive time.
+     */
+    setPersistedSubagentReviverFactory(factory: PersistedSubagentReviverFactory, idleTtlMs: number): void;
+    /**
+     * Take ownership of a finished subagent. Caller has already set registry
+     * status to "idle". Arms the TTL timer (idleTtlMs <= 0 adopts without one).
+     */
+    adopt(id: string, opts: AdoptOptions): void;
+    /** True if the id is adopted (parked or live). */
+    has(id: string): boolean;
+    /** True while {@link park} is disposing this agent's session (lets dispose hooks distinguish park from teardown). */
+    isParking(id: string): boolean;
+    /**
+     * Dispose the live session, detach it from the registry, and mark the
+     * agent `parked`. No-op unless the id is adopted and live.
+     */
+    park(id: string): Promise<void>;
+    /**
+     * Return the live session, reviving from the sessionFile if parked.
+     * Throws a plain Error if the id is unknown or parked without a reviver.
+     * Concurrent calls share one in-flight revive.
+     */
+    ensureLive(id: string): Promise<AgentSession>;
+    /** Hard removal: dispose if live, unregister from registry, drop timers. */
+    release(id: string): Promise<void>;
+    /** Teardown everything (process exit / main session dispose). */
+    dispose(): Promise<void>;
+}

package/dist/types/registry/agent-registry.d.ts

@@ -0,0 +1,97 @@
+/**
+ * AgentRegistry - Process-global registry of agents (the main session plus
+ * every subagent), keyed by stable id.
+ *
+ * Tracks each agent's status and (when live) its AgentSession so peers can be
+ * addressed by id (`irc`, `task resume`, `history://`). Sessions are
+ * registered explicitly at creation; finished agents stay registered as
+ * `idle` (live) or `parked` (session disposed, ref + sessionFile retained for
+ * revival) and are only removed on explicit release/teardown.
+ */
+import type { AgentSession } from "../session/agent-session";
+export declare const MAIN_AGENT_ID = "Main";
+/**
+ * - `running`: a turn is in flight.
+ * - `idle`: live AgentSession in memory, awaiting work. Finished agents are
+ *   `idle`, not removed.
+ * - `parked`: session disposed; AgentRef + sessionFile retained, revivable.
+ * - `aborted`: hard-killed, terminal.
+ */
+export type AgentStatus = "running" | "idle" | "parked" | "aborted";
+/**
+ * - `main`/`sub`: the user-facing agent tree (driving agent + task subagents).
+ * - `advisor`: a passive review transcript persisted like a subagent for usage
+ *   attribution and Agent Hub observability, but never a peer — hidden from
+ *   agent-facing rosters (`irc`, `history://`) and not messageable/revivable.
+ */
+export type AgentKind = "main" | "sub" | "advisor";
+export interface AgentRef {
+    id: string;
+    displayName: string;
+    kind: AgentKind;
+    parentId?: string;
+    status: AgentStatus;
+    /** Null exactly when parked/aborted. */
+    session: AgentSession | null;
+    sessionFile: string | null;
+    createdAt: number;
+    lastActivity: number;
+    /** Short gist of what the agent is currently doing (latest intent or tool), for the work-aware roster. Display-only. */
+    activity?: string;
+}
+export type RegistryEvent = {
+    type: "registered";
+    ref: AgentRef;
+} | {
+    type: "status_changed";
+    ref: AgentRef;
+} | {
+    type: "removed";
+    ref: AgentRef;
+};
+type RegistryListener = (event: RegistryEvent) => void;
+export interface RegisterInput {
+    id: string;
+    displayName: string;
+    kind: AgentKind;
+    parentId?: string;
+    session: AgentSession | null;
+    sessionFile?: string | null;
+    status?: AgentStatus;
+}
+export declare class AgentRegistry {
+    #private;
+    static global(): AgentRegistry;
+    /** Reset the global registry. Test-only. */
+    static resetGlobalForTests(): void;
+    register(input: RegisterInput): AgentRef;
+    setStatus(id: string, status: AgentStatus): void;
+    /**
+     * Record a short activity gist for the work-aware roster. Display-only and
+     * read on demand (`irc list`, peer roster), so it emits no event — keeping
+     * the per-tool-call update rate off the registry listener path (same as
+     * `attachSession`, which also bumps `lastActivity` without emitting). Only a
+     * `running` agent has current work: a heartbeat for any other status is
+     * dropped, so a late progress flush can't resurrect activity on a ref that
+     * `setStatus` just cleared. Every running heartbeat refreshes `lastActivity`
+     * — even when the gist text is unchanged — so the roster's "active … ago" and
+     * recency sort track real work, not just the last status change.
+     * The gist is normalized to one bounded line (`oneLineLabel`) so model-derived
+     * intent text can neither break the roster nor smuggle terminal escapes —
+     * every caller is safe without sanitizing at its own call site.
+     */
+    setActivity(id: string, activity: string): void;
+    attachSession(id: string, session: AgentSession, sessionFile?: string | null): void;
+    detachSession(id: string): void;
+    unregister(id: string): void;
+    get(id: string): AgentRef | undefined;
+    list(): AgentRef[];
+    /**
+     * Returns every alive agent (running | idle) except the caller. Advisor refs
+     * are observability-only transcripts, never peers, so they are excluded.
+     * Flat namespace: every other agent is visible.
+     */
+    listVisibleTo(id: string): AgentRef[];
+    onChange(listener: RegistryListener): () => void;
+}
+export {};

package/dist/types/sdk.d.ts

@@ -0,0 +1,360 @@
+import { type AgentTelemetryConfig, type ThinkingLevel } from "@oh-my-pi/pi-agent-core";
+import { type Model } from "@oh-my-pi/pi-ai";
+import type { Dialect } from "@oh-my-pi/pi-ai/dialect";
+import { type Rule } from "./capability/rule";
+import { ModelRegistry } from "./config/model-registry";
+import { type PromptTemplate } from "./config/prompt-templates";
+import { Settings, type SkillsSettings } from "./config/settings";
+import "./discovery";
+import { type CustomCommandsLoadResult } from "./extensibility/custom-commands";
+import { type ToolPathWithSource } from "./extensibility/custom-tools";
+import type { CustomTool } from "./extensibility/custom-tools/types";
+import { type ExtensionFactory, type ExtensionUIContext, type LoadExtensionsResult, type ToolDefinition } from "./extensibility/extensions";
+import { type Skill, type SkillWarning } from "./extensibility/skills";
+import { type FileSlashCommand } from "./extensibility/slash-commands";
+import type { HindsightSessionState } from "./hindsight/state";
+import { type LocalProtocolOptions } from "./internal-urls";
+import { MCPManager, type MCPToolsLoadResult } from "./mcp";
+import type { MnemopiSessionState } from "./mnemopi/state";
+import { AgentRegistry } from "./registry/agent-registry";
+import { AgentSession } from "./session/agent-session";
+import type { AuthStorage } from "./session/auth-storage";
+import { SessionManager } from "./session/session-manager";
+import { type BuildSystemPromptResult } from "./system-prompt";
+import { type ConfiguredThinkingLevel } from "./thinking";
+import { BashTool, BUILTIN_TOOLS, createTools, EditTool, EvalTool, FindTool, HIDDEN_TOOLS, type LspStartupServerInfo, loadSshTool, ReadTool, ResolveTool, SearchTool, type Tool, type ToolSession, WebSearchTool, WriteTool } from "./tools";
+import { EventBus } from "./utils/event-bus";
+import { type WorkspaceTree } from "./workspace-tree";
+export interface CreateAgentSessionOptions {
+    /** Working directory for project-local discovery. Default: getProjectDir() */
+    cwd?: string;
+    /** Global config directory. Default: ~/.kcode/agent */
+    agentDir?: string;
+    /** Spawns to allow. Default: "*" */
+    spawns?: string;
+    /** Auth storage for credentials. Default: discoverAuthStorage(agentDir) */
+    authStorage?: AuthStorage;
+    /** Model registry. Default: discoverModels(authStorage, agentDir) */
+    modelRegistry?: ModelRegistry;
+    /** Model to use. Default: from settings, else first available */
+    model?: Model;
+    /** Raw model pattern string (e.g. from --model CLI flag) to resolve after extensions load.
+     * Used when model lookup is deferred because extension-provided models aren't registered yet. */
+    modelPattern?: string;
+    /** Thinking selector. Default: from settings, else unset */
+    thinkingLevel?: ConfiguredThinkingLevel;
+    /** Models available for cycling (Ctrl+P in interactive mode) */
+    scopedModels?: Array<{
+        model: Model;
+        thinkingLevel?: ThinkingLevel;
+    }>;
+    /** Provider-facing system prompt override. Replaces the fully rendered default blocks. */
+    systemPrompt?: string | string[] | ((defaultPrompt: string[]) => string | string[]);
+    /** Already-loaded custom prompt text rendered through the bundled custom system prompt template. */
+    customSystemPrompt?: string;
+    /** Already-loaded text appended through the bundled system prompt templates. */
+    appendSystemPrompt?: string;
+    /** Optional provider-facing session identifier for prompt caches and sticky auth selection.
+     * Keeps persisted session files isolated while reusing provider-side caches. */
+    providerSessionId?: string;
+    /** Optional provider-facing prompt cache key, distinct from request lineage. */
+    providerPromptCacheKey?: string;
+    /** Absolute wall-clock deadline in Unix epoch milliseconds. */
+    deadline?: number;
+    /** Custom tools to register (in addition to built-in tools). Accepts both CustomTool and ToolDefinition. */
+    customTools?: (CustomTool | ToolDefinition)[];
+    /** Inline extensions (merged with discovery). */
+    extensions?: ExtensionFactory[];
+    /** Additional extension paths to load (merged with discovery). */
+    additionalExtensionPaths?: string[];
+    /** Disable extension discovery (explicit paths still load). */
+    disableExtensionDiscovery?: boolean;
+    /**
+     * Pre-loaded extensions (skips file discovery and the per-session factory
+     * call). Used by the CLI when extensions are loaded early to parse custom
+     * flags — the same process owns the returned instances, so reusing them is
+     * safe.
+     *
+     * NEVER pass this across session boundaries (e.g. parent → subagent).
+     * `Extension` instances close over a parent-bound `ExtensionAPI` (cwd,
+     * eventBus, runtime), and reusing them would route tools/handlers/commands
+     * back through the parent. For subagents, forward
+     * {@link preloadedExtensionPaths} instead.
+     *
+     * @internal
+     */
+    preloadedExtensions?: LoadExtensionsResult;
+    /**
+     * Pre-discovered extension source paths. When provided, the filesystem-scan
+     * inside `discoverExtensionPaths()` is skipped — the session still calls
+     * `loadExtensions()` itself so each `Extension` is bound to THIS session's
+     * `ExtensionAPI` (cwd, eventBus, runtime).
+     *
+     * This is the safe pass-through for parent → subagent forwarding.
+     */
+    preloadedExtensionPaths?: string[];
+    /**
+     * Pre-discovered custom-tool source paths from `.kcode/tools/`, `.claude/tools/`,
+     * plugins, etc. When provided, the filesystem-scan inside
+     * `discoverCustomToolPaths()` is skipped — subagents inherit the parent's
+     * scan result and call `loadCustomTools()` themselves so each session binds
+     * tools to its OWN `CustomToolAPI` (cwd, exec, pushPendingAction, UI).
+     *
+     * Forwarding the loaded `LoadedCustomTool[]` instances directly would reuse
+     * the parent's session-bound API and route tool execution back through the
+     * parent — wrong for isolated tasks and for pending-action routing.
+     */
+    preloadedCustomToolPaths?: ToolPathWithSource[];
+    /** Shared event bus for tool/extension communication. Default: creates new bus. */
+    eventBus?: EventBus;
+    /** Skills. Default: discovered from multiple locations */
+    skills?: Skill[];
+    /** Rules. Default: discovered from multiple locations */
+    rules?: Rule[];
+    /** Context files (AGENTS.md content). Default: discovered walking up from cwd */
+    contextFiles?: Array<{
+        path: string;
+        content: string;
+    }>;
+    /** Pre-built workspace tree (skips re-scanning; passed by parents to subagents). */
+    workspaceTree?: WorkspaceTree;
+    /** Prompt templates. Default: discovered from cwd/.kcode/prompts/ + agentDir/prompts/ */
+    promptTemplates?: PromptTemplate[];
+    /** File-based slash commands. Default: discovered from commands/ directories */
+    slashCommands?: FileSlashCommand[];
+    /** Enable MCP server discovery from .mcp.json files. Default: true */
+    enableMCP?: boolean;
+    /** Existing MCP manager to reuse (skips discovery, propagates to toolSession). */
+    mcpManager?: MCPManager;
+    /** Enable LSP integration (tool, formatting, diagnostics, warmup). Default: true */
+    enableLsp?: boolean;
+    /** Skip Python kernel availability check and prelude warmup */
+    skipPythonPreflight?: boolean;
+    /** Tool names explicitly requested (enables disabled-by-default tools) */
+    toolNames?: string[];
+    /** Output schema for structured completion (subagents) */
+    outputSchema?: unknown;
+    /** Whether to include the yield tool by default */
+    requireYieldTool?: boolean;
+    /** Task recursion depth (for subagent sessions). Default: 0 */
+    taskDepth?: number;
+    /** Parent Hindsight state to alias for subagent memory tools. */
+    parentHindsightSessionState?: HindsightSessionState;
+    /** Parent Mnemopi state to alias for subagent memory tools. */
+    parentMnemopiSessionState?: MnemopiSessionState;
+    /** Pre-allocated agent identity for IRC routing. Default: "Main" for top-level, parentTaskPrefix-derived for sub. */
+    agentId?: string;
+    /** Display name for the agent in IRC. Default: "main" or "sub". */
+    agentDisplayName?: string;
+    /** Optional shared agent registry for IRC routing. Default: AgentRegistry.global(). */
+    agentRegistry?: AgentRegistry;
+    /** Parent task ID prefix for nested artifact naming (e.g., "Extensions") */
+    parentTaskPrefix?: string;
+    /**
+     * Registry id of the spawning agent, recorded as this subagent's parent in
+     * the agent registry. Distinct from `parentTaskPrefix`, which is this agent's
+     * own artifact/output-id prefix (the executor passes the child's own id
+     * there, so it must never double as the parent link). Undefined for the
+     * top-level "Main" session, which has no parent.
+     */
+    parentAgentId?: string;
+    /** Inherited eval executor session id for subagents sharing parent eval state. */
+    parentEvalSessionId?: string;
+    /** Session manager. Default: session stored under the configured agentDir sessions root */
+    sessionManager?: SessionManager;
+    /** Override local:// protocol options for subagent local:// sharing. Default: uses the session's own artifacts dir and session ID. */
+    localProtocolOptions?: LocalProtocolOptions;
+    /** Settings instance. Default: Settings.init({ cwd, agentDir }) */
+    settings?: Settings;
+    /**
+     * Legacy alias for `settings`. Older Pi extensions pass SettingsManager.create(...)
+     * through this field; accept it so their SDK calls keep the configured settings.
+     */
+    settingsManager?: Settings | Promise<Settings>;
+    /** Whether UI is available (enables interactive tools like ask). Default: false */
+    hasUI?: boolean;
+    /**
+     * Opt-in OpenTelemetry instrumentation forwarded to the underlying Agent.
+     * Passing `{}` enables the loop's GenAI-semantic-convention spans. See
+     * {@link AgentTelemetryConfig} for the full surface (hooks, content capture,
+     * cost estimator, agent identity).
+     *
+     * Safe to enable without an OTEL SDK registered in the host: the
+     * `@opentelemetry/api` package returns a no-op tracer in that case.
+     */
+    telemetry?: AgentTelemetryConfig;
+    /**
+     * Fired once, when the agent loop hands its first request to the provider
+     * transport (i.e. the `streamFn` wrapper is first invoked). Used to measure
+     * subagent launch latency — the boundary between "session built" and "model
+     * call dispatched". This is the loop's dispatch point, slightly before the
+     * actual provider HTTP call (per-request prep, identical across all
+     * requests, follows it), which is the right granularity for launch timing.
+     */
+    onFirstChatDispatch?: () => void;
+    /** Whether to auto-approve all tool calls (--auto-approve CLI flag). Default: false */
+    autoApprove?: boolean;
+}
+/** Result from createAgentSession */
+export interface CreateAgentSessionResult {
+    /** The created session */
+    session: AgentSession;
+    /** Extensions result (loaded extensions + runtime) */
+    extensionsResult: LoadExtensionsResult;
+    /** Update tool UI context (interactive mode) */
+    setToolUIContext: (uiContext: ExtensionUIContext, hasUI: boolean) => void;
+    /** MCP manager for server lifecycle management (undefined if MCP disabled) */
+    mcpManager?: MCPManager;
+    /** Warning if session was restored with a different model than saved */
+    modelFallbackMessage?: string;
+    /** LSP servers detected for startup; warmup may continue in the background */
+    lspServers?: LspStartupServerInfo[];
+    /** Shared event bus for tool/extension communication */
+    eventBus: EventBus;
+}
+export type DialectFormat = "auto" | "native" | Dialect;
+export declare function resolveDialect(format: DialectFormat, model: (Pick<Model, "supportsTools"> & Partial<Pick<Model, "id">>) | undefined): Dialect | undefined;
+export type { PromptTemplate } from "./config/prompt-templates";
+export { Settings, type SkillsSettings } from "./config/settings";
+export type { CustomCommand, CustomCommandFactory } from "./extensibility/custom-commands/types";
+export type { CustomTool, CustomToolFactory } from "./extensibility/custom-tools/types";
+export type * from "./extensibility/extensions";
+export type { Skill } from "./extensibility/skills";
+export type { FileSlashCommand } from "./extensibility/slash-commands";
+export type { MCPManager, MCPServerConfig, MCPServerConnection, MCPToolsLoadResult } from "./mcp";
+export type { Tool } from "./tools";
+export { buildDirectoryTree, buildWorkspaceTree, type DirectoryTree, type WorkspaceTree } from "./workspace-tree";
+export { BashTool, BUILTIN_TOOLS, createTools, EditTool, EvalTool, FindTool, HIDDEN_TOOLS, loadSshTool, ReadTool, ResolveTool, SearchTool, type ToolSession, WebSearchTool, WriteTool, };
+/**
+ * Create an AuthStorage instance.
+ *
+ * Default: local SQLite store at `<agentDir>/agent.db`.
+ *
+ * Broker mode: when `KCODE_AUTH_BROKER_URL` is set, credentials are pulled from
+ * a remote auth-broker over the wire. Refresh tokens never leave the broker;
+ * the client receives access tokens with `refresh = "__remote__"` and calls
+ * back into the broker through the {@link AuthStorageOptions.refreshOAuthCredential}
+ * override to re-mint access tokens when needed.
+ *
+ * Delegates to {@link ./session/auth-broker-config} so the TUI and the catalog
+ * generator share the same credential-discovery logic.
+ */
+export declare function discoverAuthStorage(agentDir?: string): Promise<AuthStorage>;
+/**
+ * Discover extensions from cwd.
+ */
+export declare function discoverExtensions(cwd?: string): Promise<LoadExtensionsResult>;
+/**
+ * Path-only counterpart of {@link loadSessionExtensions}: the FS-heavy scan
+ * without the per-session module load. Subagents reuse the parent's path list
+ * (cached on {@link ToolSession.extensionPaths}) and rebuild Extension
+ * instances themselves so each session's `ExtensionAPI` (cwd, eventBus,
+ * runtime) is its own.
+ */
+export declare function discoverSessionExtensionPaths(options: Pick<CreateAgentSessionOptions, "disableExtensionDiscovery" | "additionalExtensionPaths">, cwd: string, settings: Settings): Promise<string[]>;
+/**
+ * Load the discovered/configured extensions for a session — everything {@link
+ * createAgentSession} would load except the inline factory extensions it appends
+ * itself. Extracted so the CLI can resolve extension-registered flags (and thus
+ * classify `@file` arguments extension-aware) *before* a session — and its
+ * terminal breadcrumb — is created, then hand the result back through
+ * {@link CreateAgentSessionOptions.preloadedExtensions} so the work is not
+ * repeated. Keep this the single source of the discovery branch logic.
+ */
+export declare function loadSessionExtensions(options: Pick<CreateAgentSessionOptions, "disableExtensionDiscovery" | "additionalExtensionPaths">, cwd: string, settings: Settings, eventBus: EventBus): Promise<LoadExtensionsResult>;
+/**
+ * Load discovered/configured extensions and register their providers into
+ * `modelRegistry`, then discover the dynamic provider catalogs. One-shot CLIs
+ * (`kcode bench`, dry-balance) build a bare {@link ModelRegistry} that only knows
+ * built-in catalog providers; without this, providers contributed by an
+ * extension (e.g. a custom OpenAI-compatible provider under
+ * `~/.kcode/agent/extensions/`) never reach model resolution. Mirrors the
+ * session / `kcode models` path: drain the queued provider registrations, then
+ * `refreshRuntimeProviders` so dynamically-discovered models exist before
+ * selectors are resolved.
+ */
+export declare function loadCliExtensionProviders(modelRegistry: ModelRegistry, settings: Settings, cwd: string, options?: Pick<CreateAgentSessionOptions, "disableExtensionDiscovery" | "additionalExtensionPaths">): Promise<void>;
+/**
+ * Discover skills from cwd and agentDir.
+ */
+export declare function discoverSkills(cwd?: string, _agentDir?: string, settings?: SkillsSettings): Promise<{
+    skills: Skill[];
+    warnings: SkillWarning[];
+}>;
+/**
+ * Discover context files (AGENTS.md) walking up from cwd.
+ * Returns files sorted by depth (farther from cwd first, so closer files appear last/more prominent).
+ */
+export declare function discoverContextFiles(cwd?: string, _agentDir?: string): Promise<Array<{
+    path: string;
+    content: string;
+    depth?: number;
+}>>;
+/**
+ * Discover prompt templates from cwd and agentDir.
+ */
+export declare function discoverPromptTemplates(cwd?: string, agentDir?: string): Promise<PromptTemplate[]>;
+/**
+ * Discover file-based slash commands from commands/ directories.
+ */
+export declare function discoverSlashCommands(cwd?: string): Promise<FileSlashCommand[]>;
+/**
+ * Discover custom commands (TypeScript slash commands) from cwd and agentDir.
+ */
+export declare function discoverCustomTSCommands(cwd?: string, agentDir?: string): Promise<CustomCommandsLoadResult>;
+/**
+ * Discover MCP servers from .mcp.json files.
+ * Returns the manager and loaded tools.
+ */
+export declare function discoverMCPServers(cwd?: string): Promise<MCPToolsLoadResult>;
+export interface BuildSystemPromptOptions {
+    tools?: Tool[];
+    skills?: Skill[];
+    contextFiles?: Array<{
+        path: string;
+        content: string;
+    }>;
+    cwd?: string;
+    customPrompt?: string;
+    appendPrompt?: string;
+    inlineToolDescriptors?: boolean;
+}
+/**
+ * Build the default provider-facing system prompt blocks.
+ *
+ * The returned `systemPrompt` preserves the stable harness prompt and dynamic project context
+ * as separate entries so providers can cache prompt prefixes without concatenating blocks.
+ */
+export declare function buildSystemPrompt(options?: BuildSystemPromptOptions): Promise<BuildSystemPromptResult>;
+/**
+ * Create an AgentSession with the specified options.
+ *
+ * @example
+ * ```typescript
+ * // Minimal - uses defaults
+ * const { session } = await createAgentSession();
+ *
+ * // With explicit model
+ * import { getModel } from '@oh-my-pi/pi-ai';
+ * const { session } = await createAgentSession({
+ *   model: getModel('anthropic', 'claude-opus-4-5'),
+ *   thinkingLevel: 'high',
+ * });
+ *
+ * // Continue previous session
+ * const { session, modelFallbackMessage } = await createAgentSession({
+ *   continueSession: true,
+ * });
+ *
+ * // Full control
+ * const { session } = await createAgentSession({
+ *   model: myModel,
+ *   getApiKey: async () => Bun.env.MY_KEY,
+ *   systemPrompt: ['You are helpful.'],
+ *   tools: codingTools({ cwd: getProjectDir() }),
+ *   skills: [],
+ *   sessionManager: SessionManager.inMemory(),
+ * });
+ * ```
+ */
+export declare function createAgentSession(options?: CreateAgentSessionOptions): Promise<CreateAgentSessionResult>;

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

@@ -0,0 +1,9 @@
+import type { SecretEntry } from "./obfuscator";
+export { deobfuscateSessionContext, obfuscateMessages, obfuscateProviderContext, obfuscateProviderTools, type SecretEntry, SecretObfuscator, } from "./obfuscator";
+/**
+ * Load secrets from project-local and global secrets.yml files.
+ * Project-local entries override global entries with matching content.
+ */
+export declare function loadSecrets(cwd: string, agentDir: string): Promise<SecretEntry[]>;
+/** Collect environment variable values that look like secrets. */
+export declare function collectEnvSecrets(): SecretEntry[];