import { AgencyNode } from "../types.js"; import type { LogLevel } from "../logger.js"; import { z } from "zod"; import type { OpenRouterOptions } from "smoltalk"; import { type McpServers } from "./mcpServers.js"; import type { Platform } from "../host/host.js"; import type { TrustedModules } from "../compiler/trustedModules.js"; export declare const TYPES_THAT_DONT_TRIGGER_NEW_PART: AgencyNode["type"][]; /** * Maps Agency built-in function names to TypeScript equivalents. * Most map to themselves; exceptions are names that shadow JS globals. */ export declare const BUILTIN_FUNCTIONS: Record; export declare const BUILTIN_TOOLS: string[]; export declare const BUILTIN_VARIABLES: string[]; /** Reply-attachment caps (tools showing images to the model — see * docs/dev/agents/reply-attachments.md). The byte cap mirrors smoltalk's * DEFAULT_MAX_ATTACHMENT_BYTES (20 MB, enforced again at send time); * smoltalk does not currently export that constant from its index — * keep in sync if that changes. The count cap is ours and matches the * agent's user-attachment detection limit. */ export declare const MAX_REPLY_ATTACHMENTS_PER_CALL = 10; export declare const MAX_REPLY_ATTACHMENT_BYTES: number; /** * Configuration options for the Agency compiler */ export interface AgencyConfig { verbose?: boolean; /** MCP servers the program and the agent can connect to. */ mcpServers?: McpServers; /** * Let a compile-time splice run a generator that imports JavaScript. * * By default a generator may import only `std::` modules and other * `.agency` files in your project. That restriction is what makes the * safety story work: dangerous operations in Agency ask permission, and * compilation answers nothing, so they cannot complete. JavaScript asks * nothing, so a generator that reaches an npm package is unchecked. * * Turn this on if a generator genuinely needs a JavaScript library, and * know that the generator can then do anything that library can. */ allowNonAgencyGenerators?: boolean; /** * Refuse to compile a file containing a compile-time splice, instead of * running the generator. * * Compiling a `$( ... )` runs the generator during compilation, so * compiling a file you have not read executes code you have not read. * The bound on that is real but indirect: a generator may import only * `std::` modules and other `.agency` files, and compilation installs no * interrupt handlers, so anything dangerous cannot complete. This setting * is for callers who would rather decline than rely on that argument — * someone inspecting a freshly cloned repository, say. * * The refusal names the file and the generator, so you can decide whether * to compile again without it. Off by default; sandboxed compilation * (`compileSandboxed`) refuses splices unconditionally and does not need * it. */ refuseSplices?: boolean; /** * The platform the program is compiled for: `"node"` (the default) or * `"browser"`. It turns on a check and changes nothing in the code the * compiler emits: a node or exported function that can raise an effect * tagged with a capability the platform lacks (`PLATFORM_CAPABILITIES` * in lib/host/host.ts) fails to compile. `--platform` on `compile` and * `typecheck` sets it. See docs/dev/language/capabilities.md. */ platform?: Platform; logLevel?: LogLevel; outDir?: string; /** * Number of times the LLM can go back and forth between calling tools * and responding to their outputs before halting execution to prevent infinite loops. * Default 10. */ maxToolCallRounds?: number; /** * Enable observability. When false (default), the StatelogClient is a * complete no-op — no events are emitted and no network calls are made. * Set to true to activate structured event logging via the `log` config. */ observability?: boolean; /** Statelog config */ log?: Partial<{ host: string; projectId: string; debugMode: boolean; apiKey: string; /** * Local file sink. When set, each statelog event is appended as a * single JSON object per line. Intended for local development and * tests. Can be combined with `host` — both sinks receive events. */ logFile: string; /** * Per-event remote-send timeout in milliseconds. Bounds how long * `agency` can wait on a slow/unreachable statelog host before * giving up — prevents the http POST at end-of-run from delaying * process exit. Default: 1500ms. */ requestTimeoutMs: number; metadata: { tags?: string[]; environment?: string; userId?: string; agentVersion?: string; custom?: Record; }; /** Which code this run is: entry file, closure file hashes, one closure * hash. Set by launchers (agency run, eval, agency agent) and recorded on * the statelog's agentStart event. */ code: { entry: string; closureHash: string; closure: { file: string; sha256: string; }[]; }; }>; /** Eval command configuration */ eval?: { runsDir?: string; optimizeRunsDir?: string; sourceCacheRoot?: string; /** Per-run resource limits for the agent subprocess. Unset fields keep the * built-in defaults (lib/eval/run/subprocess.ts). */ limits?: { wallClockSec?: number; maxCostUsd?: number; maxBatchCostUsd?: number; }; optimize?: { goal?: string; graders?: string; optimizer?: string; validation?: { inputs?: string; split?: number; }; }; }; /** Smoltalk client config */ client?: Partial<{ logLevel: "error" | "warn" | "info" | "debug"; defaultModel: string; defaultProvider: string; apiKey: { openAi?: string; google?: string; anthropic?: string; ollama?: string; openRouter?: string; deepInfra?: string; liteLlm?: string; openAiCompat?: string; /** For a decision model (Jev). Through OpenRouter, this is the OpenRouter key. */ typesafe?: string; }; baseUrl: { openRouter?: string; deepInfra?: string; liteLlm?: string; openAiCompat?: string; /** Where the MLX server listens. Default `http://127.0.0.1:8080/v1`. */ mlx?: string; /** Where a decision model answers: TypeSafe, a gateway, or a local Laya server. */ typesafe?: string; }; /** * Max characters of a single tool result fed back to the LLM. * Results longer than this are truncated (with a marker) in what * the model sees — the full value is still returned to Agency code. * Prevents one tool (e.g. a recursive `ls`) from blowing the * context window. Default 100000; `0` disables the cap. Override * per call with `llm(..., { maxToolResultChars })`. */ maxToolResultChars: number; /** * Warn when one tool's JSON schema serializes to more characters than * this. A tool's schema is re-sent on every request in the run, so a * single oversized one is a standing cost: `std::syntax::highlight` * once carried a nested color-scheme object worth ~17,000 characters * against a ~1,000-character norm for the rest of the stdlib. The * warning goes to the state log and changes nothing else. Default * 2000; `0` disables the check. */ maxToolSchemaChars: number; /** * Paths to user-authored "provider module" ES files loaded at * startup. Each must export `register({ registerProvider })` and call * `registerProvider(name, ClientClass)` to register a custom smoltalk * provider (e.g. a local model via `smoltalk-llama-cpp`). Relative * paths resolve against the current working directory. Merged with * the `AGENCY_PROVIDER_MODULES` env var at runtime. */ providerModules: string[]; /** Short name → local-model alias, used by `std::agency/local` and the * `agency local` CLI. A value is either a bare Hugging Face URI or an * object carrying that URI plus display metadata (what `agency local * refresh` writes) — see `ModelAliasSchema`. Read and written at runtime * (not compile-time baked) so `agency local alias` edits take effect on * the next run. */ modelAliases: Record; /** Directory downloaded local models are cached in. Overridden by the * `AGENCY_MODELS_DIR` env var; defaults to `~/.agency-agent/models`. Read * at runtime by `std::agency/local` and the `agency local` CLI. */ modelsDir: string; /** The folder LoRA adapters are in, as `.safetensors` files. A local * image server loads one the first time a request names it by its * file name without the extension (`lora: "sketch"`). Relative to the * folder the config file is in. Unset means no request may name an adapter. */ adaptersDir: string; /** The folder ControlNets are in, one diffusers directory each * (`config.json` and its `.safetensors`). A local image server loads * one the first time a request names it by folder name * (`controlnet: "scribble"`) with a `controlImage` to condition on. * `agency local download` puts a catalog ControlNet here. */ controlnetsDir: string; /** Where `agency local refresh` fetches the model catalog. Overridden by * the `AGENCY_MODEL_CATALOG_URL` env var. Read at runtime. */ modelCatalogUrl: string; /** Settings for MLX models, which run in a server. */ mlx?: Partial<{ /** The Python `agency local serve` runs every model server with: it * needs mlx-lm for chat and embedding models, mlx-audio for speech, * and torch and diffusers for images. Overridden by `--python` and * the `AGENCY_MLX_PYTHON` env var; defaults to * `~/.agency-agent/mlx-env/bin/python`. */ python: string; /** Parallel byte-range requests while downloading an MLX model. Default 8. */ downloadConcurrency: number; }>; /** Which companies OpenRouter may send each call to, for every call in * the run. Mirrors smoltalk's `OpenRouterProviderPreferences`; a * `setLlmOptions` or per-call `openRouter` replaces it whole. */ openRouter?: OpenRouterOptions; /** Settings for GGUF models, which run in this process through llama.cpp. */ llamaCpp?: Partial<{ /** A smaller model of the same family that drafts tokens for the main * one to check, which is speculative decoding. A path to a .gguf * file. Set by `agency run --local --draft `; baked * into the program as smoltalk's `llamaCppDraftModel`. */ draftModel: string; /** The chat wrapper to format the model's prompts with, by * node-llama-cpp's name for it (`qwen`, `gemma4`, `harmony`, ...), * for a model whose template node-llama-cpp does not recognise. * Baked into the program as smoltalk's `llamaCppChatWrapper`. */ chatWrapper: string; }>; statelog?: Partial<{ host: string; projectId: string; apiKey: string; }>; }>; /** * Type checker configuration. Controls which checks run and their severity. */ typechecker?: { /** If true, run type checking during compilation and print warnings. Default: false. */ enabled?: boolean; /** If true, type errors are fatal during compilation (implies enabled: true). Default: false. */ strict?: boolean; /** If true, untyped variables are errors. Default: false. */ strictTypes?: boolean; /** * What to do when a function call cannot be resolved: * - "silent": ignore * - "warn": emit a warning (default) * - "error": emit an error */ undefinedFunctions?: "silent" | "warn" | "error"; /** * What to do when a variable reference cannot be resolved: * - "silent": ignore (default for the initial landing) * - "warn": emit a warning * - "error": emit an error */ undefinedVariables?: "silent" | "warn" | "error"; /** * Which JavaScript globals an unqualified name may refer to. * - "all" (default): the interop registry (JS_GLOBALS), so `process`, * `console`, etc. resolve — ordinary compilation. * - "sandbox": the reviewed allowlist (SANDBOX_JS_GLOBALS) of globals * that cannot reach the host. Set by `--agency-only`; a name outside * the allowlist becomes an error. */ jsGlobals?: "all" | "sandbox"; /** * Strictness of union member access. When a property exists on some but * not all members of an un-narrowed union (e.g. `r.value` on an * un-guarded `Result`), this governs the diagnostic: * - "silent": no diagnostic (lenient — such accesses type as `any`) * - "warn": emit a warning * - "error": emit an error (default) * Narrow first (guard / `catch` / `match`) to access branch-specific * members safely. Set to "silent" to opt out and restore the old lenient * behavior. */ strictMemberAccess?: "silent" | "warn" | "error"; /** * Whether a `match` over a closed value type (a Result, or a closed * literal/value union) that doesn't cover every case and has no `_` arm is * a diagnostic: * - "silent": no diagnostic (default) * - "warn": emit a warning * - "error": emit an error * Conservative: open types (string/number/any, effect sets) are never * required to be exhaustive; only a `_` arm satisfies them. */ matchExhaustiveness?: "silent" | "warn" | "error"; /** * What to do when a function that declares a non-void return type can reach * the end of its body without `return`ing a value (Agency has no implicit * returns). Default `"warn"`. */ definiteReturns?: "silent" | "warn" | "error"; }; /** Whether to emit debugStep() instrumentation in compiled output (default: true). * Set to false to eliminate per-step overhead when tracing/debugging is not needed. */ instrument?: boolean; /** Checkpoint configuration */ checkpoints?: { /** Maximum number of times a single checkpoint can be restored before throwing CheckpointError. * Prevents infinite restore loops. Default: 100. */ maxRestores?: number; }; /** Maximum logical function-call nesting depth before the runaway-recursion * guard throws CallDepthExceededError. Catches unbounded recursion — most * importantly the async kind, which grows the promise chain until the process * OOMs with no useful diagnostic — before it exhausts memory. Raise this for * programs that legitimately recurse very deeply. Default: 2048. */ maxCallDepth?: number; /** Failure-propagation mode. "on" (default): a failure value passed to a * parameter not typed to accept Results skips the call and propagates the * original failure; failures into plain TS functions and method calls on * Results throw. "warn": warnings only, legacy behavior otherwise. * "off": no checks. */ failurePropagation?: "off" | "warn" | "on"; /** What sandboxed code may reach beyond the standard library. */ sandbox?: SandboxConfig; /** Root spend/time budget for each run — the same ceiling as `agency run * --max-cost` / `--max-time`, but declarative and honored when the agent is * served remotely (a CLI flag, when given, wins). `maxCost` is dollars of LLM * spend; `< 0` disables, `0` is a real limit (no paid spend). `maxTime` is a * duration string like `30s`, `5m`, `1h`; `<= 0` disables. */ budget?: { maxCost?: number; maxTime?: string; }; /** Enable execution tracing — writes checkpoints to a .trace file */ trace?: boolean; /** Custom path for the trace file (default: .trace) */ traceFile?: string; /** Directory for auto-generated trace files. Each execution creates a new file * named _.agencytrace. */ traceDir?: string; /** Directory containing pre-compiled JS output (e.g., "dist"). * When set, the debugger imports compiled modules from this directory * instead of compiling on the fly. Resolved relative to cwd. */ distDir?: string; /** Test runner configuration */ test?: { /** Number of test files to run in parallel. Default: 1 (sequential). */ parallel?: number; }; doc?: { /** Output directory for generated documentation (default: "docs") */ outDir?: string; /** Base URL for source links in generated docs */ baseUrl?: string; }; /** * Enables the memory layer for this project. When set, every agent run * receives a `MemoryManager` on its RuntimeContext, std::memory becomes * usable, and `llm({ memory: true })` injects relevant facts. */ memory?: { /** Directory where per-memoryId subdirectories of JSON files are stored. */ dir: string; /** Default model used for extraction / compaction / LLM-tier recall. */ model?: string; autoExtract?: { /** Number of LLM turns between auto-extraction passes. Default: 5. */ interval?: number; }; compaction?: { /** Trigger metric: "token" estimates or raw "messages" count. */ trigger?: "token" | "messages"; /** Threshold above which compaction runs. */ threshold?: number; }; embeddings?: { /** Embedding model name (forwarded to smoltalk.embed). Required for * the local providers, mlx and llama-cpp, which have no default. */ model?: string; /** The provider that serves `model`. Set it when the model name does * not imply one, which is every local model. */ provider?: string; }; }; /** * Visual thresholds used by `agency logs view`. Durations at or * above `slowMs` (default 300000) render amber; durations below * `fastMs` (default 100) render gray. Costs at or above * `expensiveUsd` (default 1) render amber. */ viewer?: { slowMs?: number; fastMs?: number; expensiveUsd?: number; }; pack?: { /** * Output module format. Default: "esm". CJS output is useful when * embedding the bundle in a project whose package.json sets * `"type": "commonjs"` and the surrounding tooling expects CommonJS. */ format?: "esm" | "cjs"; /** * esbuild `target` string (e.g. "node20", "node22"). Default: "node20". */ target?: string; /** * Additional bare specifiers to keep external (in addition to Node * built-ins). Use sparingly — anything listed here must already be * installed wherever the bundle runs. */ external?: string[]; }; coverage?: { /** Output directory for collected coverage data (default: ".coverage") */ outDir?: string; /** * Minimum acceptable total coverage percentage (0–100). * `agency coverage report` exits with code 1 when total coverage falls * below this value. Overridden by the CLI `--threshold` flag. */ threshold?: number; /** * Per-file minimum coverage percentage (0–100). Each individual file * must be at or above this value, in addition to the overall threshold. */ perFileThreshold?: number; /** * Glob patterns of source files to exclude from coverage reports * (relative to the project root, picomatch syntax). Useful for * generated code, examples, or files you intentionally do not test. * * Example: ["examples/**", "stdlib/legacy/**"] */ exclude?: string[]; }; } /** One `client.modelAliases` value. Two forms are on disk: * * - a bare URI string, the shape `agency local alias add` writes; and * - an object carrying the URI plus display metadata, the shape * `agency local refresh` writes for catalog-managed entries (tagged * `source: "remote"` so a refresh can tell its own entries from yours). * * Both must validate here or a refresh leaves agency.json unloadable. The * object mirrors `AliasObject` in `lib/stdlib/localModels.ts`, which is the * type side of the same contract; `lib/config.modelAliases.test.ts` round-trips * a fully-populated entry so the two cannot drift apart. Unknown metadata keys * are allowed through so an older agency can load a config written by a newer * one (forward compatibility) rather than erroring on a field it lacks. */ export declare const ModelAliasSchema: z.ZodUnion; uri: z.ZodString; source: z.ZodOptional>; params: z.ZodOptional; sizeBytes: z.ZodOptional; kind: z.ZodOptional>; tags: z.ZodOptional>; category: z.ZodOptional; contextWindow: z.ZodOptional; license: z.ZodOptional; description: z.ZodOptional; sha256: z.ZodOptional; companions: z.ZodOptional>; }, z.core.$loose>]>; /** A `client.modelAliases` value: a bare URI or the rich object form. */ export type ModelAlias = z.infer; /** The `sandbox` block of `agency.json`. */ export type SandboxConfig = { /** Directories of `.agency` modules the host vouches for, each with the * directory its compiled JavaScript is in. A workflow may call tools * from these modules, and the child runs the host's compiled files * instead of compiling the source in the sandbox. Only `std::workflow` * compiles against this list. Relative paths resolve against the current * working directory, as `client.providerModules` do. See * docs/dev/runtime/trusted-modules.md. */ trustedModules?: TrustedModules[]; }; export declare const AgencyConfigSchema: z.ZodObject<{ verbose: z.ZodOptional; mcpServers: z.ZodOptional>; env: z.ZodOptional>; }, z.core.$strict>, z.ZodObject<{ type: z.ZodLiteral<"http">; url: z.ZodString; auth: z.ZodOptional>; authTimeout: z.ZodOptional; clientId: z.ZodOptional; clientSecret: z.ZodOptional; headers: z.ZodOptional>; }, z.core.$strict>]>>>; allowNonAgencyGenerators: z.ZodOptional; refuseSplices: z.ZodOptional; platform: z.ZodOptional>; logLevel: z.ZodOptional>; outDir: z.ZodOptional; maxToolCallRounds: z.ZodOptional; observability: z.ZodOptional; log: z.ZodOptional; projectId: z.ZodOptional; debugMode: z.ZodOptional; apiKey: z.ZodOptional; logFile: z.ZodOptional; requestTimeoutMs: z.ZodOptional; metadata: z.ZodOptional>; environment: z.ZodOptional; userId: z.ZodOptional; agentVersion: z.ZodOptional; custom: z.ZodOptional>; }, z.core.$strip>>; code: z.ZodOptional>; }, z.core.$strip>>; }, z.core.$strip>>; eval: z.ZodOptional; optimizeRunsDir: z.ZodOptional; sourceCacheRoot: z.ZodOptional>; limits: z.ZodOptional; maxCostUsd: z.ZodOptional; maxBatchCostUsd: z.ZodOptional; }, z.core.$strip>>>; optimize: z.ZodOptional>; graders: z.ZodOptional>; optimizer: z.ZodOptional>; validation: z.ZodOptional; split: z.ZodOptional; }, z.core.$strip>>>; }, z.core.$strip>>>; }, z.core.$strip>>; client: z.ZodOptional>; defaultModel: z.ZodOptional; defaultProvider: z.ZodOptional; apiKey: z.ZodOptional; google: z.ZodOptional; anthropic: z.ZodOptional; ollama: z.ZodOptional; openRouter: z.ZodOptional; deepInfra: z.ZodOptional; liteLlm: z.ZodOptional; openAiCompat: z.ZodOptional; typesafe: z.ZodOptional; }, z.core.$strip>>; baseUrl: z.ZodOptional; deepInfra: z.ZodOptional; liteLlm: z.ZodOptional; openAiCompat: z.ZodOptional; mlx: z.ZodOptional; typesafe: z.ZodOptional; }, z.core.$strip>>; maxToolResultChars: z.ZodOptional; maxToolSchemaChars: z.ZodOptional; providerModules: z.ZodOptional>; modelAliases: z.ZodOptional; uri: z.ZodString; source: z.ZodOptional>; params: z.ZodOptional; sizeBytes: z.ZodOptional; kind: z.ZodOptional>; tags: z.ZodOptional>; category: z.ZodOptional; contextWindow: z.ZodOptional; license: z.ZodOptional; description: z.ZodOptional; sha256: z.ZodOptional; companions: z.ZodOptional>; }, z.core.$loose>]>>>; modelsDir: z.ZodOptional; adaptersDir: z.ZodOptional; controlnetsDir: z.ZodOptional; modelCatalogUrl: z.ZodOptional; mlx: z.ZodOptional; downloadConcurrency: z.ZodOptional; }, z.core.$strip>>; openRouter: z.ZodOptional>; only: z.ZodOptional>; ignore: z.ZodOptional>; allowFallbacks: z.ZodOptional; requireParameters: z.ZodOptional; dataCollection: z.ZodOptional>; sort: z.ZodOptional>; quantizations: z.ZodOptional>; }, z.core.$strip>>; }, z.core.$strip>>; llamaCpp: z.ZodOptional; chatWrapper: z.ZodOptional; }, z.core.$strip>>; statelog: z.ZodOptional; projectId: z.ZodOptional; apiKey: z.ZodOptional; }, z.core.$strip>>; }, z.core.$strip>>; typechecker: z.ZodOptional; strict: z.ZodOptional; strictTypes: z.ZodOptional; undefinedFunctions: z.ZodOptional>; undefinedVariables: z.ZodOptional>; jsGlobals: z.ZodOptional>; strictMemberAccess: z.ZodOptional>; matchExhaustiveness: z.ZodOptional>; definiteReturns: z.ZodOptional>; }, z.core.$strip>>; instrument: z.ZodOptional; checkpoints: z.ZodOptional; }, z.core.$strip>>; maxCallDepth: z.ZodOptional; failurePropagation: z.ZodOptional>; sandbox: z.ZodOptional>>; }, z.core.$strip>>; budget: z.ZodOptional; maxTime: z.ZodOptional; }, z.core.$strip>>; trace: z.ZodOptional; traceFile: z.ZodOptional; traceDir: z.ZodOptional; distDir: z.ZodOptional; test: z.ZodOptional; }, z.core.$strip>>; doc: z.ZodOptional; baseUrl: z.ZodOptional; }, z.core.$strip>>; viewer: z.ZodOptional; fastMs: z.ZodOptional; expensiveUsd: z.ZodOptional; }, z.core.$strip>>; coverage: z.ZodOptional; threshold: z.ZodOptional; perFileThreshold: z.ZodOptional; exclude: z.ZodOptional>; }, z.core.$strip>>; pack: z.ZodOptional>; target: z.ZodOptional; external: z.ZodOptional>; }, z.core.$strip>>; memory: z.ZodOptional; autoExtract: z.ZodOptional; }, z.core.$strip>>; compaction: z.ZodOptional>; threshold: z.ZodOptional; }, z.core.$strip>>; embeddings: z.ZodOptional; provider: z.ZodOptional; }, z.core.$strip>>; }, z.core.$strip>>; }, z.core.$loose>; export type ConfigResult = { config: AgencyConfig; error?: string; }; /** Check `raw` against AgencyConfigSchema. `source` names where it came from * in the error message. */ export declare function validateConfig(raw: unknown, source: string): ConfigResult; /** A `--model` value after parsing. `explicitProvider` is set only when the * user wrote `provider/model`; a bare model leaves it undefined so smoltalk * infers the provider from the model name. * * Declared here rather than in the CLI so `CliFlags` stays self-contained: * `lib/config/config.ts` must not depend on `lib/cli/`, which would pull the CLI and * the runtime graph behind it into every consumer of the config module. */ export type ResolvedModelFlag = { model: string; explicitProvider?: string; /** A .gguf path for `agency run --local --draft `: the * smaller model that drafts tokens for `model`. Only for llama-cpp. */ draftModel?: string; }; /** Per-invocation flags accepted by `agency run`/`compile` and forwarded to the * bundled agents. Mapped onto AgencyConfig by applyCliFlags. `trace` is * `string` for `--trace `, `true` for a bare `--trace`. */ export type CliFlags = { trace?: string | true; logFile?: string; logStdout?: boolean; observability?: boolean; /** `--strict` on `run`/`compile`: fail the run on any fatal type error. */ strict?: boolean; /** `--strict` on `typecheck`: untyped variables are errors, nothing else. * Same spelling as `strict`, deliberately narrower. `typechecker.strict` * has one reader — the compile-path gate at compiler/compile.ts — and * `typecheck` never reaches it, so setting `strict` here would be inert * rather than harmful. An inert setting that reads as meaningful is still * a trap: it would quietly start mattering the day this command grows a * compile path. */ strictTypes?: boolean; /** `--refuse-splices`: decline compile-time generator execution. */ refuseSplices?: boolean; /** `--platform`: the platform to check the program against. */ platform?: Platform; maxToolCallRounds?: number; maxToolResultChars?: number; model?: ResolvedModelFlag; }; /** * Fold per-invocation CLI flags onto a config COPY (never mutates the input). * The single definition of what each debug flag means: * --trace → trace + traceFile= * --trace (bare) → trace + traceFile=.trace when an input path is * known (agency run), else traceDir="." (a bundled agent * with no input file → a per-run file in cwd) * --log

→ log.logFile=

and observability=true (bare → log.jsonl, * resolved in the caller that reads the flag value) * --log stdout → log.host="stdout" and observability=true (stream to stdout) * --observability → observability=true * --strict → typechecker.strict + strictTypes (the compile-path gate * never runs the checker on strictTypes alone). This is * the `run`/`compile` meaning. * --strict (tc) → typechecker.strictTypes ONLY. `agency typecheck` calls * the checker unconditionally and computes its own exit * code, so it never reaches that gate; `strict` would be * inert there, and an inert-but-meaningful-looking * setting is a trap. Same flag name, narrower meaning, * which is why it is a separate field, not a branch. * --refuse-splices → refuseSplices=true (refuse to compile a file with a * splice rather than running its generator) * --platform

→ platform=

: check the program against that * platform's capabilities * --model → client.defaultModel= and client.defaultProvider * DELETED, so smoltalk infers the provider * --model

/ → client.defaultModel= + client.defaultProvider=

* --max-tool-call-rounds → maxToolCallRounds= (baked into runPrompt at * compile time; overrides agency.json for this run) * --max-tool-result-chars → client.maxToolResultChars= (0 disables the * cap; overrides agency.json for this run) */ export declare function applyCliFlags(config: AgencyConfig, flags: CliFlags, input?: string): AgencyConfig; /** The model every LLM call uses when neither agency.json nor the call names * one, and the provider it routes through. The provider is named rather than * inferred because the inferred route for an OpenAI model is the base "openai" * client, which has no hosted web search; "openai-responses" does. */ export declare const DEFAULT_MODEL = "gpt-5-mini"; export declare const DEFAULT_PROVIDER = "openai-responses"; /** The model and provider a `client` block selects, over a fallback. A * configured provider wins. A model named without a provider has no * provider, so smoltalk picks one from the model name. With neither, the * fallback's model and provider stand. * * This is the compile-time rule: the code generator applies it with the * built-in defaults as the fallback, and the runtime merge applies it with a * program's baked values, so a child started by `run` behaves as if it had * been compiled with its parent's config. It is not the per-call rule for * `llm(model:)`, `modelProviderOverride` in `lib/runtime/llmConfig.ts`. */ export declare function defaultRoute(client: AgencyConfig["client"] | undefined, fallback: { model: string; provider?: string; }): { model: string; provider?: string; }; /** The one env var carrying a JSON Partial into an already-compiled * process (see the source-of-truth note above, source 3). */ export declare const CONFIG_OVERRIDES_ENV = "AGENCY_CONFIG_OVERRIDES"; /** Seeds the trace id of every RuntimeContext in a process tree (explicit * statelogConfig.traceId still wins). Set PER-RUN by harnesses — eval * command targets use it so descendants started without IPC (a bash * `agency run ...`) land in the same trace as their parent. Do not export * it from a shell: every subsequent run would merge into one trace. */ export declare const TRACE_ID_ENV = "AGENCY_TRACE_ID"; /** Serialize config overrides for a child process's AGENCY_CONFIG_OVERRIDES. */ export declare function serializeConfigOverrides(overrides: Partial): string; /** Read + validate AGENCY_CONFIG_OVERRIDES. Returns {} when the var is absent, * unparseable, or fails schema validation, so a malformed value can never * brick startup. Reads the default host's settings unless handed an * environment, which the CLI does for a child it is about to start. */ export declare function readConfigOverrides(env?: Record): Partial; /** Combine inherited env overrides with flag-derived ones: flags win * key-by-key, and `log` (the only nested override flag parsing writes) * merges one level deep — so a --trace flag cannot destroy an inherited * logFile, while an explicit --log still wins that key. */ export declare function mergeConfigOverrides(inherited: Partial, flags: Partial): Partial; /** Config paths that hold secrets. `agency config show` masks these. */ export declare const SECRET_CONFIG_PATHS: string[]; /** A copy of `config` with every SECRET_CONFIG_PATHS value masked to its last * four characters. For human-facing output such as `agency config show`. */ export declare function redactConfigSecrets(config: AgencyConfig): AgencyConfig;