@theokit/agents 9.3.0 → 9.4.0

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

@@ -0,0 +1,236 @@
+import { TrustPosture, SettingSource, CustomTool, MemorySettings } from '@theokit/sdk';
+import { z } from 'zod';
+import { R as ReasoningEffort, G as Guardrail, H as HumanInTheLoopOptions, S as SkillsSelection, M as McpServersMap, C as CompiledAgentOptions } from './agent-compiler-CIPQkehU.js';
+import { H as HookHandlers } from './hook-handlers-Cw2FsnE5.js';
+import { TheokitAgentError } from '@theokit/sdk/errors';
+
+/**
+ * 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 DefineAgentConfig as D, type InferAgentInput as I, type ProjectSettingsGrant as P, type SettingSourcesSelection as S, UntrustedSettingSourceError as U, AGENT_BRAND as a, type InferAgentToolNames as b, type SettingSourceCapability as c, compileAgentDefinition as d, isAgentDefinition as i, resolveSettingSources as r };