@theokit/agents 7.6.0 → 8.0.0

package/dist/define-agent-3Kuf6iKM.d.ts

@@ -0,0 +1,633 @@
+import { McpServerConfig, SystemPromptResolver, InlineSkill, SettingSource, MemorySettings, SkillsSettings, ContextSettings, TrustPosture, CustomTool } from '@theokit/sdk';
+import { z } from 'zod';
+import { TheokitAgentError } from '@theokit/sdk/errors';
+import { H as HookHandlers } from './hook-handlers-Cw2FsnE5.js';
+
+/**
+ * Provider-agnostic extended-thinking knob (M1 reasoning-visibility). The common set autocompletes;
+ * `(string & {})` accepts provider-specific values forward-compat (mirrors `AgentRunErrorCode`) — the
+ * SDK validates the value against the model's catalog. Defined in this leaf module so every layer
+ * (`@Agent` config, compiler, runner, sdk-adapter) imports it without an import cycle.
+ */
+type ReasoningEffort = 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | (string & {});
+/** Scalar agent configuration. */
+interface AgentOptions {
+    /** Unique agent name (kebab-case). */
+    name: string;
+    /** HTTP route prefix (e.g., '/api/agents/support'). */
+    route: string;
+    /** LLM model identifier (e.g., 'claude-sonnet-4-5-20250929'). */
+    model?: string;
+    /** Extended-thinking effort; mapped to the SDK `ModelSelection.params` so the provider reasons. */
+    reasoningEffort?: ReasoningEffort;
+    /**
+     * Opt-in (default false): convert inline `<think>…</think>` in the text stream into `thinking`
+     * events (M2) — for models that emit reasoning as inline tags (qwen/deepseek) rather than via a
+     * native reasoning param. Off by default since a code assistant may emit literal `<think>` in text.
+     */
+    parseThinkTags?: boolean;
+    /**
+     * Opt-in (default false): strip a leaked Hermes `<function=…></tool_call>` tool-call dialect out of
+     * the visible text (theocode#32) — for models (qwen/qwen3-coder) that intermittently emit tool calls
+     * as text instead of native `tool_calls`. Off by default since a code assistant may emit a literal
+     * `<function=` in answer/code text. Sibling of {@link parseThinkTags}.
+     */
+    stripToolDialect?: boolean;
+    /**
+     * Opt-in (default false): recover a leaked Hermes `<function=…></tool_call>` tool-call dialect so the
+     * call actually EXECUTES (theokit#58 follow-up). Where {@link stripToolDialect} only hides the leaked
+     * block from the visible text, this enables the SDK's `extractToolCallsFromContent` on the chat route,
+     * so a `chat_completions` finish with ZERO native `tool_calls` has its text scanned for the dialect and
+     * any recovered calls are dispatched by the loop. For models (qwen/qwen3-coder via OpenRouter) that
+     * leak tool calls as text. Off by default (a code assistant may print a literal `<function=`); fail-open.
+     * Has effect only when {@link AgentOptions} routes a provider via `providers.routes`. Sibling of
+     * {@link stripToolDialect} — typically enabled together.
+     */
+    recoverLeakedToolCalls?: boolean;
+    /** Enable SSE streaming (default: true). */
+    stream?: boolean;
+    /** Maximum loop iterations before forcing a terminal response. */
+    maxIterations?: number;
+    /** Timeout in milliseconds for the entire agent run. */
+    timeoutMs?: number;
+    /**
+     * System prompt for the agent. Either a static string OR a
+     * {@link SystemPromptResolver} computed per request (V4-L.1, Axis-B) — the SDK
+     * invokes the resolver each send with the run's `SystemPromptContext` (cwd, etc.).
+     */
+    systemPrompt?: string | SystemPromptResolver;
+}
+/** Configuration stored by @MainLoop() decorator. */
+interface MainLoopOptions {
+    /** Execution strategy. */
+    strategy?: 'simple-chat' | 'plan-act-reflect' | 'react';
+    /** Maximum iterations for this loop. */
+    maxIterations?: number;
+    /** Timeout in milliseconds. */
+    timeoutMs?: number;
+}
+/** Internal representation of a resolved @MainLoop. */
+interface MainLoopMeta {
+    propertyKey: string | symbol;
+    strategy: 'simple-chat' | 'plan-act-reflect' | 'react';
+    maxIterations?: number;
+    timeoutMs?: number;
+}
+/** Configuration stored by @Toolbox() decorator. */
+interface ToolboxOptions {
+    /** Namespace prefix for all tools in this toolbox (e.g., 'support'). */
+    namespace?: string;
+}
+/** Configuration stored by @Tool() decorator. */
+interface ToolOptions {
+    /** Tool name (surfaced to LLM). */
+    name: string;
+    /** LLM-facing description. */
+    description: string;
+    /** Zod input schema — compiled to JSON Schema via defineTool(). */
+    input: z.ZodType;
+    /** Risk level (informational — feeds manifest + UI). */
+    risk?: 'low' | 'medium' | 'high';
+}
+/** Budget configuration for @Budget() decorator. */
+interface BudgetOptions {
+    /** Maximum cost in USD for this scope. */
+    maxCostUsd: number;
+    /** Rolling window for budget tracking. */
+    window?: 'daily' | 'monthly';
+}
+/** Approval configuration for @RequiresApproval() decorator. */
+interface ApprovalOptions {
+    /** Reason shown to the approver. */
+    reason: string;
+}
+/** Policy handler function type. */
+type PolicyHandler = (user: {
+    roles: string[];
+}) => boolean;
+/**
+ * M53 — moved here from the `@HumanInTheLoop` decorator, which is being deleted: the type is
+ * consumed by `compileHitlGates` and the toolbox capability, not by the decorator alone.
+ */
+type TimeoutAction = 'abort' | 'proceed' | 'retry';
+interface HumanInTheLoopOptions {
+    /** Question shown to the human approver. */
+    question: string;
+    /** Timeout in milliseconds before onTimeout fires (default: 300_000 = 5 min). */
+    timeout?: number;
+    /** Action when timeout expires (default: 'abort'). */
+    onTimeout?: TimeoutAction;
+    /** Show the tool input to the approver (default: true). */
+    showInput?: boolean;
+    /**
+     * M20 — an optional JSON-schema descriptor of the custom payload the approver may attach (edited
+     * args, a review note). Carried into the `approval_required` event + `GET /approvals` so the UI
+     * knows what to collect. A plain JSON object, not a live Zod schema (keeps the wire serializable).
+     */
+    payloadSchema?: Record<string, unknown>;
+}
+
+type McpServersMap = Record<string, McpServerConfig>;
+/** M53 — moved from the `@ProjectContext` decorator being deleted; read by the compiler. */
+type IndexStrategy = 'tree-sitter' | 'regex' | 'none';
+type RelevanceStrategy = 'git-history' | 'import-graph' | 'semantic' | 'manual';
+interface ProjectContextOptions {
+    /** Files that mark the project root (searched upward from cwd). */
+    rootMarkers?: string[];
+    /** How to index the codebase for structural understanding. */
+    indexStrategy?: IndexStrategy;
+    /** Maximum files to include in context per request. */
+    maxFilesInContext?: number;
+    /** How to rank file relevance when selecting context. */
+    relevanceStrategy?: RelevanceStrategy;
+    /** Glob patterns to exclude from indexing and context. */
+    ignorePatterns?: string[];
+    /** File extensions to include in indexing (default: all text files). */
+    includeExtensions?: string[];
+}
+type CheckpointStrategy = 'after-tool-call' | 'after-iteration' | 'manual';
+type CheckpointStorage = 'memory' | 'filesystem' | 'drizzle' | 'redis';
+interface CheckpointOptions {
+    /** Where to persist checkpoints. */
+    storage?: CheckpointStorage;
+    /** When to auto-checkpoint (default: 'after-tool-call'). */
+    strategy?: CheckpointStrategy;
+    /** Maximum checkpoints to retain per run (rolling window). */
+    maxCheckpoints?: number;
+    /** Time-to-live in ms before checkpoints expire (default: 3_600_000 = 1h). */
+    ttl?: number;
+}
+type MemoryProvider = 'built-in' | 'honcho' | 'supermemory' | 'mem0';
+type MemoryScope = 'per-user' | 'per-agent' | 'per-tenant' | 'global';
+interface MemoryOptions {
+    /** Memory provider backend. */
+    provider?: MemoryProvider;
+    /** Enable semantic search via embeddings. */
+    embeddings?: boolean;
+    /** Enable full-text search (FTS5). */
+    fts?: boolean;
+    /** Memory isolation scope (default: 'per-user'). */
+    scope?: MemoryScope;
+    /** Maximum facts to retain per scope (0 = unlimited). */
+    maxFacts?: number;
+}
+
+/**
+ * M9 (theokit-ai-first) — guardrail contract + typed errors.
+ *
+ * ADR-0040 § D2: guardrails are a HOME/BOUNDARY concern (filter user input before the SDK,
+ * filter model output before the client). They REUSE the SDK runtime — this module makes zero
+ * LLM calls. A guard reports one of three actions; the pipeline (`pipeline.ts`) enforces them.
+ */
+/** What a guard decided for a piece of text. */
+type GuardrailAction = 'allow' | 'block' | 'redact';
+/**
+ * The result of a single guard check.
+ * - `allow`  — text passes untouched.
+ * - `block`  — the pipeline throws {@link GuardrailViolationError}; the run stops fail-fast.
+ * - `redact` — the pipeline replaces the text with {@link GuardrailResult.text} and continues.
+ */
+interface GuardrailResult {
+    action: GuardrailAction;
+    /** Human-readable reason — required in spirit for `block`, surfaced in the thrown error. */
+    reason?: string;
+    /** The transformed text — present (and used) only when `action === 'redact'`. */
+    text?: string;
+}
+/**
+ * A guardrail. A guard MAY inspect input (before the model), output (after the model), or both.
+ * A guard that omits a phase hook is skipped for that phase.
+ */
+interface Guardrail {
+    readonly name: string;
+    checkInput?(text: string): GuardrailResult | Promise<GuardrailResult>;
+    checkOutput?(text: string): GuardrailResult | Promise<GuardrailResult>;
+}
+/** Which boundary phase a violation happened in. */
+type GuardrailPhase = 'input' | 'output';
+/** Thrown (fail-fast) when a guard returns `action: 'block'`. Typed per error-handling.md. */
+/**
+ * M80 — extends {@link TheokitAgentError}, not plain `Error`.
+ *
+ * `isTransientError` is defined over `TheokitAgentError`, so a class outside that hierarchy is
+ * INVISIBLE to it and the only recourse left to a consumer is matching on message text — a regex
+ * over an eight-level `cause` chain, which is what one actually wrote. `code` is stable across a
+ * rename of the class; `isRetryable` is DECLARED rather than defaulted, because a default would be a
+ * retry policy nobody chose.
+ */
+declare class GuardrailViolationError extends TheokitAgentError {
+    readonly guardName: string;
+    readonly phase: GuardrailPhase;
+    readonly reason: string;
+    readonly name = "GuardrailViolationError";
+    constructor(guardName: string, phase: GuardrailPhase, reason: string);
+}
+/** Thrown when {@link costGuard}'s cumulative token budget is exceeded. */
+/**
+ * M80 — extends {@link TheokitAgentError}, not plain `Error`.
+ *
+ * `isTransientError` is defined over `TheokitAgentError`, so a class outside that hierarchy is
+ * INVISIBLE to it and the only recourse left to a consumer is matching on message text — a regex
+ * over an eight-level `cause` chain, which is what one actually wrote. `code` is stable across a
+ * rename of the class; `isRetryable` is DECLARED rather than defaulted, because a default would be a
+ * retry policy nobody chose.
+ */
+declare class CostBudgetExceededError extends TheokitAgentError {
+    readonly usedTokens: number;
+    readonly maxTokens: number;
+    readonly name = "CostBudgetExceededError";
+    constructor(usedTokens: number, maxTokens: number);
+}
+
+/**
+ * M13 (theokit-ai-first) — per-request skills resolution (ADR-0040 § D2, home/boundary concern).
+ *
+ * The static `skills.enabled` filter already works (`compile-skills` maps `include` → the SDK's
+ * `enabled`). This adds a PER-REQUEST resolver so multi-tenant apps expose different skill sets to
+ * different users. A selection is either a static list or a function of the request context (the M7
+ * run-context). Discovery + injection stay in the SDK; this only CHOOSES the enabled set per call.
+ */
+
+/** The request context handed to a skills resolver (the M7 run-context — opaque per-request data). */
+type SkillsRequestContext = Record<string, unknown>;
+/**
+ * How the skill set is chosen:
+ * - a static array of `string` (filesystem skill NAMES → `skills.enabled`) and/or `InlineSkill`
+ *   objects from `createSkill` (code-defined skills → `skills.inline`, injected into the `<skills>`
+ *   block). A mixed list is split at compile time.
+ * - a function — resolved per request from the {@link SkillsRequestContext} (sync or async). The
+ *   resolver returns filesystem skill NAMES (inline skills are static — declared on the agent).
+ */
+type SkillsSelection = readonly (string | InlineSkill)[] | ((ctx: SkillsRequestContext) => readonly string[] | Promise<readonly string[]>);
+/**
+ * Resolve the enabled skill names for a request. Returns `undefined` when no selection is given (the
+ * SDK then enables every discovered skill). Fails fast if a resolver returns a non-array. The static
+ * array is compiled ahead of time (see `compileSkillsSelection`), so this is exercised for the
+ * resolver form; a static array is defensively narrowed to its string (name) members.
+ */
+declare function resolveEnabledSkills(selection: SkillsSelection | undefined, ctx: SkillsRequestContext): Promise<string[] | undefined>;
+
+/**
+ * Agent compiler — transforms decorator metadata into SDK calls.
+ *
+ * Per ADR D1: @Agent is a macro over Agent.create().
+ * Per ADR D3: @Tool compiles to defineTool().
+ *
+ * EC-3: throws if toolbox instance is missing from the instances map.
+ */
+
+/**
+ * M53 — the input shape `compileTools`/`compileHitlGates` consume, declared WITH them now that the
+ * metadata walk that used to own it is gone. `ToolboxCapability` builds this from a class'
+ * `static tools` declaration.
+ */
+/** A guard/interceptor class token — identity only (the DI container instantiates it). */
+type ClassToken = abstract new (...args: never[]) => object;
+interface ToolWalkResult {
+    propertyKey: string | symbol;
+    config: ToolOptions;
+    guards: ClassToken[];
+    approval?: ApprovalOptions;
+    capabilities?: string[];
+    budget?: BudgetOptions;
+    trace: boolean;
+    audit: boolean;
+    /** HITL config when the tool is gated (M4); absent ⇒ not gated. */
+    hitl?: HumanInTheLoopOptions;
+}
+interface ToolboxWalkResult {
+    /** The toolbox class — used as the identity key into `toolboxInstances`. */
+    class: ClassToken;
+    namespace: string;
+    tools: ToolWalkResult[];
+    guards: ClassToken[];
+}
+/** Minimal interface matching defineTool() result shape. */
+interface CompiledTool {
+    name: string;
+    description: string;
+    inputSchema: unknown;
+    /**
+     * M7 — the optional 2nd `ctx` arg carries the SDK run context: `ctx.context` is the
+     * `defineAgent({ context })` / per-run value, `ctx.signal` the abort signal. Optional so the
+     * decorator `@Tool` handlers (which ignore it) stay assignable. The SDK calls the tool with
+     * both args; a handler that needs run-context (e.g. a filesystem tool reading `projectRoot`)
+     * reads `ctx?.context`.
+     */
+    handler: (input: unknown, ctx?: {
+        signal?: AbortSignal;
+        context?: unknown;
+    }) => string | Promise<string>;
+}
+/**
+ * Compile @Tool metadata into tool definitions.
+ *
+ * @param toolboxes - Walked toolbox metadata
+ * @param toolboxInstances - Map of Toolbox class → instantiated object (for `this` binding)
+ */
+declare function compileTools(toolboxes: ToolboxWalkResult[], toolboxInstances: Map<ClassToken, object>): CompiledTool[];
+/** Compiled sub-agent definition matching SDK AgentDefinition shape. */
+interface CompiledSubAgent {
+    model?: string;
+    /**
+     * V4-L.1: typed as the union for consistency with `AgentOptions.systemPrompt`,
+     * so `compileSubAgents` carries whatever the sub-agent declared. Sub-agent
+     * resolver EXECUTION is out of scope this slice (ADR D3): `compiled.agents` is
+     * not spread into `Agent.create` by `createSdkAgentStream`; a resolver here is
+     * carried, not invoked. Top-level agent resolvers are the supported path.
+     */
+    systemPrompt?: string | SystemPromptResolver;
+}
+/** Compiled agent options ready for SDK Agent.create(). */
+interface CompiledAgentOptions {
+    model?: string;
+    /** Extended-thinking effort; mapped to SDK ModelSelection.params. */
+    reasoningEffort?: ReasoningEffort;
+    /** Opt-in `<think>`-tag extraction (M2); wraps the stream when true. */
+    parseThinkTags?: boolean;
+    /** Opt-in tool-dialect stripping (theocode#32); strips leaked `<function=…></tool_call>` from text when true. */
+    stripToolDialect?: boolean;
+    /** Opt-in leaked-dialect recovery (theokit#58); enables the SDK route's `extractToolCallsFromContent` so leaked tool calls EXECUTE when true. */
+    recoverLeakedToolCalls?: boolean;
+    /** Static prompt OR a per-request {@link SystemPromptResolver} (V4-L.1, Axis-B). */
+    systemPrompt?: string | SystemPromptResolver;
+    /**
+     * theokit-file-based-config — opt-in `.theokit/` file-based config roots (`"project"`/`"user"`/…).
+     * Projected into `Agent.create({ local: { settingSources } })` by `assembleM8CreateOptions`
+     * (merged with `cwd`, decoupled from inline skills). Absent ⇒ inline (code) config only.
+     */
+    settingSources?: readonly SettingSource[];
+    /** Code `Plugin` objects forwarded to `Agent.create({ plugins })` (lifecycle-hook seam). */
+    plugins?: readonly unknown[];
+    tools: CompiledTool[];
+    agents: Record<string, CompiledSubAgent>;
+    memory?: MemoryOptions | MemorySettings;
+    skills?: SkillsSettings;
+    context?: ContextSettings;
+    /**
+     * M7 — run-context injected into every tool handler's `ctx.context` by the theokit adapter
+     * (`buildSdkTools` wrapper). Populated by `defineAgent({ context })` (functional surface).
+     * NAME NOTE: distinct from the context-window `context` (`ContextSettings`) above — this is
+     * per-run user data for tools, not token-budget config.
+     */
+    runContext?: Record<string, unknown>;
+    /** Raw @ProjectContext config; the adapter builds the (async) systemPrompt resolver from it. */
+    projectContext?: ProjectContextOptions;
+    mcpServers?: McpServersMap;
+    maxIterations?: number;
+    timeoutMs?: number;
+    stream: boolean;
+    /**
+     * HITL gate map (M4): runtime tool name → `@HumanInTheLoop` config. Absent/empty ⇒ no gated
+     * tools. The harness (`mountAgent`) turns this into the `pre_tool_call` pause wiring.
+     */
+    hitl?: Map<string, HumanInTheLoopOptions>;
+    /**
+     * `@Checkpoint` config (M4): when present the harness emits `checkpoint_saved` and selects the
+     * durable SDK conversation storage (`storage: 'filesystem'`) so a same-`sessionId` request resumes.
+     */
+    checkpoint?: CheckpointOptions;
+    /**
+     * M9 — guardrails: input/output guards applied at the framework boundary (ADR-0040 § D2).
+     * Input guards run on the user message BEFORE the SDK runtime sees it (fail-fast on `block`).
+     * They REUSE the runtime; they never reimplement it. Absent/empty ⇒ no guards.
+     */
+    guardrails?: readonly Guardrail[];
+    /**
+     * M13 — per-request skills resolver (from `defineAgent({ skills: (ctx) => [...] })`). The request
+     * path resolves it against the run-context (`resolveEnabledSkills`) and sets `skills.enabled`
+     * before the SDK runs. Not consumed by the SDK directly (it reads `skills`). Absent ⇒ no resolver.
+     */
+    skillsResolver?: SkillsSelection;
+}
+
+/**
+ * M68 — the trust gate for `settingSources`.
+ *
+ * ## The defect this module closes
+ *
+ * `settingSources` enables on-disk config discovery. `'user'` reads `~/.theokit/` — the operator's
+ * own machine, which no third party controls. `'project'` reads `<cwd>/.theokit/`, **including
+ * `hooks.json`, which executes shell**.
+ *
+ * The previous API took `readonly SettingSource[]`, and its JSDoc justified the risk this way:
+ * *"it is opt-in because `.theokit/` is the app's own repo (informed consent)"*. That premise holds
+ * for a web app whose `cwd` is its own deploy. It does **not** hold for the class of product this
+ * framework addresses — an agent whose `cwd` is a repository the user just cloned. There `.theokit/`
+ * is attacker-controlled content, and enabling `'project'` is remote code execution on the first
+ * `build()`.
+ *
+ * Documenting it did not prevent it. The measured consumer (TheoCode) did not trust the API: it
+ * gated from the outside, with a `posture.allows` of its own (`chat.ts:386`, comment B-008). It
+ * already **had** the right decision and could not pass it through, because the API only accepted
+ * strings. The gate existed on its side and evaporated at the boundary.
+ *
+ * ## The evidence is the SDK's, not one invented here
+ *
+ * `TrustPosture` is `@theokit/sdk`'s own trust primitive, and `recordWiring`'s doc says *"a posture
+ * is the only thing in this package that retains a capability"*. A bespoke type would make two trust
+ * grammars coexist and drift apart (ADR 0063).
+ */
+/**
+ * The framework's capability vocabulary — deliberately a single name (ADR 0065).
+ *
+ * `allows` is all-or-nothing in the SDK: every declared `K` gets the same boolean. A finer
+ * vocabulary (`hooks`, `skills`, `subagents`, `mcp`) would promise the consumer it can gate one
+ * without gating the other, and the primitive does not deliver that. An API that suggests a
+ * distinction the runtime does not make teaches the wrong thing, and the error only surfaces when
+ * somebody depends on the distinction.
+ */
+type SettingSourceCapability = 'projectSettings';
+/** Authorization to read config from the working directory. Requires the posture, never a claim. */
+interface ProjectSettingsGrant {
+    /**
+     * Typically the output of `resolveTrustPosture` — which is what gives it `source` (`'env' |
+     * 'store' | 'default'`) and therefore a refusal that says WHERE the decision came from instead of
+     * merely denying.
+     */
+    readonly trustedBy: TrustPosture<SettingSourceCapability>;
+}
+/**
+ * Which on-disk config roots the agent may read.
+ *
+ * The asymmetry is the design: `user` is a boolean because `~/.theokit/` belongs to the operator;
+ * `project` requires evidence because `<cwd>/.theokit/` may not. Omitting a root is not enabling it
+ * — never "enabling without a gate". The asymmetry is inherited from the SDK itself, whose
+ * `TrustPostureInput.envOverride` documents that `false` and `undefined` both mean "the operator did
+ * not turn it on", not "turned it off".
+ */
+interface SettingSourcesSelection {
+    /** `~/.theokit/` — the operator's machine. No gate: no third party controls it. */
+    readonly user?: boolean;
+    /** `<cwd>/.theokit/` — controlled by whoever wrote the open repository. Requires evidence. */
+    readonly project?: ProjectSettingsGrant;
+}
+/**
+ * Refusal to read the working directory for lack of trust.
+ *
+ * Descends from `TheokitAgentError` because typed errors are an unbreakable rule here — and because
+ * `isTransientError` only sees this hierarchy. A class extending plain `Error` would be invisible to
+ * the predicate that separates recoverable from unrecoverable (the defect M67 fixed in five
+ * classes).
+ */
+declare class UntrustedSettingSourceError extends TheokitAgentError {
+    /** Where the trust decision came from: `'env' | 'store' | 'default'`. */
+    readonly trustSource: string;
+    /** The refused capability. */
+    readonly capability: SettingSourceCapability;
+    readonly name = "UntrustedSettingSourceError";
+    constructor(message: string, 
+    /** Where the trust decision came from: `'env' | 'store' | 'default'`. */
+    trustSource: string, 
+    /** The refused capability. */
+    capability: SettingSourceCapability);
+}
+/**
+ * Translate the declared selection into the `SettingSource`s the SDK accepts, refusing what the
+ * posture does not authorize.
+ *
+ * Refuses rather than ignores (ADR 0064). Ignoring would leave the product running in the belief
+ * that the repository's hooks are active — a silent failure mode, on the wrong side. The SDK already
+ * picked that side for the same problem: `recordWiring` throws `UngatedCapabilityError` when
+ * somebody registers a capability the posture does not gate.
+ *
+ * @throws {UntrustedSettingSourceError} when `project` is requested and the posture does not grant it.
+ */
+declare function resolveSettingSources(selection: SettingSourcesSelection | undefined): readonly SettingSource[];
+
+/**
+ * M2 (theokit-ai-first) — `defineAgent`, the zero-config imperative agent surface.
+ *
+ * ADR-B1: `defineAgent({...})` (default-exported from a top-level `agents/<name>.ts`) is
+ * the canonical zero-config surface; the `@Agent` class decorator stays the advanced/DI
+ * surface. Both compile to {@link CompiledAgentOptions} and run through the same SDK
+ * runtime (`createSdkAgentStream`) — one runtime, two syntaxes.
+ *
+ * This module is PURE metadata (sdk-runtime.md / G2): `defineAgent` describes an agent, it
+ * NEVER calls an LLM. It imports only `zod` (types) + the compiler shape — no `theokit`
+ * core, preserving the agents → (nothing) dependency direction (G1).
+ */
+
+/**
+ * Brand tag for a `defineAgent` value. `Symbol.for` (global registry, not `Symbol()`) so
+ * the brand survives duplicate module instances (dual-package / bundling) — the scanner's
+ * brand-check then works regardless of which copy created the definition.
+ */
+declare const AGENT_BRAND: unique symbol;
+/** Config accepted by {@link defineAgent}. */
+interface DefineAgentConfig<TInput extends z.ZodType = z.ZodType> {
+    /** Zod schema for the request body — lifted into the typed client (M2, {@link InferAgentInput}). */
+    input?: TInput;
+    /** Model id (e.g. `claude-sonnet-4-6`). Falls back to the SDK default when omitted. */
+    model?: string;
+    /** Static system prompt. */
+    system?: string;
+    /** Extended-thinking effort. */
+    reasoningEffort?: ReasoningEffort;
+    /**
+     * Pre-built tools. Accepts the `@theokit/sdk` `CustomTool` that `defineAgentTool`
+     * (theokit/server) and every `@theokit/sdk-tools` factory return (issue #81) — they are
+     * normalized to the internal {@link CompiledTool} shape at compile time.
+     */
+    tools?: readonly CustomTool[];
+    /**
+     * M7 — run-context: an opaque, per-agent object forwarded to every tool handler's
+     * `ctx.context` at run time (injected by the theokit adapter's tool wrapper). Set shared config
+     * (e.g. `{ projectRoot }`) ONCE at the agent level instead of baking it into each tool
+     * factory. Mirrors ai-sdk `experimental_context`, mastra `RuntimeContext`, and
+     * openai-agents-js `RunContext`. Distinct from `@Agent`'s context-window `context`.
+     */
+    context?: Record<string, unknown>;
+    /**
+     * M9 — guardrails: input/output guards applied at the framework boundary (ADR-0040 § D2).
+     * Input guards run on the user message before the SDK runtime; a `block` fails the run fast.
+     * Built-ins live in `@theokit/agents` (`promptInjectionDetector`, `piiDetector`, `costGuard`,
+     * `unicodeNormalizer`, `outputModeration`).
+     */
+    guardrails?: readonly Guardrail[];
+    /**
+     * M14 — HITL approvals keyed by tool name. Each gated tool pauses the run and emits an
+     * `approval_required` event until approved (reuses the same `compiled.hitl` wiring the `@Agent`
+     * + `@HumanInTheLoop` path produces). A key that does not match a declared tool fails fast at
+     * compile time.
+     */
+    approvals?: Record<string, HumanInTheLoopOptions>;
+    /**
+     * M13 — skills selection: a static list (compiled straight to the SDK `skills.enabled`) OR a
+     * per-request resolver `(ctx) => string[]` (carried on `compiled.skillsResolver`, resolved by the
+     * request path against the run-context). Absent ⇒ the SDK enables every discovered skill.
+     */
+    skills?: SkillsSelection;
+    /**
+     * theokit-file-based-config — opt into `.theokit/` file-based config (skills, subagents, hooks,
+     * MCP, context, cron). The SDK discovers config from these roots under the app's `cwd`:
+     * `project` = `<cwd>/.theokit/`, `user` = `~/.theokit/`. Absent ⇒ inline (code) config only.
+     *
+     * SECURITY (M68): `project` reads `.theokit/hooks.json`, which **executes shell**, so it requires
+     * a `TrustPosture` rather than a string. This field used to take `readonly SettingSource[]`, and
+     * its own JSDoc justified the risk as *"opt-in because `.theokit/` is the app's own repo (informed
+     * consent)"*. That premise holds for a web app whose `cwd` is its own deploy; it does not hold for
+     * an agent whose `cwd` is a repository the user just cloned, where `.theokit/` is
+     * attacker-controlled content.
+     *
+     * `user` stays a plain boolean — `~/.theokit/` is the operator's own machine. Omitting a root is
+     * not enabling it. The SDK owns discovery + execution (G2 / ADR-0040); theokit resolves the
+     * selection through `resolveSettingSources` and wires the result into
+     * `Agent.create({ local.settingSources })`.
+     */
+    settingSources?: SettingSourcesSelection;
+    /**
+     * M49 — durable memory (the SDK's `.theokit/memory/` subsystem: `Remember:` capture, MEMORY.md
+     * store, auto-injected `<memory>` block, `memory_search`/`memory_get` tools). The shape is the
+     * SDK's own `MemorySettings` — the canonical runtime contract. Projected into
+     * `Agent.create({ memory })` by `assembleM8CreateOptions`.
+     */
+    memory?: MemorySettings;
+    /**
+     * Code `Plugin` objects forwarded to `Agent.create({ plugins })` — EXTENSION units (tools,
+     * commands, model providers, memory adapters). For lifecycle interception use {@link hooks}.
+     */
+    plugins?: readonly unknown[];
+    /**
+     * Lifecycle hooks keyed by `HookName` (`pre_tool_call` may veto via `{ block, message }`). Set by
+     * the builder's `hooks()`; converted into a code plugin at `build()` and never reaching the SDK
+     * under this name — the plugin is the TRANSPORT, this is the contract callers write against.
+     */
+    hooks?: HookHandlers | Readonly<Record<string, unknown>>;
+    /**
+     * MCP servers available to the agent — the builder-chain equivalent of the `@MCP` class
+     * decorator. Each key is a server name; the value is the server configuration. Forwarded
+     * unchanged to `Agent.create({ mcpServers })` (the SDK owns MCP execution). Absent ⇒ no MCP.
+     */
+    mcpServers?: McpServersMap;
+}
+/**
+ * A branded agent definition — the value {@link defineAgent} returns.
+ *
+ * `TTools` (M8) is a phantom type parameter carrying the tool-name union: the `AgentBuilder.create()` builder
+ * threads its accumulated literal tool names here (`.build()` returns `AgentDefinition<TInput,
+ * 'a' | 'b'>`), so the generated client (`.theokit/agents.d.ts`) can expose them via
+ * {@link InferAgentToolNames}. `defineAgent` leaves it `string` (its tools array carries no literal
+ * names). Never present at runtime.
+ */
+type AgentDefinition<TInput extends z.ZodType = z.ZodType, TTools extends string = string> = DefineAgentConfig<TInput> & {
+    readonly [AGENT_BRAND]: true;
+    readonly __toolNames?: TTools;
+};
+/** Infer the request type of an agent definition from its `input` Zod schema. */
+type InferAgentInput<T> = T extends AgentDefinition<infer S> ? (S extends z.ZodType ? z.infer<S> : never) : never;
+/**
+ * Infer the tool-name union of an agent definition (M8). Yields the literal union for agents built
+ * with the `AgentBuilder.create()` builder (`'read_file' | 'count_lines'`), or `string` for `defineAgent` agents
+ * whose tools array carries no literal names.
+ */
+type InferAgentToolNames<T> = T extends AgentDefinition<z.ZodType, infer N> ? N : never;
+/** Brand-check: is `value` a {@link defineAgent} result? */
+declare function isAgentDefinition(value: unknown): value is AgentDefinition;
+/**
+ * Lower a definition to the SDK-ready {@link CompiledAgentOptions} — the same shape
+ * `compileAgent` (decorator path) produces, so both surfaces converge on one runtime.
+ */
+declare function compileAgentDefinition(def: AgentDefinition): CompiledAgentOptions;
+
+export { type AgentDefinition as A, type BudgetOptions as B, type CompiledAgentOptions as C, type DefineAgentConfig as D, type Guardrail as G, type HumanInTheLoopOptions as H, type InferAgentInput as I, type MainLoopMeta as M, type PolicyHandler as P, type ReasoningEffort as R, type SettingSourcesSelection as S, type ToolOptions as T, UntrustedSettingSourceError as U, type CompiledTool as a, type ApprovalOptions as b, AGENT_BRAND as c, type AgentOptions as d, CostBudgetExceededError as e, type GuardrailAction as f, type GuardrailPhase as g, type GuardrailResult as h, GuardrailViolationError as i, type InferAgentToolNames as j, type MainLoopOptions as k, type McpServersMap as l, type ProjectSettingsGrant as m, type SettingSourceCapability as n, type SkillsRequestContext as o, type SkillsSelection as p, type TimeoutAction as q, type ToolWalkResult as r, type ToolboxOptions as s, type ToolboxWalkResult as t, compileAgentDefinition as u, compileTools as v, isAgentDefinition as w, resolveEnabledSkills as x, resolveSettingSources as y, type ProjectContextOptions as z };