@theokit/agents 14.5.0 → 15.0.0

package/dist/define-agent-y3fsG91f.d.ts

@@ -1,188 +0,0 @@
-import { CustomTool, MemorySettings, TelemetrySettings } from '@theokit/sdk';
-import { z } from 'zod';
-import { G as Guardrail, S as SkillsSelection, H as HookApprovalGate, C as CodePlugin, a as CompiledAgentOptions } from './agent-compiler-D7-Xd6Zh.js';
-import { R as ReasoningEffort, H as HumanInTheLoopOptions, M as McpServersMap } from './types-C16Wuh9E.js';
-import { H as HookHandlers } from './hook-handlers-Cw2FsnE5.js';
-import { S as SettingSourcesSelection } from './setting-sources-gate-BJJiKq33.js';
-
-/**
- * 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;
-    /**
-     * theokit#363 — hard ceiling on the agent's tool-calling turns within ONE run. Reaching it ends
-     * the turn instead of letting the model keep calling tools; absent ⇒ the SDK's own ceiling (8).
-     *
-     * Named `maxIterations`, not `maxSteps`, because the concept already has exactly one name here —
-     * `@Agent({ maxIterations })`, `@MainLoop({ maxIterations })`, `AgentRunner.stream({ maxIterations })`,
-     * `delegate({ maxIterations })` — and one name in the SDK it lowers to (`SendOptions.maxIterations`).
-     * A second name would be the only place needing translation, and the translation is invisible where
-     * it costs most: the SDK rejects an invalid value with a message naming `SendOptions.maxIterations`,
-     * which an author who typed `.maxSteps()` has no way to connect to what they wrote. Familiarity
-     * argues for the ai-sdk spelling, but ai-sdk's own name is `stopWhen: stepCountIs(n)` — borrowing
-     * "steps" would buy recognition of a word, not of an API.
-     */
-    maxIterations?: number;
-    /**
-     * 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;
-    /**
-     * #686 — decide whether a hook declared in a config root is spawned at all, BEFORE it runs.
-     *
-     * Covers any root, including a foreign dialect imported through `settingSources.claudeCode`.
-     * Requires `@theokit/sdk >= 5.4.0`: declaring it against an older SDK is REFUSED at assembly
-     * rather than forwarded, because a gate that silently does not gate is worse than none.
-     */
-    hookApproval?: HookApprovalGate;
-    /**
-     * B-054 — `MEMORY.md` here is NOT the Claude Code CLI's auto-memory file. This is the durable
-     * subsystem below: a SQLite+FTS5 store under `.theokit/memory/`, with `memory_search`/`memory_get`
-     * tools and no index cap. The CLI's lives under its own home (`CLAUDE_CONFIG_DIR` or `~/.claude`),
-     * is capped at 200 lines / 25 KB on read, and is swept on `cleanupPeriodDays` — none of which is
-     * implemented here. The SDK READS that directory for interop and does not write to it.
-     *
-     * Same filename, different directory, different semantics. Stated at both ends because a checklist
-     * that greps for `MEMORY.md` finds one and concludes the other exists.
-     *
-     * 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;
-    /**
-     * B-072 — OpenTelemetry for this agent. Forwarded verbatim to `Agent.create({ telemetry })`,
-     * where the SDK emits spans for `agent.send`, `llm.call`, `tool.call` and `memory.search`.
-     *
-     * `{ enabled: true }` is the minimal opt-in. `@opentelemetry/api` is an OPTIONAL peer of the SDK:
-     * without it the whole thing is a silent no-op, which is the usual reason a run reports no spans.
-     */
-    telemetry?: TelemetrySettings;
-    /**
-     * Code `Plugin` objects forwarded to `Agent.create({ plugins })` — EXTENSION units (tools,
-     * commands, model providers, memory adapters). For lifecycle interception use {@link hooks}.
-     */
-    /**
-     * Code plugins — `{ name, register }`. NOT the Claude Code filesystem-bundle form, which is
-     * declared by living in a `plugins/` directory rather than by being passed here (B-055).
-     *
-     * `readonly unknown[]` is what let the wrong shape through silently.
-     */
-    plugins?: readonly CodePlugin[];
-    /**
-     * 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 DefineAgentConfig as D, type InferAgentInput as I, AGENT_BRAND as a, type InferAgentToolNames as b, compileAgentDefinition as c, isAgentDefinition as i };