/**
 * frameworkSessionLaunch — per-framework launch arg builders for
 * Instar-managed tmux sessions.
 *
 * Provider-portability v1.0.0: before this module, `SessionManager`
 * hardcoded the Claude CLI's flag set directly inline (Telegram-driven
 * interactive sessions used `claude --dangerously-skip-permissions
 * [--resume <id>]`). That left Codex sessions and future frameworks
 * unreachable from the Telegram topic flow.
 *
 * Adding a framework: implement a builder below and register it in
 * `BUILDERS`. The exhaustiveness check in `buildInteractiveLaunch`
 * forces a compile error if a case is missed.
 */
import type { IntelligenceFramework } from './intelligenceProviderFactory.js';
import { type EffortLevel, type ThinkingMode } from './topicProfileValidation.js';
/**
 * Cross-framework generic model tiers. Higher-level code (UpgradeNotify,
 * StallTriage, etc.) should think in tiers, not in framework-specific
 * names — each framework maps the tier to its own preferred model via
 * `resolveModelForFramework`. The legacy Claude-only tier names
 * ('haiku'|'sonnet'|'opus') still resolve correctly for back-compat.
 */
export type GenericModelTier = 'fast' | 'balanced' | 'capable';
/**
 * Map a generic tier or framework-specific name to the concrete model
 * string that should be passed to the framework's CLI. Pass-through for
 * anything that isn't a recognized generic tier (so callers can still
 * provide a raw model id when needed).
 *
 * Claude tier names ('haiku'|'sonnet'|'opus') ARE generic to claude-code
 * (the CLI accepts them as `--model` aliases) so we let them pass
 * through verbatim there.
 */
export declare function resolveModelForFramework(framework: IntelligenceFramework, modelOrTier: string | undefined): string | undefined;
export interface InteractiveLaunchOptions {
    /** Absolute path to the CLI binary for the selected framework. */
    binaryPath: string;
    /**
     * Optional session ID to resume into. Claude uses `--resume <id>` (flag).
     * Codex uses `resume <id>` (subcommand inserted right after the binary);
     * unsupported frameworks may ignore.
     */
    resumeSessionId?: string;
    /**
     * Codex requires a sandbox mode. Defaults to `danger-full-access` for
     * agentic sessions — these run autonomously and need the same
     * permission scope Claude gets via `--dangerously-skip-permissions`.
     */
    codexSandboxMode?: 'read-only' | 'workspace-write' | 'danger-full-access';
    /**
     * Optional model override for the launched session. Accepts a generic
     * tier ('fast'|'balanced'|'capable'), a framework-specific tier name,
     * or a raw model id. Resolution per-framework happens in the builder.
     * When unset, each builder uses its own subscription-safe default
     * ('balanced' for Codex; Claude inherits its CLI's account default).
     */
    defaultModel?: string;
    /**
     * Phase 6 local-model adapter — when set on a codex-cli launch, emits
     * `--oss --local-provider <provider>` so the interactive session
     * talks to a local Ollama/LM Studio instance.
     */
    codexLocalProvider?: 'ollama' | 'lmstudio';
    /**
     * Per-spawn Codex threadline MCP override. When set on a codex-cli launch,
     * emits `-c mcp_servers.threadline.{command,args}=...` so THIS agent's codex
     * session uses ITS OWN threadline MCP regardless of which agent last won the
     * SHARED ~/.codex/config.toml (last-writer-wins collision). See
     * resolveThreadlineMcpEntry / CODEX-MULTIAGENT-THREADLINE-SPEC.
     */
    codexThreadlineMcp?: {
        command: string;
        args: string[];
    };
    /**
     * Warm-session A2A (claude-code only): when set, the interactive claude
     * session is launched with `--session-id <uuid>` so its transcript is created
     * at a deterministic id. The warm keep-alive worker uses this so an eviction
     * mid-thread can fall back losslessly to `--resume <uuid>` (#746). Mutually
     * exclusive with `resumeSessionId` (resume wins — you cannot set a new id when
     * reloading an existing transcript). No effect on non-claude frameworks.
     */
    sessionId?: string;
    /**
     * pi-cli only: directory pi persists its session JSONL files into
     * (`--session-dir`). SessionManager pins this to the agent's state dir so
     * pi transcripts are durable + reap-log-coherent instead of landing in
     * pi's per-cwd default location (PI-HARNESS-INTEGRATION-SPEC §2.2).
     * No effect on non-pi frameworks.
     */
    piSessionDir?: string;
    /**
     * Subscription & Auth Standard P1.3 (claude-code only): the per-account config
     * home for this session. When set, the builder injects
     * `CLAUDE_CONFIG_DIR=<configHome>` into envOverrides so the launched Claude
     * session authenticates under THAT account's login instead of inheriting the
     * parent agent's. This is the swap mechanism — selecting/swapping an account =
     * launching (or `--resume`-ing) with that account's configHome. No effect on
     * non-claude frameworks. NEVER a token — just the login location.
     */
    configHome?: string;
    /**
     * Topic Profile §6 — per-topic thinking mode. Mapped per framework:
     *  - claude-code: `--effort <low|medium|high|max>` (the live CLI's verified
     *    launch flag); `off` → MAX_THINKING_TOKENS=0 via envOverrides (the flag
     *    has no off level).
     *  - codex-cli: `-c model_reasoning_effort=<low|medium|high|xhigh>`;
     *    `max` → xhigh; `off` → low (Codex reasoning models have no off — the
     *    caller discloses the remap once, §4).
     *  - gemini-cli / pi-cli: strict no-op (no reasoning knob shipped).
     */
    thinkingMode?: ThinkingMode;
    /**
     * Topic Profile — per-topic Claude Code `--effort` level pin (a DIRECT pin
     * of the CLI flag value: low|medium|high|xhigh|max). When set, the
     * claude-code builder pushes `--effort <level>` at spawn. Validated against
     * the closed enum INSIDE the builder (defense in depth) — an unknown value
     * is dropped, never passed to the CLI. Strict no-op on non-claude
     * frameworks. Distinct from `thinkingMode` (which the builders MAP onto the
     * reasoning knob); `effort` is the launch flag verbatim.
     */
    effort?: EffortLevel;
}
export interface InteractiveLaunchSpec {
    /** Args to append after the tmux env-var block, starting with the binary path. */
    argv: string[];
    /**
     * Framework-specific environment-variable additions/clears the caller
     * should merge into the tmux `-e` flags. Keys map to values; an empty
     * string clears the variable in the spawned session.
     */
    envOverrides: Record<string, string>;
}
/**
 * Build the argv + env overrides for a Telegram/Slack-driven
 * interactive session in the given framework.
 *
 * @example
 *   const spec = buildInteractiveLaunch('codex-cli', { binaryPath: '/usr/local/bin/codex' });
 *   // → spec.argv = ['/usr/local/bin/codex', '--sandbox', 'danger-full-access']
 *   // → spec.envOverrides = { CLAUDECODE: '' }
 */
