llm-cli-gateway 1.17.3 → 1.17.5

package/dist/request-helpers.d.ts

@@ -1,55 +1,20 @@
 import { z } from "zod/v3";
-/** Prefix for gateway-generated session IDs. Enforces provenance structurally. */
 export declare const GATEWAY_SESSION_PREFIX = "gw-";
 export interface SessionResumeResult {
     resumeArgs: string[];
     effectiveSessionId: string | undefined;
     userProvidedSession: boolean;
 }
-/**
- * Validate that a user-provided sessionId doesn't use the reserved gateway prefix.
- * Throws if the ID starts with "gw-" — this namespace is reserved for gateway-generated IDs.
- */
 export declare function validateSessionId(sessionId: string): void;
-/**
- * Pure function: determine --resume args and session provenance from request flags.
- * Does NOT perform any session I/O — callers handle create/update separately.
- */
-/**
- * Reject CLI arg values that start with "-" to prevent argument injection.
- * spawn() doesn't invoke a shell so there's no shell injection, but a value
- * like "--dangerously-skip-permissions" passed as a tool name would be
- * interpreted as a flag by the child CLI.
- */
 export declare function sanitizeCliArgValues(values: string[], fieldName: string): string[];
 export declare function resolveSessionResumeArgs(opts: {
     sessionId?: string;
     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 sandbox/working-directory policy flags; the original session's approval
- * policy is inherited. Callers MUST filter those flags 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: {
@@ -57,39 +22,16 @@ export declare function resolveCodexSessionArgs(opts: {
     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.
- *
- * Current Vibe defaults session logging on; older configs can explicitly set
- * `[session_logging] enabled = false`. The doctor checks that toggle before
- * callers rely on session continuity; 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;
@@ -98,48 +40,13 @@ export interface PrepareMistralRequestInput {
     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[];
-    /**
-     * Phase 4 slice γ: emit `--trust` so non-interactive runs in fresh
-     * workspaces skip Vibe's interactive trust prompt for this invocation
-     * only (not persisted to `trusted_folders.toml`). Default undefined →
-     * Vibe's prompt behaviour is preserved for existing callers.
-     */
     trust?: boolean;
-    /**
-     * Phase 4 slice δ: emit `--max-turns N` to cap the agent-loop iteration
-     * count (only applies in programmatic mode with `-p`).
-     */
     maxTurns?: number;
-    /**
-     * Phase 4 slice δ: emit `--max-price DOLLARS` so the session is
-     * interrupted when cumulative cost crosses the cap (programmatic mode
-     * only).
-     */
     maxPrice?: number;
-    /**
-     * Vibe 2.x supports `--max-tokens N` in programmatic mode, wired through to
-     * `run_programmatic(max_session_tokens=...)`.
-     */
     maxTokens?: number;
-    /**
-     * Phase 4 slice ζ: emit `--workdir <DIR>` so Vibe changes into the named
-     * directory before running. Single value (Vibe accepts one --workdir).
-     */
     workingDir?: string;
-    /**
-     * Phase 4 slice ζ: emit `--add-dir <DIR>` per directory. Vibe's `--help`
-     * states the flag "Can be specified multiple times" — each entry is its
-     * own argv pair.
-     */
     addDir?: string[];
 }
 export interface PrepareMistralRequestResult {
@@ -147,127 +54,39 @@ export interface PrepareMistralRequestResult {
     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).
- * - Output format emits `--output <text|json|streaming>` (legacy gateway
- *   aliases `plain` and `stream-json` are normalized before spawn).
- * - 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];
-/**
- * Deprecated Codex approval modes. Current Codex no longer exposes an
- * `--ask-for-approval` flag; the MCP input is temporarily retained so older
- * callers do not fail schema validation, but it emits no CLI argv.
- */
 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;
-    /** Deprecated compatibility input; current Codex exposes no approval-policy flag. */
     askForApproval?: CodexAskForApproval;
-    /** Legacy: shorthand for sandbox=workspace-write. */
     fullAuto?: boolean;
-    /**
-     * Deprecated compatibility input. Current Codex rejects `--full-auto`, so
-     * this no longer changes argv emission.
-     */
     useLegacyFullAutoFlag?: boolean;
 }
 export interface CodexSandboxFlagsResult {
     args: string[];
-    /** Set when deprecated/no-op compatibility inputs are supplied. */
     warning?: string;
 }
-/**
- * Resolve current Codex sandbox args from the modern params + legacy
- * `fullAuto` shorthand. Current Codex exposes `--sandbox`, but no longer
- * exposes `--ask-for-approval` or `--full-auto`.
- *
- * Precedence:
- *   1. Explicit `sandboxMode` emits `--sandbox <mode>`.
- *   2. Else if `fullAuto: true`, expand to `--sandbox workspace-write`.
- *   3. Deprecated `askForApproval` and `useLegacyFullAutoFlag` emit no argv
- *      and return warnings for callers to surface/log.
- *   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.
- *
- * Verified against `codex exec resume --help` (codex-cli 0.135.0):
- * `--sandbox`, `--add-dir`, `-C`, `--cd`, `--profile`, and `--search` are rejected.
- * Deprecated `--full-auto` / `--ask-for-approval` are kept here defensively so
- * legacy pre-filtered segments are stripped instead of reaching spawn.
- * `--output-schema` and `-c key=value` ARE accepted on resume and therefore are
- * NOT in this filter (Phase 4 slice α restored the previously-silent drop of those two).
- */
 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`, `--cd`,
- * `--profile`) 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>>>;
@@ -319,12 +138,6 @@ export declare const CLAUDE_HIGH_IMPACT_PARAMS_SCHEMA: z.ZodEffects<z.ZodObject<
     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;
@@ -342,13 +155,6 @@ export declare const CLAUDE_AGENT_DEFINITION_SCHEMA: z.ZodObject<{
     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>;
@@ -359,7 +165,6 @@ export declare function validateClaudeAgentsMap(agents: Record<string, unknown>)
 };
 export interface ClaudeHighImpactFlagsInput {
     agent?: string;
-    /** Pre-validated agents map (call {@link validateClaudeAgentsMap} first). */
     agents?: Record<string, ClaudeAgentDefinition>;
     forkSession?: boolean;
     systemPrompt?: string;
@@ -368,86 +173,24 @@ export interface ClaudeHighImpactFlagsInput {
     maxTurns?: number;
     effort?: ClaudeEffortLevel;
     excludeDynamicSystemPromptSections?: boolean;
-    /**
-     * Phase 4 slice η — Claude `--fallback-model <model>`. Routes overloaded-model
-     * requests to the named fallback. Only effective with `--print` (we always pass
-     * `-p`, so no extra gating required here).
-     */
     fallbackModel?: string;
-    /**
-     * Phase 4 slice η — Claude `--json-schema <schema>`. Per `claude --help`, the
-     * argument is the JSON Schema *literal*, not a path. Object values are
-     * `JSON.stringify`-d; string values are passed verbatim (caller already wrote
-     * a JSON literal). No temp file lifecycle needed (contrast with Codex
-     * `--output-schema`, which takes a path).
-     */
     jsonSchema?: string | Record<string, unknown>;
-    /**
-     * Phase 4 slice ζ — Claude `--add-dir <dirs...>`. Additional directories the
-     * Claude CLI is allowed to read/write beyond the process cwd. The CLI accepts
-     * a single variadic flag (space-separated values) per `claude --help`; we
-     * emit one `--add-dir` instance per directory so each path is its own argv
-     * token (survives any future tightening of the variadic parser without
-     * changing the call site).
-     */
     addDir?: string[];
+    noSessionPersistence?: boolean;
+    settingSources?: string;
+    settings?: string;
+    tools?: string[];
 }
-/**
- * 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>;
@@ -488,30 +231,11 @@ export interface CodexHighImpactFlagsInput {
 }
 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;
-    /** Set when deprecated/no-op compatibility inputs are supplied. */
     warning?: string;
 }
-/**
- * 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;
@@ -520,22 +244,7 @@ export interface CodexForkRequestInput {
 export declare function prepareCodexForkRequest(input: CodexForkRequestInput): {
     args: string[];
 };
-/**
- * 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">>;
@@ -559,35 +268,14 @@ export interface GeminiHighImpactFlagsInput {
 }
 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 strategy.
- */
 export interface GeminiSessionPlan {
-    /** Flag pair to inject into argv (one of `["--resume", id]`, `["--resume", "latest"]`, or `[]`). */
     args: string[];
-    /** True iff `--resume <id>` was emitted with a user-supplied id. */
     resumed: boolean;
 }
-/**
- * Resolve Gemini session args. Gemini CLI 0.43 exposes `--resume` but not a
- * supported `--session-id` flag for fresh sessions, so new-session requests
- * intentionally emit no session flag and let the CLI create its own session.
- */
 export declare function resolveGeminiSessionPlan(opts: {
     sessionId?: string;
     resumeLatest?: boolean;