llm-cli-gateway 1.1.0 → 1.5.4

package/dist/request-helpers.d.ts

@@ -1,7 +1,4 @@
-/**
- * Pure, side-effect-free helpers for request argument planning.
- * Zero I/O, zero dependencies on index-scoped collaborators.
- */
+import { z } from "zod";
 /** Prefix for gateway-generated session IDs. Enforces provenance structurally. */
 export declare const GATEWAY_SESSION_PREFIX = "gw-";
 export interface SessionResumeResult {
@@ -30,3 +27,527 @@ export declare function resolveSessionResumeArgs(opts: {
     resumeLatest?: boolean;
     createNewSession?: boolean;
 }): SessionResumeResult;
+/**
+ * Codex-specific resume planning.
+ *
+ * Codex CLI ≥ 0.30 exposes session resume as a subcommand (`codex exec resume`),
+ * not a flag pair like Claude/Gemini/Grok. So we can't return a simple list of
+ * args — we describe the *mode* and let the caller branch when building argv:
+ *
+ *   - "new"            → `codex exec [...flags] PROMPT`
+ *   - "resume-by-id"   → `codex exec resume [...resume-safe flags] <SESSION_ID> PROMPT`
+ *   - "resume-latest"  → `codex exec resume --last [...resume-safe flags] PROMPT`
+ *
+ * `codex exec resume` rejects `--full-auto`; the original session's approval
+ * policy is inherited. Callers MUST filter `--full-auto` out of the flag set
+ * when mode is one of the resume forms (see `prepareCodexRequest`).
+ *
+ * `sessionId` MUST be a real Codex session UUID (as recorded under
+ * `~/.codex/sessions/`). Gateway-generated `gw-*` IDs are rejected, since
+ * they are bookkeeping handles and would 404 against `codex resume`.
+ */
+export type CodexSessionMode = "new" | "resume-by-id" | "resume-latest";
+export interface CodexSessionPlan {
+    mode: CodexSessionMode;
+    /** Real Codex session UUID. Present only when mode === "resume-by-id". */
+    sessionId?: string;
+}
+export declare function resolveCodexSessionArgs(opts: {
+    sessionId?: string;
+    resumeLatest?: boolean;
+    createNewSession?: boolean;
+}): CodexSessionPlan;
+/**
+ * Grok-specific resume args. Grok accepts `--resume <id>` to resume a named session,
+ * and `--continue` to resume the most recent session for the current working directory.
+ * Unlike `resolveSessionResumeArgs`, "resume latest" maps to `--continue` (not `--resume latest`)
+ * because Grok would interpret a literal "latest" as a session ID.
+ */
+export declare function resolveGrokSessionArgs(opts: {
+    sessionId?: string;
+    resumeLatest?: boolean;
+    createNewSession?: boolean;
+}): SessionResumeResult;
+/**
+ * Mistral Vibe-specific resume args.
+ *
+ * Vibe persists sessions only when `[session_logging] enabled = true` is set in
+ * `~/.vibe/config.toml`. The doctor checks for that toggle and surfaces an
+ * actionable error when it is missing; this pure helper just emits the args.
+ *
+ * The args shape mirrors Grok (`--continue` for latest, `--resume <id>` for a
+ * specific session) because Vibe exposes the same surface for its session log.
+ */
+export declare function resolveMistralSessionArgs(opts: {
+    sessionId?: string;
+    resumeLatest?: boolean;
+    createNewSession?: boolean;
+}): SessionResumeResult;
+/**
+ * Vibe-specific permission mode mapping. Vibe replaces Grok's `--always-approve`
+ * with an `--agent <mode>` enum. When the caller does not set a permissionMode,
+ * the gateway emits `--agent auto-approve` explicitly: omitting the flag would
+ * let Vibe pick its own default which may not be auto-approve, surprising
+ * programmatic callers.
+ */
+export declare const MISTRAL_AGENT_MODES: readonly ["default", "plan", "accept-edits", "auto-approve", "chat", "explore", "lean"];
+export type MistralAgentMode = (typeof MISTRAL_AGENT_MODES)[number];
+export declare const MISTRAL_DEFAULT_AGENT_MODE: MistralAgentMode;
+export interface PrepareMistralRequestInput {
+    prompt: string;
+    resolvedModel?: string;
+    outputFormat?: string;
+    permissionMode?: MistralAgentMode;
+    effort?: string;
+    reasoningEffort?: string;
+    allowedTools?: string[];
+    /**
+     * Vibe has no flag to deny tools; this is accepted in the schema for caller
+     * parity with Grok/Claude but produces no CLI flag. The caller is expected to
+     * emit a `logger.warn` when this is non-empty.
+     */
+    disallowedTools?: string[];
+}
+export interface PrepareMistralRequestResult {
+    args: string[];
+    env: Record<string, string>;
+    ignoredDisallowedTools: boolean;
+}
+/**
+ * Pure helper that builds Vibe's argv and env.
+ *
+ * - Model is selected via `VIBE_ACTIVE_MODEL` env var (NOT a `--model` flag).
+ * - Permission mode emits `--agent <mode>` (defaults to `auto-approve` when unset).
+ * - Allowed tools emit `--enabled-tools <tool>` once per tool (allowlist only).
+ * - Disallowed tools are accepted but ignored at the CLI boundary.
+ */
+export declare function prepareMistralRequest(input: PrepareMistralRequestInput): PrepareMistralRequestResult;
+/**
+ * Claude `--permission-mode` values. `default` is a no-op (no flag emitted) —
+ * matches the CLI's behavior when the flag is absent, and avoids hard-coding an
+ * undocumented literal.
+ */
+export declare const CLAUDE_PERMISSION_MODES: readonly ["default", "acceptEdits", "plan", "auto", "dontAsk", "bypassPermissions"];
+export type ClaudePermissionMode = (typeof CLAUDE_PERMISSION_MODES)[number];
+export interface ClaudePermissionFlagsInput {
+    permissionMode?: ClaudePermissionMode;
+    /** Legacy parameter retained for one minor release. Maps to bypassPermissions. */
+    dangerouslySkipPermissions?: boolean;
+}
+export interface ClaudePermissionFlagsResult {
+    args: string[];
+    /** Set when both legacy + new flag are passed; caller should logger.warn. */
+    warning?: string;
+}
+/**
+ * Resolve Claude's `--permission-mode` args.
+ *
+ * Precedence:
+ *   1. If `permissionMode` is set, it wins. A warning is returned when
+ *      `dangerouslySkipPermissions: true` is also set (legacy + new conflict).
+ *   2. Else if `dangerouslySkipPermissions: true`, emit `--permission-mode
+ *      bypassPermissions`.
+ *   3. Else (or `permissionMode === "default"`) emit nothing.
+ */
+export declare function resolveClaudePermissionFlags(input: ClaudePermissionFlagsInput): ClaudePermissionFlagsResult;
+/**
+ * Gemini `--approval-mode` values. Preserves existing values (`default`,
+ * `auto_edit`, `yolo`) and adds `plan` for parity with Claude's plan mode.
+ */
+export declare const GEMINI_APPROVAL_MODES: readonly ["default", "auto_edit", "yolo", "plan"];
+export type GeminiApprovalMode = (typeof GEMINI_APPROVAL_MODES)[number];
+/**
+ * Codex sandbox modes (for `--sandbox <mode>`).
+ */
+export declare const CODEX_SANDBOX_MODES: readonly ["read-only", "workspace-write", "danger-full-access"];
+export type CodexSandboxMode = (typeof CODEX_SANDBOX_MODES)[number];
+/**
+ * Codex approval modes (for `--ask-for-approval <mode>`).
+ */
+export declare const CODEX_ASK_FOR_APPROVAL_MODES: readonly ["untrusted", "on-request", "never"];
+export type CodexAskForApproval = (typeof CODEX_ASK_FOR_APPROVAL_MODES)[number];
+export interface CodexSandboxFlagsInput {
+    /** Modern: explicit sandbox mode. */
+    sandboxMode?: CodexSandboxMode;
+    /** Modern: explicit approval mode. */
+    askForApproval?: CodexAskForApproval;
+    /** Legacy: shorthand for sandbox=workspace-write + askForApproval=never. */
+    fullAuto?: boolean;
+    /**
+     * Escape hatch: when true + `fullAuto: true`, emit `--full-auto` directly
+     * instead of expanding. Off by default. Deprecated and removed after
+     * Mistral GA.
+     */
+    useLegacyFullAutoFlag?: boolean;
+}
+export interface CodexSandboxFlagsResult {
+    args: string[];
+    /** Set when fullAuto + explicit sandbox/approval are both supplied. */
+    warning?: string;
+}
+/**
+ * Resolve Codex `--sandbox` / `--ask-for-approval` args from the modern
+ * params + legacy `fullAuto` shorthand.
+ *
+ * Precedence:
+ *   1. If `useLegacyFullAutoFlag && fullAuto`, emit `--full-auto` directly
+ *      (escape hatch; deprecated).
+ *   2. Else explicit `sandboxMode` / `askForApproval` always emit their
+ *      flags. If `fullAuto: true` is set alongside, a warning is attached
+ *      and the explicit values win.
+ *   3. Else if `fullAuto: true`, expand to
+ *      `--sandbox workspace-write --ask-for-approval never`.
+ *   4. Else emit nothing.
+ */
+export declare function resolveCodexSandboxFlags(input: CodexSandboxFlagsInput): CodexSandboxFlagsResult;
+/**
+ * Flags that `codex exec resume` rejects (the original session's policy is
+ * inherited). Callers must drop these when building resume argv.
+ *
+ * U26 expands this list with `--add-dir`, `-C`, `--output-schema`, and
+ * `--search`, all of which `codex exec resume --help` rejects at the audit
+ * date.
+ */
+export declare const CODEX_RESUME_FILTERED_FLAGS: ReadonlySet<string>;
+/**
+ * Strip resume-incompatible flag/value pairs from a Codex argv segment.
+ *
+ * Bare flags (`--full-auto`, `--search`) drop without consuming a value.
+ * Value-taking flags (`--sandbox`, `--ask-for-approval`, `--add-dir`, `-C`,
+ * `--output-schema`) drop together with their immediately-following value.
+ */
+export declare function filterCodexResumeFlags(args: string[]): string[];
+/**
+ * Claude `--effort` enum values. Mirrors the model-side effort axis.
+ */
+export declare const CLAUDE_EFFORT_LEVELS: readonly ["low", "medium", "high", "xhigh", "max"];
+export type ClaudeEffortLevel = (typeof CLAUDE_EFFORT_LEVELS)[number];
+/**
+ * Standalone Zod object for U25's high-impact param subset. Enforces the
+ * `systemPrompt` / `appendSystemPrompt` mutual-exclusion via `.refine(...)`.
+ *
+ * The MCP SDK's `server.tool` takes a raw shape (no top-level refine), so the
+ * tool callback re-checks the constraint and returns an error response. This
+ * exported schema is what tests use to verify Zod-level enforcement.
+ */
+export declare const CLAUDE_HIGH_IMPACT_PARAMS_SCHEMA: z.ZodEffects<z.ZodObject<{
+    agent: z.ZodOptional<z.ZodString>;
+    agents: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    forkSession: z.ZodOptional<z.ZodBoolean>;
+    systemPrompt: z.ZodOptional<z.ZodString>;
+    appendSystemPrompt: z.ZodOptional<z.ZodString>;
+    maxBudgetUsd: z.ZodOptional<z.ZodNumber>;
+    maxTurns: z.ZodOptional<z.ZodNumber>;
+    effort: z.ZodOptional<z.ZodEnum<["low", "medium", "high", "xhigh", "max"]>>;
+    excludeDynamicSystemPromptSections: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    agent?: string | undefined;
+    agents?: Record<string, Record<string, unknown>> | undefined;
+    forkSession?: boolean | undefined;
+    systemPrompt?: string | undefined;
+    appendSystemPrompt?: string | undefined;
+    maxBudgetUsd?: number | undefined;
+    maxTurns?: number | undefined;
+    effort?: "low" | "medium" | "high" | "xhigh" | "max" | undefined;
+    excludeDynamicSystemPromptSections?: boolean | undefined;
+}, {
+    agent?: string | undefined;
+    agents?: Record<string, Record<string, unknown>> | undefined;
+    forkSession?: boolean | undefined;
+    systemPrompt?: string | undefined;
+    appendSystemPrompt?: string | undefined;
+    maxBudgetUsd?: number | undefined;
+    maxTurns?: number | undefined;
+    effort?: "low" | "medium" | "high" | "xhigh" | "max" | undefined;
+    excludeDynamicSystemPromptSections?: boolean | undefined;
+}>, {
+    agent?: string | undefined;
+    agents?: Record<string, Record<string, unknown>> | undefined;
+    forkSession?: boolean | undefined;
+    systemPrompt?: string | undefined;
+    appendSystemPrompt?: string | undefined;
+    maxBudgetUsd?: number | undefined;
+    maxTurns?: number | undefined;
+    effort?: "low" | "medium" | "high" | "xhigh" | "max" | undefined;
+    excludeDynamicSystemPromptSections?: boolean | undefined;
+}, {
+    agent?: string | undefined;
+    agents?: Record<string, Record<string, unknown>> | undefined;
+    forkSession?: boolean | undefined;
+    systemPrompt?: string | undefined;
+    appendSystemPrompt?: string | undefined;
+    maxBudgetUsd?: number | undefined;
+    maxTurns?: number | undefined;
+    effort?: "low" | "medium" | "high" | "xhigh" | "max" | undefined;
+    excludeDynamicSystemPromptSections?: boolean | undefined;
+}>;
+/**
+ * Minimal Anthropic agent-definition schema. Mirrors the shape expected by
+ * Claude CLI's `--agents` inline JSON argument. We validate the *required*
+ * keys (`description`, `prompt`) up-front so a malformed payload fails fast
+ * with an actionable error instead of producing an opaque CLI exit.
+ */
+export declare const CLAUDE_AGENT_DEFINITION_SCHEMA: z.ZodObject<{
+    description: z.ZodString;
+    prompt: z.ZodString;
+    tools: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    model: z.ZodOptional<z.ZodString>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    description: z.ZodString;
+    prompt: z.ZodString;
+    tools: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    model: z.ZodOptional<z.ZodString>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    description: z.ZodString;
+    prompt: z.ZodString;
+    tools: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    model: z.ZodOptional<z.ZodString>;
+}, z.ZodTypeAny, "passthrough">>;
+export type ClaudeAgentDefinition = z.infer<typeof CLAUDE_AGENT_DEFINITION_SCHEMA>;
+/**
+ * Validate an `agents` map against {@link CLAUDE_AGENT_DEFINITION_SCHEMA}.
+ *
+ * Returns `{ ok: true, value }` on success and `{ ok: false, agentKey, message }`
+ * on the first failing entry. The caller is responsible for turning the failure
+ * into a tool-level error response (e.g. via `createErrorResponse`).
+ */
+export declare function validateClaudeAgentsMap(agents: Record<string, unknown>): {
+    ok: true;
+    value: Record<string, ClaudeAgentDefinition>;
+} | {
+    ok: false;
+    agentKey: string;
+    message: string;
+};
+export interface ClaudeHighImpactFlagsInput {
+    agent?: string;
+    /** Pre-validated agents map (call {@link validateClaudeAgentsMap} first). */
+    agents?: Record<string, ClaudeAgentDefinition>;
+    forkSession?: boolean;
+    systemPrompt?: string;
+    appendSystemPrompt?: string;
+    maxBudgetUsd?: number;
+    maxTurns?: number;
+    effort?: ClaudeEffortLevel;
+    excludeDynamicSystemPromptSections?: boolean;
+}
+/**
+ * Emit Claude high-impact feature flags (U25) as a flat argv segment.
+ *
+ * Mutual-exclusion of `systemPrompt`/`appendSystemPrompt` is enforced upstream
+ * at the Zod schema (`.refine(...)`); this helper does *not* re-check it, so
+ * tests can exercise either flag in isolation.
+ */
+export declare function prepareClaudeHighImpactFlags(input: ClaudeHighImpactFlagsInput): string[];
+/**
+ * Zod schema for Codex `configOverrides` map.
+ *
+ * Hard requirements (argv-injection prevention):
+ *   - Keys MUST match /^[a-zA-Z0-9._]+$/ (no whitespace, no equals, no flag-like prefixes).
+ *   - Values MUST NOT contain CR or LF — newlines could be re-interpreted by the
+ *     CLI's TOML parser as new keys.
+ *
+ * The CLI consumes overrides as `-c key=value`. We rely on `spawn(..., args)`
+ * passing argv directly without a shell, so we forbid shape-breaking
+ * characters rather than shell-escaping values.
+ */
+export declare const CODEX_CONFIG_OVERRIDES_SCHEMA: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodString, string, string>>>;
+export type CodexConfigOverrides = z.infer<typeof CODEX_CONFIG_OVERRIDES_SCHEMA>;
+/**
+ * Emit `-c key=value` pairs for each override. Caller MUST have validated the
+ * map with {@link CODEX_CONFIG_OVERRIDES_SCHEMA} first.
+ */
+export declare function emitCodexConfigOverrideArgs(overrides: Record<string, string> | undefined): string[];
+/**
+ * Materialize `outputSchema` into a CLI path.
+ *
+ * If `outputSchema` is a string, treat it as a pre-existing path and pass it
+ * through verbatim (no temp file, no cleanup needed).
+ *
+ * If it is an object, JSON-serialize it into a 0o600-mode temp file under
+ * `os.tmpdir()` and return both the path and a cleanup function. The caller
+ * MUST invoke `cleanup()` in a `finally` block (no matter the exit path) so
+ * the temp file does not leak.
+ *
+ * Returns `null` when `outputSchema` is undefined.
+ */
+export interface CodexOutputSchemaResult {
+    path: string;
+    /** No-op when schema came in as a string. Idempotent. */
+    cleanup: () => void;
+}
+export declare function prepareCodexOutputSchema(outputSchema: string | Record<string, unknown> | undefined): CodexOutputSchemaResult | null;
+/**
+ * Validate that every image path exists on disk. Returns the first missing
+ * path on failure; `null` on success.
+ */
+export declare function findMissingImagePath(images: string[] | undefined): string | null;
+/**
+ * Zod schema for the U26 Codex high-impact feature subset. Used by the
+ * `codex_request` / `codex_request_async` tool schemas to validate the new
+ * params before they reach `prepareCodexRequest`.
+ */
+export declare const CODEX_HIGH_IMPACT_PARAMS_SCHEMA: z.ZodObject<{
+    outputSchema: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>;
+    search: z.ZodOptional<z.ZodBoolean>;
+    profile: z.ZodOptional<z.ZodString>;
+    configOverrides: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodString, string, string>>>;
+    ephemeral: z.ZodOptional<z.ZodBoolean>;
+    images: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    ignoreUserConfig: z.ZodOptional<z.ZodBoolean>;
+    ignoreRules: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    search?: boolean | undefined;
+    profile?: string | undefined;
+    outputSchema?: string | Record<string, unknown> | undefined;
+    configOverrides?: Record<string, string> | undefined;
+    ephemeral?: boolean | undefined;
+    images?: string[] | undefined;
+    ignoreUserConfig?: boolean | undefined;
+    ignoreRules?: boolean | undefined;
+}, {
+    search?: boolean | undefined;
+    profile?: string | undefined;
+    outputSchema?: string | Record<string, unknown> | undefined;
+    configOverrides?: Record<string, string> | undefined;
+    ephemeral?: boolean | undefined;
+    images?: string[] | undefined;
+    ignoreUserConfig?: boolean | undefined;
+    ignoreRules?: boolean | undefined;
+}>;
+export interface CodexHighImpactFlagsInput {
+    outputSchema?: string | Record<string, unknown>;
+    search?: boolean;
+    profile?: string;
+    configOverrides?: Record<string, string>;
+    ephemeral?: boolean;
+    images?: string[];
+    ignoreUserConfig?: boolean;
+    ignoreRules?: boolean;
+}
+export interface CodexHighImpactFlagsResult {
+    args: string[];
+    /** Cleanup hook for the `outputSchema` temp file. Caller MUST invoke in `finally`. */
+    cleanup: () => void;
+    /** First missing image path, if any. When set, the caller should bail before spawning. */
+    missingImagePath: string | null;
+}
+/**
+ * Build the U26 argv segment AND any required side-effect handles.
+ *
+ * IMPORTANT: When this function writes a temp file for `outputSchema`, the
+ * returned `cleanup` function MUST be invoked by the caller (typically in a
+ * `finally` block around the spawn). Failing to do so leaks `0o600` temp
+ * files into `os.tmpdir()`.
+ */
+export declare function prepareCodexHighImpactFlags(input: CodexHighImpactFlagsInput): CodexHighImpactFlagsResult;
+/**
+ * Pure helper for `codex_fork_session`. Builds `codex fork ...` argv from a
+ * mutually-exclusive (sessionId | forkLast) selector and a prompt.
+ *
+ * Mutual exclusion is also enforced at the Zod schema in `index.ts`; this
+ * helper re-checks defensively so callers exercising it in isolation get the
+ * same guarantees.
+ */
+export interface CodexForkRequestInput {
+    prompt: string;
+    sessionId?: string;
+    forkLast?: boolean;
+}
+export declare function prepareCodexForkRequest(input: CodexForkRequestInput): {
+    args: string[];
+};
+/**
+ * Strict UUID v4 regex. Gemini's CLI is reportedly stricter about session id
+ * shape than the gateway's internal handles, so caller-supplied IDs (and IDs
+ * generated by `crypto.randomUUID()`) are validated against this regex before
+ * being emitted as `--session-id <uuid>`.
+ */
+export declare const GEMINI_SESSION_ID_REGEX: RegExp;
+export declare function isValidGeminiSessionId(id: string): boolean;
+/**
+ * Prepend `@<abs-path>` tokens to a Gemini prompt so the CLI's attachment
+ * resolver picks them up. Each path MUST be absolute and exist on disk.
+ *
+ * Returns the mutated prompt. Throws on validation failure so the caller can
+ * convert to a `createErrorResponse`.
+ */
+export declare function prependGeminiAttachments(prompt: string, attachments: string[]): string;
+/**
+ * Zod schema for the U27 Gemini high-impact feature subset. Used by the
+ * `gemini_request` / `gemini_request_async` tool schemas to validate the new
+ * params before they reach `prepareGeminiRequest`.
+ *
+ * `attachments` paths are validated to be absolute at the Zod layer; existence
+ * is enforced at execution time via `prependGeminiAttachments`.
+ */
+export declare const GEMINI_HIGH_IMPACT_PARAMS_SCHEMA: z.ZodObject<{
+    sandbox: z.ZodOptional<z.ZodBoolean>;
+    policyFiles: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    adminPolicyFiles: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    attachments: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
+}, "strip", z.ZodTypeAny, {
+    sandbox?: boolean | undefined;
+    policyFiles?: string[] | undefined;
+    adminPolicyFiles?: string[] | undefined;
+    attachments?: string[] | undefined;
+}, {
+    sandbox?: boolean | undefined;
+    policyFiles?: string[] | undefined;
+    adminPolicyFiles?: string[] | undefined;
+    attachments?: string[] | undefined;
+}>;
+export interface GeminiHighImpactFlagsInput {
+    sandbox?: boolean;
+    policyFiles?: string[];
+    adminPolicyFiles?: string[];
+}
+export interface GeminiHighImpactFlagsResult {
+    args: string[];
+    /** First missing policy path, if any. When set, the caller should bail. */
+    missingPolicyPath: string | null;
+    /** Which field the missing path came from (for actionable error messages). */
+    missingPolicyField: "policyFiles" | "adminPolicyFiles" | null;
+}
+/**
+ * Emit Gemini U27 high-impact flags. Policy paths are existence-checked here
+ * so a missing file fails fast with an actionable error rather than producing
+ * an opaque CLI exit.
+ *
+ * Does NOT handle `attachments` — those are mutated into the prompt string
+ * via {@link prependGeminiAttachments} BEFORE the `-p <prompt>` pair is
+ * emitted, preserving the U21 `-p` ordering invariant.
+ */
+export declare function prepareGeminiHighImpactFlags(input: GeminiHighImpactFlagsInput): GeminiHighImpactFlagsResult;
+/**
+ * Result of resolving Gemini's session-id emission strategy.
+ *
+ * U27 introduces deterministic `--session-id <uuid>` emission for fresh
+ * sessions, mapping the gateway-side session ID 1:1 to Gemini's authoritative
+ * store. The existing `--resume <id>` flow is preserved for user-supplied
+ * session IDs.
+ */
+export interface GeminiSessionPlan {
+    /** Flag pair to inject into argv (one of `["--session-id", uuid]`, `["--resume", id]`, `["--resume", "latest"]`, or `[]`). */
+    args: string[];
+    /** The UUID emitted via `--session-id`, if any. Gateway should persist this. */
+    emittedSessionId?: string;
+    /** True iff `--resume <id>` was emitted with a user-supplied id. */
+    resumed: boolean;
+}
+/**
+ * Resolve Gemini session-id args. When a fresh session is being established
+ * (either `createNewSession: true`, or no sessionId/resumeLatest set), emit
+ * `--session-id <uuid>` so the gateway and Gemini agree on the session
+ * identifier from the first turn.
+ *
+ * Falls back to `--resume <id>` when the caller supplies a sessionId, and
+ * `--resume latest` for `resumeLatest` (existing behavior preserved).
+ */
+export declare function resolveGeminiSessionPlan(opts: {
+    sessionId?: string;
+    resumeLatest?: boolean;
+    createNewSession?: boolean;
+    /** Override generator for deterministic tests. Must produce a v4 UUID. */
+    generateId?: () => string;
+}): GeminiSessionPlan;