export declare function buildInteractiveLaunch(framework: IntelligenceFramework, options: InteractiveLaunchOptions): InteractiveLaunchSpec;
/**
 * Resolve which framework an interactive session should run under,
 * given a per-call override (e.g., from telegramTopicMap.framework),
 * the agent-level `sessions.framework` config field, and the
 * `INSTAR_FRAMEWORK` env var. First match wins.
 */
export declare function resolveInteractiveFramework(input: {
    perCall?: IntelligenceFramework;
    configFramework?: IntelligenceFramework;
    envFramework?: IntelligenceFramework | null;
}): IntelligenceFramework;
/**
 * Options for a headless (prompt-and-exit) launch. Mirrors the shape
 * SessionManager.spawnSession passes when invoking the CLI with a
 * one-shot prompt — Claude uses `-p <prompt>`, Codex uses
 * `exec --json <prompt>`.
 */
export interface HeadlessLaunchOptions {
    /** Absolute path to the CLI binary for the selected framework. */
    binaryPath: string;
    /** The one-shot prompt to send. */
    prompt: string;
    /**
     * Optional model identifier passed straight through to the CLI's
     * model flag. For Claude this is a tier name (opus/sonnet/haiku) or
     * a full id; for Codex this is a Codex model id (gpt-5.3-codex etc.).
     * Caller is responsible for picking the right shape — see
     * intelligenceProviderFactory's resolveModelId for tier-to-model
     * mapping per framework.
     */
    model?: string;
    /**
     * Codex sandbox mode override. When set → `-s <mode> --ask-for-approval
     * never`. When absent, the headless default is `-s workspace-write` (jobs
     * stay sandboxed) unless `codexAllowMcpTools` is set, which selects
     * `--dangerously-bypass-approvals-and-sandbox` for reply workers.
     */
    codexSandboxMode?: 'read-only' | 'workspace-write' | 'danger-full-access';
    /**
     * Phase 6 local-model adapter — when set, the codex-cli builder
     * emits `--oss --local-provider <provider>` so the spawn talks to a
     * local Ollama/LM Studio instance instead of OpenAI. The model field
     * becomes the local model id (e.g. `llama3.2:latest`,
     * `qwen2.5-coder:7b`). The `defaultModel` (for raw tier resolution)
     * is bypassed since local models don't share OpenAI's tier
     * vocabulary.
     */
    codexLocalProvider?: 'ollama' | 'lmstudio';
    /**
     * Per-spawn Codex threadline MCP override — see InteractiveLaunchOptions.
     * Emits `-c mcp_servers.threadline.{command,args}=...` so this agent's
     * headless codex worker (notably Threadline inbound-reply spawns) uses ITS
     * OWN threadline MCP, not whichever agent last won the shared config.
     */
    codexThreadlineMcp?: {
        command: string;
        args: string[];
    };
    /**
     * When true, a codex-cli headless spawn launches with
     * `--dangerously-bypass-approvals-and-sandbox` so it can make MCP tool calls
     * (e.g. threadline_send to reply). Required for Threadline inbound-reply
     * workers — codex cancels MCP calls under any sandbox. Leave false for jobs:
     * they keep the workspace-write sandbox (they ingest external content and
     * don't use MCP). No effect on non-codex frameworks.
     */
    codexAllowMcpTools?: boolean;
    /**
     * Topic Profile — per-topic Claude Code `--effort` level pin (a DIRECT pin
     * of the CLI flag value: low|medium|high|xhigh|max). When set, the
     * claude-code headless builder pushes `--effort <level>` right after the
     * `--model` block and before the `-p` prompt. Validated against the closed
     * enum INSIDE the builder — an unknown value is dropped. No-op on non-claude
     * frameworks.
     */
    effort?: EffortLevel;
}
export interface HeadlessLaunchSpec {
    /** Args to append after the tmux env-var block, starting with the binary path. */
    argv: string[];
    /**
     * Framework-specific environment-variable additions/clears. Caller
     * merges these into the tmux `-e` flags alongside the universal
     * INSTAR_* / DATABASE_URL clearing block.
     */
    envOverrides: Record<string, string>;
}
/**
 * Build the argv + env overrides for a headless (one-shot prompt)
 * session in the given framework. Companion to `buildInteractiveLaunch`
 * for the prompt-and-exit path that backs SessionManager.spawnSession,
 * UpgradeNotifyManager, PipeSessionSpawner, and any future code that
 * needs an agent to handle a single prompt without staying interactive.
 *
 * @example
 *   const spec = buildHeadlessLaunch('codex-cli', {
 *     binaryPath: '/usr/local/bin/codex',
 *     prompt: 'summarize this thread',
 *     model: 'gpt-5.3-codex',
 *   });
 *   // → spec.argv = ['/usr/local/bin/codex', 'exec', '--json',
 *   //                '--skip-git-repo-check', '-s', 'workspace-write',
 *   //                '-m', 'gpt-5.3-codex', 'summarize this thread']
 */
