@ordewell/core 0.4.0

package/dist/ITerminalRunner-Bbpe8uts.d.ts

@@ -0,0 +1,535 @@
+import { h as RunnerId } from './Task-1NwmUImI.js';
+
+/**
+ * The planner's single approval seam. Every capability that reaches beyond the
+ * default read-only, in-workspace envelope — a path outside the workspace root,
+ * a shell command outside the auto-allowed set, a URL fetch — routes through
+ * one `request()` so the policy has exactly one owner (the same "one repair
+ * owner" shape as PlanRepair).
+ *
+ * Surfaces supply the human channel. VS Code answers with a modal; the web
+ * server currently has no prompt UI, so it denies unless the scope was
+ * pre-approved through config. Denial is always a visible, actionable tool
+ * result — never a silent success.
+ */
+type ApprovalKind = 'external_path' | 'shell_command' | 'url_fetch';
+interface ApprovalRequest {
+    kind: ApprovalKind;
+    /** The concrete thing being asked about: an absolute path, a command line, a URL. */
+    subject: string;
+    /**
+     * What a grant covers. Approving remembers this, not `subject`, so reading a
+     * second file from an already-approved directory does not prompt again.
+     */
+    scope: string;
+    /** One-line context for the prompt. */
+    detail?: string;
+}
+interface IApproval {
+    request(req: ApprovalRequest): Promise<boolean>;
+}
+/** Denies everything. The safe default when a surface wires no approval channel. */
+declare const DENY_ALL: IApproval;
+
+interface ToolOutcome {
+    success: boolean;
+    output: string;
+    truncated: boolean;
+}
+interface ReadFileOpts {
+    maxBytes?: number;
+    offset?: number;
+    limit?: number;
+}
+/**
+ * `content` returns matching lines, `files` only the paths that matched, and
+ * `count` a per-file tally. Cheap models otherwise grep and then read whole
+ * files to answer "which files touch this", burning rounds against the budget.
+ */
+type GrepOutputMode = 'content' | 'files' | 'count';
+interface GrepOptions {
+    /** File glob filter, e.g. `*.ts`. */
+    include?: string;
+    /** Search root. Relative to the workspace unless approved as external. */
+    path?: string;
+    outputMode?: GrepOutputMode;
+    /** Lines of context around each match (`content` mode only). */
+    contextBefore?: number;
+    contextAfter?: number;
+    /** Treat the pattern as a literal string rather than a regex. */
+    literal?: boolean;
+    caseInsensitive?: boolean;
+    /** Global cap on returned rows. Defaults to {@link GREP_DEFAULT_HEAD_LIMIT}. */
+    headLimit?: number;
+}
+interface GlobOptions {
+    /** Search root. Relative to the workspace unless approved as external. */
+    path?: string;
+    headLimit?: number;
+}
+interface FindSymbolOptions {
+    /** Language id or file extension, e.g. `typescript` or `.go`. Narrows the keyword set. */
+    language?: string;
+    /** Search root. Relative to the workspace unless approved as external. */
+    path?: string;
+}
+/** Global row cap for grep. A per-file cap is not a budget — see PoolFileSystem. */
+declare const GREP_DEFAULT_HEAD_LIMIT = 100;
+/**
+ * Directories that are never interesting to a planner and would otherwise eat
+ * the result budget. Applied by every search entry point, not just `glob` —
+ * `dist/` and `.ordewell/` are frequently not gitignored.
+ */
+declare const SEARCH_EXCLUSIONS: string[];
+interface IFileSystem {
+    readFile(path: string, opts?: ReadFileOpts): Promise<ToolOutcome>;
+    readFiles(paths: string[]): Promise<ToolOutcome>;
+    glob(pattern: string, opts?: GlobOptions): Promise<ToolOutcome>;
+    grep(pattern: string, opts?: GrepOptions): Promise<ToolOutcome>;
+    listDir(path: string, depth?: number): Promise<ToolOutcome>;
+    bash(command: string): Promise<ToolOutcome>;
+    /** Definition-first lookup for one symbol. See `symbolPatterns.ts`. */
+    findSymbol(symbol: string, opts?: FindSymbolOptions): Promise<ToolOutcome>;
+    getWorkspaceRoot(): string;
+    /**
+     * Inject the human-approval channel for out-of-envelope access. Optional so
+     * test doubles stay small; every adapter extending `BaseFileSystem` has it.
+     */
+    setApproval?(approval: IApproval): void;
+}
+
+/**
+ * Decides whether one out-of-envelope capability may run, and remembers the
+ * answer for the rest of the session.
+ *
+ * Grants are keyed on {@link ApprovalRequest.scope}, never on the concrete
+ * subject: approving a read of `/tmp/foo/a.log` grants `/tmp/foo/*`, and
+ * approving `az group list` grants `az group`. Without that, a planner doing
+ * real research would prompt on every single call and the feature would be
+ * unusable.
+ *
+ * `mode` is the policy floor:
+ *   ask     consult the human channel; no channel means deny (headless, web)
+ *   allow   grant everything the tier system did not already refuse
+ *   deny    grant nothing beyond `preApproved`
+ *
+ * Note the ordering: `preApproved` is honored under every mode including
+ * `deny`, because it is an explicit operator decision rather than a default.
+ */
+type ApprovalMode = 'ask' | 'allow' | 'deny';
+interface ApprovalPolicyOptions {
+    mode?: ApprovalMode;
+    /** Scopes granted up front from config. A trailing `*` matches by prefix. */
+    preApproved?: string[];
+    /** The human channel. Absent means there is nobody to ask. */
+    ask?: (req: ApprovalRequest) => Promise<boolean>;
+    /** Called whenever a decision is reached, for surfacing in a UI or a log. */
+    onDecision?: (req: ApprovalRequest, granted: boolean, source: ApprovalSource) => void;
+}
+type ApprovalSource = 'pre-approved' | 'remembered' | 'mode' | 'asked' | 'no-channel';
+declare class ApprovalPolicy implements IApproval {
+    private readonly mode;
+    private readonly preApproved;
+    private readonly asker?;
+    private readonly onDecision?;
+    private readonly granted;
+    private readonly refused;
+    /** One in-flight ask per scope: a parallel tool round must not prompt twice for the same thing. */
+    private readonly inFlight;
+    private generation;
+    constructor(opts?: ApprovalPolicyOptions);
+    request(req: ApprovalRequest): Promise<boolean>;
+    /** Scopes the user has granted this session — for display and for persistence. */
+    grantedScopes(): string[];
+    /** Drop every session-scoped decision. Called on session reset. */
+    reset(): void;
+}
+
+interface CatalogModel {
+    id: string;
+    name: string;
+    description: string;
+    pricing: {
+        prompt: string;
+        completion: string;
+    };
+    contextLength: number;
+}
+declare class ModelCatalog {
+    static fetchModels(apiKey: string, baseUrl?: string, fetchImpl?: typeof fetch): Promise<CatalogModel[]>;
+    /**
+     * Delete the on-disk catalog cache for a base URL so the next fetch re-runs.
+     * Used by the resolver's `invalidate()` in production (no injected fetch);
+     * best-effort — a missing file or unreadable dir is a no-op.
+     */
+    static clearCache(baseUrl?: string): void;
+    private static readCache;
+    private static writeCache;
+}
+
+interface ModelShortcut {
+    label: string;
+    id: string;
+    provider: string;
+    description: string;
+    pricing?: string;
+}
+declare const ORCHESTRATOR_SHORTCUTS: ModelShortcut[];
+declare function resolveModelShortcut(input: string, shortcuts: ModelShortcut[]): string | null;
+/**
+ * Resolves a value to a model id ONLY when it is in the supplied catalog
+ * option list — either directly or via a shortcut label. Free-typed, unknown,
+ * or not-currently-available values return null, so callers never store an id
+ * the user couldn't have selected from the list. Keeps model-setting list-only.
+ */
+declare function knownModelId(value: string, optionIds: string[], shortcuts: ModelShortcut[]): string | null;
+
+type ProviderModelLists = Record<string, string[]>;
+interface OrchestratorOption {
+    id: string;
+    label: string;
+    provider: string;
+    apiProvider: AiProvider;
+    description?: string;
+    pricing?: string;
+}
+
+interface FetchAllProviderModelsOptions {
+    apiKeys: Record<string, string>;
+    baseUrls: Record<string, string>;
+    fetchImpl?: typeof fetch;
+}
+type AllProviderModels = Record<string, CatalogModel[]>;
+/**
+ * Result of a picker-catalog fetch fan-out: the per-provider model lists plus
+ * the per-provider failures. `errors` is keyed by provider id and holds the
+ * failure message for any provider whose catalog fetch rejected — the seam the
+ * surfaces (CLI, VS Code) use to flag "this configured provider didn't work"
+ * rather than silently showing a short list.
+ */
+interface ProviderModelsResult {
+    models: AllProviderModels;
+    errors: Record<string, string>;
+}
+/** The provider config fields the discovery fan-out needs. */
+interface ProviderCredentialSource {
+    getProviderApiKey(provider: AiProvider): string;
+    getProviderBaseUrl(provider: AiProvider): string;
+    openaiCompatibleBaseUrl: string;
+}
+/**
+ * Collect the API keys and base URLs the picker fan-out should probe, applying
+ * the single "configured" policy shared by every surface (CLI + VS Code):
+ *  - a preset is discovered only when it has an API key (OpenRouter included —
+ *    its public catalog is not probed keyless, matching the product rule that
+ *    only key-configured providers appear);
+ *  - `openai_compatible` is discovered only when an explicit endpoint is set
+ *    (keyless local servers like ollama / LM Studio).
+ * Base URLs are handed through only for providers that pass the gate, so the
+ * fan-out never touches an unconfigured third-party endpoint.
+ */
+declare function collectProviderCredentials(config: ProviderCredentialSource): {
+    apiKeys: Record<string, string>;
+    baseUrls: Record<string, string>;
+};
+declare function fetchAllProviderModels(opts: FetchAllProviderModelsOptions): Promise<ProviderModelsResult>;
+declare function resolveProvider(modelId: string, providerModelLists: Record<string, string[]>): AiProvider | null;
+declare function toOrchestratorOptions(providerModels: AllProviderModels, shortcuts: ModelShortcut[]): OrchestratorOption[];
+
+/**
+ * Who plans. Mostly LLM vendors reached over HTTP; the last three are *harness
+ * planners* (ADR-0009) — a coding agent CLI already installed on the machine,
+ * driven as the planner over its own programmatic transport and authenticated
+ * by the subscription the user already holds. They are runners in the provider
+ * axis, deliberately: "what plans for me?" is one question, and it belongs in
+ * one setting. `isCliProvider` is the single guard that tells the two kinds
+ * apart.
+ */
+type AiProvider = 'google' | 'openrouter' | 'openai_compatible' | 'openai' | 'xai' | 'groq' | 'deepseek' | 'together' | 'mistral' | 'anthropic' | 'fireworks' | 'perplexity' | 'zhipu' | 'kimi' | 'cerebras' | 'deepinfra' | 'doubao' | 'qwen' | 'hunyuan' | 'baichuan' | 'minimax' | 'yi' | 'stepfun' | 'siliconflow' | 'cohere' | 'novita' | 'claude-code' | 'codex' | 'opencode';
+interface IConfig {
+    aiProvider: AiProvider;
+    apiKey: string;
+    planningModel: string;
+    enabledRunners: string[];
+    maxParallelSessions: number;
+    researchEnabled: boolean;
+    researchMaxSteps: number;
+    researchMaxFileSize: number;
+    openAiBaseUrl: string;
+    openAiApiKey: string;
+    /** Provider keys + base URL the ModelResolver uses to fetch the picker catalogs. */
+    openrouterKey: string;
+    geminiKey: string;
+    geminiBaseUrl?: string;
+    /** Base URL + API key for a user-provided OpenAI-compatible endpoint (ollama, vLLM, LM Studio, etc.). */
+    openaiCompatibleBaseUrl: string;
+    openaiCompatibleApiKey: string;
+    orchestratorModel: string;
+    geminiModel: string;
+    /** Model for research subagents (issue #34); defaults to the (cheap) planner model. */
+    researchSubagentModel: string;
+    /**
+     * Thinking effort / model variant for a harness planner (ADR-0009), chosen
+     * from the agent's own discovered variants. Separate from the per-task
+     * efforts the plan carries — this one is the planner's own dial.
+     */
+    plannerThinkingEffort?: string;
+    planMapEnabled: boolean;
+    autonomousMode: boolean;
+    /**
+     * What to do when planner research reaches outside its default envelope — an
+     * out-of-workspace path, or a shell command beyond the auto-allowed read-only
+     * set. `ask` prompts the user (and denies where no surface can prompt, such as
+     * headless runs); `allow` and `deny` skip the prompt entirely.
+     */
+    approvalMode: ApprovalMode;
+    /** Scopes granted up front, so CI and power users never see a prompt. Trailing `*` matches by prefix. */
+    approvalPreApproved: string[];
+    /** Get the base URL for an OpenAI-compatible provider. */
+    getProviderBaseUrl(provider: AiProvider): string;
+    /** Get the API key for a provider. */
+    getProviderApiKey(provider: AiProvider): string;
+    /**
+     * Push the canonical provider routing lists in (sole producer: ModelResolver).
+     * Config consumes them when resolving a chosen model id to its serving API.
+     */
+    setProviderModelLists(lists: ProviderModelLists): void;
+}
+declare function enabledRunners(cfg: IConfig): RunnerId[];
+
+interface RunnerPluginManifest {
+    name: string;
+    displayName: string;
+    description: string;
+    version: string;
+    author?: string;
+    homepage?: string;
+    runner: PluginRunnerDef;
+    features: PluginFeatures;
+    modelDiscovery: PluginModelDiscovery;
+    contextFile?: string;
+    contextFileAltPath?: string;
+    modes?: PluginMode[];
+}
+interface PluginRunnerDef {
+    command: string;
+    argsTemplate: string[];
+    promptInArgs: boolean;
+    env?: Record<string, string>;
+    /** When true, the runner requires a PTY. HeadlessRunner wraps with `script` to allocate one. */
+    requiresTty?: boolean;
+}
+interface PluginFeatures {
+    modelSelection: boolean;
+    thinkingEffort: boolean;
+    planMode: boolean;
+    planModeFlag: string;
+    buildModeFlag?: string;
+    /** Flag appended when headless mode is on, so the agent never prompts for permission (e.g. Claude's --dangerously-skip-permissions). */
+    headlessFlag?: string;
+    thinkingFlag?: string;
+    thinkingValueEnabled?: string;
+    thinkingValueDisabled?: string;
+    thinkingValueAdaptive?: string;
+    /** Maps mode IDs to the CLI --permission-mode value. Used by {{feature:permissionModeVal}}. */
+    permissionModeValues?: Record<string, string>;
+}
+type PluginParser = 'claude-help' | 'opencode-models' | 'opencode-models-verbose' | 'anthropic-models' | 'line-by-line' | 'json' | 'json-table';
+interface DiscoveryCommand {
+    command: string;
+    args: string[];
+    parser?: PluginParser;
+}
+type ApiAuthMethod = {
+    type: 'env';
+    varName: string;
+    header: string;
+    prefix?: string;
+} | {
+    type: 'file';
+    path: string;
+    jsonPath: string;
+    header: string;
+    prefix?: string;
+};
+interface ApiDiscoveryConfig {
+    url: string;
+    headers?: Record<string, string>;
+    auth: ApiAuthMethod[];
+    parser: PluginParser;
+}
+interface PluginModelDiscovery {
+    method: 'command' | 'hardcoded';
+    command?: string;
+    args?: string[];
+    parser?: PluginParser;
+    jsonPath?: string;
+    /**
+     * Stdio JSON-RPC discovery (Codex `app-server`): spawn the command, send
+     * `initialize` then `model/list`, and read the catalog from the response.
+     * Tried BEFORE apiDiscovery and command discovery. When the call fails,
+     * `cacheFile` (the runner's own on-disk catalog cache, `~` expanded) is
+     * read before falling through to the remaining discovery methods.
+     */
+    appServer?: {
+        command: string;
+        args: string[];
+        cacheFile?: string;
+    };
+    /**
+     * Optional last-resort list for user plugins whose CLI cannot enumerate
+     * models. Used only when command discovery fails entirely or the CLI is
+     * unavailable. Built-in manifests must NOT use this: anything listed here is
+     * shown to the user as available even when it isn't.
+     */
+    fallbackModels?: {
+        modelId: string;
+        modelLabel: string;
+    }[];
+    /**
+     * Stable `--model` aliases that the runner's CLI always accepts but its help
+     * text may omit (e.g. Claude's 'haiku'). Merged into successful discovery
+     * results to fill gaps — discovered models take precedence, missing aliases
+     * are appended — and used as the last resort when discovery fails entirely.
+     * Unlike `fallbackModels`, entries must be stable CLI-accepted aliases
+     * (contracts that always resolve), not arbitrary model IDs.
+     */
+    canonicalAliases?: {
+        modelId: string;
+        modelLabel: string;
+    }[];
+    /**
+     * HTTP API discovery — tried BEFORE command discovery. When the runner's CLI
+     * has no model-listing subcommand (Claude Code), an API endpoint can serve as
+     * the authoritative source. Auth methods are tried in order; the first that
+     * yields a token is used. If no auth method yields a token or the request
+     * fails, discovery falls through to `discoveryCommands` + `canonicalAliases`.
+     */
+    apiDiscovery?: ApiDiscoveryConfig;
+    preferredPatterns?: {
+        id: string;
+        label: string;
+    }[];
+    variants?: {
+        id: string;
+        label: string;
+    }[];
+    discoveryCommands?: DiscoveryCommand[];
+}
+interface PluginMode {
+    id: string;
+    label: string;
+    description: string;
+    /** CLI value passed to the runner's permission/mode flag. Defaults to id if omitted. */
+    cliValue?: string;
+    /** Marks this mode as the runner's most permissive mode — the resolved default when autonomous mode is ON. */
+    autonomous?: boolean;
+    /** Marks this mode as the runner's conservative build mode — the resolved default when autonomous mode is OFF. */
+    safe?: boolean;
+}
+interface PluginEntry {
+    manifest: RunnerPluginManifest;
+    source: 'builtin' | 'user';
+    installPath?: string;
+}
+interface ResolveContext {
+    prompt: string;
+    model?: string;
+    thinkingEffort?: string;
+    /** All variant ids the assigned model offers — lets {{opencodeVariantConfig}} disable the non-chosen ones. */
+    modelVariants?: string[];
+    mode: string;
+    /** When true, resolve {{if headless}} blocks and the {{feature:headless}} token. */
+    headless?: boolean;
+}
+interface RunnerInvocation {
+    command: string;
+    args: string[];
+    env: Record<string, string>;
+    promptInArgs: boolean;
+}
+/**
+ * Persistent storage seam for plugin manifests. The RunnerRegistry delegates
+ * all filesystem operations to this interface so the plugin lifecycle is
+ * testable without real I/O.
+ */
+interface IPluginStore {
+    /** Path to the user plugins directory (~/.config/ordewell/plugins/). */
+    getUserPluginsDir(): string;
+    /** List subdirectory names inside the user plugins directory. */
+    listUserPluginDirs(): string[];
+    /** Read and parse a manifest.json from pluginDir. Returns null on failure. */
+    loadManifest(pluginDir: string): RunnerPluginManifest | null;
+    /** Recursively copy sourceDir to destDir. */
+    copyDir(sourceDir: string, destDir: string): void;
+    /** Recursively remove a directory. */
+    removeDir(dir: string): void;
+    /** Ensure a directory exists (mkdir -p). */
+    ensureDir(dir: string): void;
+    /** Write a text file. */
+    writeFile(filePath: string, content: string): void;
+    /** Read a UTF-8 text file. Returns null on ENOENT or read error. */
+    readFile(filePath: string): string | null;
+    /** True if path exists and is a directory. */
+    dirExists(path: string): boolean;
+    /** True if path exists. */
+    exists(path: string): boolean;
+}
+
+declare class RunnerRegistry {
+    private plugins;
+    private store;
+    constructor(store?: IPluginStore);
+    private loadBuiltins;
+    loadUserPlugins(): void;
+    get(id: string): PluginEntry | undefined;
+    getManifest(id: string): RunnerPluginManifest | undefined;
+    list(): PluginEntry[];
+    listEnabled(config: IConfig): PluginEntry[];
+    listEnabledIds(config: IConfig): string[];
+    isBuiltIn(id: string): boolean;
+    installFromPath(sourcePath: string): RunnerPluginManifest;
+    installFromGit(url: string): RunnerPluginManifest;
+    private finishInstall;
+    remove(name: string): void;
+    createSkeleton(name: string, outputDir: string): string;
+}
+
+interface ITerminalSession {
+    id: string;
+    taskId: string;
+    onOutput(callback: (text: string) => void): void;
+    onExit(callback: (code: number) => void): void;
+    kill(): void;
+    getOutput(): string;
+    write(text: string): void;
+}
+
+interface ITerminalRunner {
+    spawn(opts: {
+        taskId: string;
+        runner: string;
+        prompt: string;
+        modelId?: string;
+        thinkingEffort?: string;
+        modelVariants?: string[];
+        mode?: string;
+        headless?: boolean;
+        cwd: string;
+        registry?: RunnerRegistry;
+        /** Task order and title — surfaces use these to label task_started/output events. */
+        order?: number;
+        title?: string;
+        /**
+         * The owning plan session. Task ids are only unique within one plan, so
+         * transports that key OS resources by task (tmux windows, log files) need
+         * this to keep two plans' identically named tasks apart.
+         */
+        planSessionId?: string;
+    }): Promise<ITerminalSession>;
+    stop(sessionId: string): void;
+    stopAll(): void;
+    activeCount: number;
+}
+
+export { type AiProvider as A, type ResolveContext as B, type CatalogModel as C, DENY_ALL as D, type RunnerInvocation as E, type FetchAllProviderModelsOptions as F, GREP_DEFAULT_HEAD_LIMIT as G, type RunnerPluginManifest as H, type IApproval as I, RunnerRegistry as J, collectProviderCredentials as K, enabledRunners as L, ModelCatalog as M, fetchAllProviderModels as N, ORCHESTRATOR_SHORTCUTS as O, type PluginEntry as P, knownModelId as Q, type ReadFileOpts as R, SEARCH_EXCLUSIONS as S, type ToolOutcome as T, resolveModelShortcut as U, resolveProvider as V, toOrchestratorOptions as W, type AllProviderModels as a, type ApprovalKind as b, type ApprovalMode as c, ApprovalPolicy as d, type ApprovalPolicyOptions as e, type ApprovalRequest as f, type ApprovalSource as g, type DiscoveryCommand as h, type FindSymbolOptions as i, type GlobOptions as j, type GrepOptions as k, type GrepOutputMode as l, type IConfig as m, type IFileSystem as n, type IPluginStore as o, type ITerminalRunner as p, type ITerminalSession as q, type ModelShortcut as r, type OrchestratorOption as s, type PluginFeatures as t, type PluginMode as u, type PluginModelDiscovery as v, type PluginRunnerDef as w, type ProviderCredentialSource as x, type ProviderModelLists as y, type ProviderModelsResult as z };