@sema-agent/core/dist/config/catalog.d.ts

Stateless, task-oriented AI agent core

/**
 * Config catalog (ruled 2026-07-19) — the SINGLE machine-readable source for the engineering
 * configuration scale across every client (server / cli / TB harness / future shells).
 *
 * Why this exists: the same knob was found carrying FIVE different values across layers (maxTurns:
 * core default 1000, TB cloud harness 80, a box-side adapter 500, cloud_companion 200, a server env
 * cap) with no layer aware of the others. The catalog is the anti-chaos contract:
 *
 *   1. **Recommended values are imported from the live constants** — never hand-copied. A drift
 *      between catalog and engine is a compile/test failure, not a doc bug.
 *   2. **Clients don't hand-write numbers.** A client either inherits the recommendation (writes
 *      nothing) or overrides it and DECLARES the override (`TaskSpec.configOverrides`, with a
 *      reason). Declared overrides ride the `config.assembled` trace, so every run self-reports its
 *      true knobs and their provenance — "who set 80" becomes a trace read, not archaeology.
 *   3. **Announced change discipline**: the recommendations are a living baseline — any repo
 *      changing one (or overriding persistently) posts the change to the shared config record so the
 *      scale evolves deliberately, together.
 *
 * v1 scope: the cross-client TASK-LAUNCH knobs (the chaos surface). Internal engine tuning
 * (compaction thresholds, retry ladders…) stays out until a real cross-repo consumer appears.
 */
import type { TaskLimits } from "../core/types.js";
export declare const CONFIG_CATALOG_VERSION = "sema-config@1";
export interface ConfigKnob {
    /** Dotted catalog key, e.g. `limits.maxTurns`. Stable — clients key parity probes off it. */
    key: string;
    /** The recommended value. `null` = deliberately UNSET (the summary says what unset means). */
    recommended: number | boolean | string | null;
    unit?: "turns" | "seconds" | "ms" | "days" | "usd" | "tokens" | "count";
    /** What kind of knob this is: a runaway safety net, a spend bound, a behavior switch, retention. */
    kind: "safety-net" | "budget" | "behavior" | "retention";
    /** One-line semantics, including the meaning of unset and any derived-default coupling. */
    summary: string;
    /** Who may set it and who wins (highest first). */
    precedence: string;
}
/** The v1 catalog. Recommended values reference the LIVE constants — the totality pin in
 *  `test/config-catalog.test.ts` fails if an entry and its engine source diverge. */
export declare function describeConfigCatalog(): {
    version: string;
    knobs: ConfigKnob[];
};
/**
 * A host-layer override DECLARATION (`TaskSpec.configOverrides`) — the "changes must be announced"
 * mechanical hook. A host that overrides a catalog knob at its own layer (env cap, adapter flag,
 * harness default) attaches the declaration so the override rides the `config.assembled` trace with
 * provenance `host-declared` instead of being invisible. Advisory: declarations are observability
 * metadata — they do not themselves change any effective value.
 */
export interface ConfigOverrideDeclaration {
    /** Catalog key (`limits.maxTurns`) — or a host-namespaced key (`tb.harness.maxTurns`) for knobs
     *  that live entirely outside core. */
    key: string;
    value: number | boolean | string | null;
    /** Why this deployment deviates from the recommendation — required; this is the announcement. */
    reason: string;
}
export type ConfigProvenance = "default" | "spec" | "derived" | "host-declared";
/** One field of the effective-config manifest (`config.assembled`). */
export interface EffectiveConfigField {
    key: string;
    value: number | boolean | string | null;
    provenance: ConfigProvenance;
}
/** Declaration bounds: host strings ride the trace stream — bounded and sanitized, never
 *  free-form. Beyond `MAX_OVERRIDE_DECLARATIONS` entries are dropped (count-capped, first-N kept). */
export declare const MAX_OVERRIDE_DECLARATIONS = 32;
/**
 * Build the effective task-launch config + provenance from a spec's launch fields. Pure. The
 * manifest must mirror ENGINE truth, not the spec's surface: `maxOutputTokens` falls back
 * to the model's own cap (provenance `derived`) before "provider default".
 */
export declare function resolveEffectiveConfig(spec: {
    limits?: Pick<TaskLimits, "maxTurns" | "maxWalltimeMs" | "maxOutputTokens" | "maxCostUsd" | "maxTokens">;
    resourceSuspend?: {
        totalTokens?: number;
        totalBudgetUsd?: number;
    };
    configOverrides?: readonly ConfigOverrideDeclaration[];
}, ctx?: {
    modelMaxTokens?: number;
}): EffectiveConfigField[];
/** Bounded, sanitized reasons map for the manifest's announcement face. */
export declare function declarationReasons(declarations: readonly ConfigOverrideDeclaration[] | undefined): Record<string, string>;