export declare function buildHeadlessLaunch(framework: IntelligenceFramework, options: HeadlessLaunchOptions): HeadlessLaunchSpec;
/**
 * Extra claude-code headless flags spliced before the `-p` prompt positional:
 *  - `--allowedTools <list>` — the per-session tool-scope allowlist.
 *  - `--strict-mcp-config --mcp-config {"mcpServers":{}}` — the no-project-MCP
 *    spawn: a headless one-shot `claude -p` session that inherits the project
 *    `.mcp.json` HANGS on boot when that set includes interactively-authenticated
 *    remote MCP servers (they can't complete OAuth headless), so it never
 *    processes its prompt. An empty strict MCP config makes claude ignore the
 *    project config and start with zero MCP servers (verified live: a mentor
 *    autonomous-fix loop session stalled ~4.5 min at 0.1% CPU on MCP init; with
 *    this flag a headless spawn boots in ~9s).
 *
 * Returns `[]` for non-claude frameworks or when neither option is requested, so
 * the caller can splice unconditionally. Pure + order-stable for testing.
 */
/**
 * Defense-in-depth clamp for the direct `--effort` pin: returns the value
 * verbatim when it is a member of the closed enum, else null (the builder
 * drops it). The resolver already fails-open, but the builder is a second
 * untrusted entry point — an unknown value must never reach the CLI. Exported
 * for unit tests.
 */
export declare function validateEffortLevel(value: string | undefined | null): EffortLevel | null;
/**
 * Topic Profile §6 — map the generic thinking-mode enum to the Claude CLI's
 * `--effort` levels. `off` returns null (it rides the MAX_THINKING_TOKENS=0
 * env channel instead — the flag has no off level). Exported for the L5
 * canary + unit tests.
 */
export declare function claudeEffortForThinkingMode(mode: ThinkingMode | undefined): 'low' | 'medium' | 'high' | 'max' | null;
/**
 * Topic Profile §6 — map the generic thinking-mode enum to codex
 * `model_reasoning_effort` levels. `max` → xhigh; `off` → low (codex has no
 * off — the §4 write path discloses the remap once). Exported for the L5
 * canary + unit tests.
 */
export declare function codexReasoningEffortForThinkingMode(mode: ThinkingMode | undefined): 'low' | 'medium' | 'high' | 'xhigh' | null;
export declare function claudeHeadlessExtraFlags(opts: {
    framework: IntelligenceFramework | string;
    allowedTools?: string[];
    disableProjectMcp?: boolean;
}): string[];
//# sourceMappingURL=frameworkSessionLaunch.d.ts.map