@theokit/agents 0.46.0 → 1.0.0

package/dist/types-DVA4LQsA.d.ts

@@ -1,313 +0,0 @@
-import { SystemPromptResolver } from '@theokit/sdk';
-import { z } from 'zod';
-
-/**
- * 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 & {});
-/** Configuration stored by @Agent() decorator. */
-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;
-
-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;
-}
-/** Serializable checkpoint state. */
-interface CheckpointState {
-    id: string;
-    runId: string;
-    agentName: string;
-    step: number;
-    messages: unknown[];
-    toolResults: unknown[];
-    createdAt: number;
-    resumeToken: string;
-}
-declare function Checkpoint(options?: CheckpointOptions): ClassDecorator;
-declare function getCheckpointConfig(target: Function): CheckpointOptions | undefined;
-
-/** Stored `@Compaction` declaration (resolved + validated at `AgentRunner.build()`). */
-interface CompactionDecoratorConfig {
-    /** Strategy name (e.g. `'token-budget'`). Validated at resolve time. */
-    name: string;
-    /** Token budget for `'token-budget'`. Required at resolve time (EC-2). */
-    keepTokens?: number;
-}
-declare function Compaction(name: string, options?: {
-    keepTokens?: number;
-}): ClassDecorator;
-declare function getCompactionConfig(target: Function): CompactionDecoratorConfig | undefined;
-
-type ContextCompactionStrategy = 'truncate-oldest' | 'summarize-oldest' | 'sliding-window' | 'priority-based';
-interface ContextWindowOptions {
-    /** Maximum tokens before compaction triggers. */
-    maxTokens?: number;
-    /** How to compact when maxTokens is exceeded. */
-    compactionStrategy?: ContextCompactionStrategy;
-    /** Always preserve the system prompt during compaction (default: true). */
-    preserveSystemPrompt?: boolean;
-    /** Number of recent messages to always keep intact (default: 10). */
-    preserveLastN?: number;
-    /** Keep all tool results even during compaction (default: true). */
-    preserveToolResults?: boolean;
-}
-declare function ContextWindow(options?: ContextWindowOptions): ClassDecorator;
-declare function getContextWindowConfig(target: Function): ContextWindowOptions | undefined;
-
-type PlatformName = 'telegram' | 'discord' | 'slack' | 'whatsapp' | 'teams' | 'email' | 'sms' | 'mattermost' | 'line' | 'matrix';
-type SessionStrategy = 'per-user' | 'per-channel' | 'per-thread';
-interface GatewayOptions {
-    /** Platform adapters this agent supports. */
-    platforms: PlatformName[];
-    /** How to resolve agentId from inbound events (default: 'per-user'). */
-    sessionStrategy?: SessionStrategy;
-    /** Auto-start typing indicator while agent processes (default: true). */
-    typing?: boolean;
-}
-declare function Gateway(options: GatewayOptions): ClassDecorator;
-declare function getGatewayConfig(target: Function): GatewayOptions | undefined;
-/**
- * Resolve a stable agentId from a platform event based on the session strategy.
- *
- * Mirrors @theokit/gateway SessionRouter.defaultStrategy() but is configurable
- * via the @Gateway decorator.
- */
-declare function resolveSessionId(strategy: SessionStrategy, platform: string, sender: {
-    id: string;
-}, channel: {
-    id: string;
-    type: 'dm' | 'group' | 'thread';
-    topicId?: string;
-}): string;
-
-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>;
-}
-declare function HumanInTheLoop(options: HumanInTheLoopOptions): MethodDecorator;
-declare function getHumanInTheLoopConfig(target: Function, propertyKey: string | symbol): HumanInTheLoopOptions | undefined;
-
-interface McpServerConfig {
-    /** Command to start the MCP server. */
-    command: string;
-    /** Arguments passed to the command. */
-    args?: string[];
-    /** Environment variables for the server process. */
-    env?: Record<string, string>;
-    /** Working directory for the server process. */
-    cwd?: string;
-}
-type McpServersMap = Record<string, McpServerConfig>;
-declare function MCP(servers: McpServersMap): ClassDecorator;
-declare function getMcpConfig(target: Function): McpServersMap | undefined;
-
-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;
-}
-declare function Memory(options?: MemoryOptions): ClassDecorator;
-declare function getMemoryConfig(target: Function): MemoryOptions | undefined;
-
-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[];
-}
-declare function ProjectContext(options?: ProjectContextOptions): ClassDecorator;
-declare function getProjectContextConfig(target: Function): ProjectContextOptions | undefined;
-
-interface SkillsOptions {
-    /** Skill names to include (resolved from .theokit/skills/<name>/SKILL.md). */
-    include: string[];
-    /** Auto-discover all skills in .theokit/skills/ (default: false). */
-    autoDiscover?: boolean;
-}
-declare function Skills(namesOrOptions: string[] | SkillsOptions): ClassDecorator;
-declare function getSkillsConfig(target: Function): SkillsOptions | undefined;
-
-/**
- * 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. */
-declare class GuardrailViolationError extends Error {
-    readonly guardName: string;
-    readonly phase: GuardrailPhase;
-    readonly reason: string;
-    constructor(guardName: string, phase: GuardrailPhase, reason: string);
-}
-/** Thrown when {@link costGuard}'s cumulative token budget is exceeded. */
-declare class CostBudgetExceededError extends Error {
-    readonly usedTokens: number;
-    readonly maxTokens: number;
-    constructor(usedTokens: number, maxTokens: number);
-}
-
-export { getSkillsConfig as $, type AgentOptions as A, type BudgetOptions as B, CostBudgetExceededError as C, type MemoryProvider as D, type MemoryScope as E, type PlatformName as F, type Guardrail as G, type HumanInTheLoopOptions as H, type IndexStrategy as I, ProjectContext as J, type ProjectContextOptions as K, type RelevanceStrategy as L, type MainLoopMeta as M, Skills as N, type SkillsOptions as O, type PolicyHandler as P, getCheckpointConfig as Q, type ReasoningEffort as R, type SessionStrategy as S, type TimeoutAction as T, getCompactionConfig as U, getContextWindowConfig as V, getGatewayConfig as W, getHumanInTheLoopConfig as X, getMcpConfig as Y, getMemoryConfig as Z, getProjectContextConfig as _, type ApprovalOptions as a, resolveSessionId as a0, type GuardrailAction as b, type GuardrailPhase as c, type GuardrailResult as d, GuardrailViolationError as e, type MainLoopOptions as f, type ToolOptions as g, type ToolboxOptions as h, Checkpoint as i, type CheckpointOptions as j, type CheckpointState as k, type CheckpointStorage as l, type CheckpointStrategy as m, Compaction as n, type CompactionDecoratorConfig as o, type ContextCompactionStrategy as p, ContextWindow as q, type ContextWindowOptions as r, Gateway as s, type GatewayOptions as t, HumanInTheLoop as u, MCP as v, type McpServerConfig as w, type McpServersMap as x, Memory as y, type MemoryOptions as z };