import { AgencyNode } from "./types.js"; import type { LogLevel } from "./logger.js"; import { z } from "zod"; 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/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; /** * 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; 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; }; }>; /** Eval command configuration */ eval?: { runsDir?: string; optimizeRunsDir?: string; 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; }; baseUrl: { openRouter?: string; deepInfra?: string; liteLlm?: string; openAiCompat?: 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; /** * 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 → Hugging Face URI aliases for local models, used by * `std::agency/local` and the `agency local` CLI. 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; 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"; /** * 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"; }; /** Enable debugger mode — auto-inserts breakpoints before every step */ debugger?: boolean; /** 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"; /** 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). */ model?: string; }; }; /** * Visual thresholds used by `agency logs view`. Durations at or * above `slowMs` (default 5000) render bright-red; durations below * `fastMs` (default 100) render gray. Costs at or above * `expensiveUsd` (default 0.01) render bright-red. */ 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[]; }; } export declare const AgencyConfigSchema: z.ZodObject<{ verbose: z.ZodOptional; allowNonAgencyGenerators: 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>>; }, z.core.$strip>>; eval: z.ZodOptional; optimizeRunsDir: z.ZodOptional; 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; }, z.core.$strip>>; baseUrl: z.ZodOptional; deepInfra: z.ZodOptional; liteLlm: z.ZodOptional; openAiCompat: z.ZodOptional; }, z.core.$strip>>; maxToolResultChars: z.ZodOptional; providerModules: z.ZodOptional>; modelAliases: z.ZodOptional>; modelsDir: z.ZodOptional; 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>; strictMemberAccess: z.ZodOptional>; matchExhaustiveness: z.ZodOptional>; definiteReturns: z.ZodOptional>; }, z.core.$strip>>; debugger: z.ZodOptional; instrument: z.ZodOptional; checkpoints: z.ZodOptional; }, z.core.$strip>>; maxCallDepth: z.ZodOptional; failurePropagation: z.ZodOptional>; 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; }, z.core.$strip>>; }, z.core.$strip>>; }, z.core.$loose>; /** * Load agency.json at the given path without calling process.exit. * Returns the parsed config, or an error message if the file is invalid. * Returns an empty config if the file doesn't exist. */ export declare function loadConfigSafe(configPath: string): { config: AgencyConfig; error?: string; }; /** * Find the agency.json for a given file path by searching upward. * Returns the directory containing agency.json, or null if not found. */ export declare function findProjectRoot(startPath: string): string | null; /** 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?: boolean; maxToolCallRounds?: number; maxToolResultChars?: number; }; /** * 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) * --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 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"; /** 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. */ export declare function readConfigOverrides(env?: NodeJS.ProcessEnv): Partial; /** Return a deep copy of `config` with secret-bearing fields masked, for * human-facing output (`agency config show`). Masks every `apiKey` — the * top-level `log.apiKey` string and each key under `client.apiKey` / * `client.statelog.apiKey` — to `•••`. */ export declare function redactConfigSecrets(config: AgencyConfig): AgencyConfig;