@kb-labs/agent-sdk 0.6.0

package/dist/index.d.ts

@@ -0,0 +1,841 @@
+import { A as AgentMiddleware, R as RunContext, L as LLMCallResult, T as ToolExecCtx, a as LLMCtx, E as ExecutionLoop } from './loop-BeFjNV2F.js';
+export { j as AgentEventBus, i as AgentEvents, B as BaseMiddleware, C as ContextMeta, e as ControlAction, b as LLMCallPatch, f as LoopContext, g as LoopOutput, h as LoopResult, c as ToolCallInput, d as ToolOutput, U as Unsubscribe } from './loop-BeFjNV2F.js';
+import { LLMTier, TaskResult, KernelState, AgentMode as AgentMode$1, EvidenceRequirements, PromptContextSelection, RepositoryModel, ToolCapability, RepositoryTopology, RepositoryStack, RepositoryFingerprints, RepositoryWorkspaceLayout, RepositoryConventions, ToolCallRecord, IterationSnapshot, RunEvaluation, CorrectionRecord, TurnInterpretation, ToolPack, AgentConfig } from '@kb-labs/agent-contracts';
+import { LLMTool, LLMMessage } from '@kb-labs/sdk';
+
+/**
+ * Tracing interface for the Agent SDK.
+ *
+ * All tracing goes through a single TracingMiddleware [order=0] in agent-core.
+ * Business logic never calls tracer.trace() directly — zero tracing lапша.
+ *
+ * Levels:
+ *   minimal — run:start/end only
+ *   normal  — + iteration, llm:start/end, tool:start/end
+ *   full    — + full prompts, raw LLM responses, tool outputs without truncation
+ */
+
+type TraceLevel = 'minimal' | 'normal' | 'full';
+interface TraceEvent {
+    type: string;
+    timestamp: string;
+    /** = RunContext.requestId */
+    runId: string;
+    iteration?: number;
+    /** For span nesting (LLM call, tool call, sub-agent) */
+    spanId?: string;
+    parentSpanId?: string;
+    data: Record<string, unknown>;
+}
+type RunStartEvent = TraceEvent & {
+    type: 'run:start';
+    data: {
+        task: string;
+        tier: LLMTier;
+    };
+};
+type RunEndEvent = TraceEvent & {
+    type: 'run:end';
+    data: {
+        success: boolean;
+        totalTokens: number;
+        durationMs: number;
+    };
+};
+type IterStartEvent = TraceEvent & {
+    type: 'iteration:start';
+    data: {
+        iteration: number;
+        maxIterations: number;
+    };
+};
+type IterEndEvent = TraceEvent & {
+    type: 'iteration:end';
+    data: {
+        iteration: number;
+    };
+};
+type LLMStartEvent = TraceEvent & {
+    type: 'llm:start';
+    data: {
+        messageCount: number;
+        tools: string[];
+    };
+};
+type LLMEndEvent = TraceEvent & {
+    type: 'llm:end';
+    data: {
+        promptTokens: number;
+        completionTokens: number;
+        durationMs: number;
+    };
+};
+type ToolStartEvent = TraceEvent & {
+    type: 'tool:start';
+    data: {
+        toolName: string;
+        input: unknown;
+    };
+};
+type ToolEndEvent = TraceEvent & {
+    type: 'tool:end';
+    data: {
+        toolName: string;
+        success: boolean;
+        durationMs: number;
+    };
+};
+type EscalateEvent = TraceEvent & {
+    type: 'escalate';
+    data: {
+        fromTier: LLMTier;
+        toTier: LLMTier;
+        reason: string;
+    };
+};
+type AbortEvent = TraceEvent & {
+    type: 'abort';
+    data: {
+        reason: string;
+    };
+};
+type SpawnEvent = TraceEvent & {
+    type: 'spawn';
+    data: {
+        profileId: string;
+        childRunId: string;
+    };
+};
+interface AgentTracer {
+    trace(event: TraceEvent): void;
+    /** For async tracers (batching, network writes). Called at run end. */
+    flush?(): Promise<void>;
+}
+
+/**
+ * AgentMode — defines a mode of execution (execute, plan, spec, debug, etc.).
+ *
+ * A mode can:
+ *   - Add system prompt instructions
+ *   - Filter available tools (e.g. plan mode = read-only)
+ *   - Register mode-specific middlewares
+ *   - Take full control via execute() and call next() for the standard loop
+ *
+ * Modes are registered via sdk.withMode(mode) and selected at runtime
+ * based on AgentConfig.mode. Multiple modes can be registered;
+ * only the matching one is activated.
+ */
+
+interface ToolFilter {
+    /** If set, only tools matching these names are included */
+    allowNames?: string[];
+    /** If set, tools matching these names are excluded */
+    denyNames?: string[];
+    /** If true, only read-only tools (no filesystem writes, no shell) */
+    readOnly?: boolean;
+    /** Filter by tool capability tags */
+    capabilities?: string[];
+}
+type ToolFilterFn = (tool: LLMTool) => boolean;
+interface AgentMode {
+    /** Mode name — matched against AgentConfig.mode */
+    name: string;
+    /** Extra instructions appended to the system prompt in this mode */
+    getSystemPromptAdditions?(): string;
+    /** Restricts which tools are visible to the LLM in this mode */
+    getToolFilter?(): ToolFilter | ToolFilterFn;
+    /** Additional middlewares activated only in this mode */
+    getMiddlewares?(): AgentMiddleware[];
+    /**
+     * Full mode override — mode takes control of execution.
+     * Call next() to delegate to the standard LinearExecutionLoop.
+     *
+     * Use this for modes that wrap the loop (e.g. plan mode: validate → loop → validate).
+     */
+    execute?(task: string, ctx: RunContext, next: () => Promise<TaskResult>): Promise<TaskResult>;
+}
+
+/**
+ * AgentMemory — interface for what the agent remembers across iterations.
+ *
+ * Implementations live in agent-core:
+ *   - InMemoryAgentMemory    — simple in-process store
+ *   - ArchiveAgentMemory     — persistent file-backed store
+ *   - RAGAgentMemory         — vector-search backed (mind-engine)
+ */
+interface MemoryEntry {
+    content: string;
+    type: 'fact' | 'task' | 'observation' | 'error';
+    metadata?: Record<string, unknown>;
+}
+interface AgentMemory {
+    add(entry: MemoryEntry): Promise<void>;
+    /** Returns entries relevant to the query (semantic or keyword search) */
+    get(query: string): Promise<MemoryEntry[]>;
+    clear(): Promise<void>;
+}
+
+/**
+ * StopCondition — defines when the execution loop should stop.
+ *
+ * All registered conditions are evaluated after each LLM response.
+ * When multiple conditions fire simultaneously, the one with the
+ * lowest priority number wins (priority = 0 is highest).
+ *
+ * Built-in conditions in agent-core (priorities 0–9 reserved):
+ *   AbortCondition      0  — abortSignal.aborted
+ *   ReportCondition     1  — agent called the report tool
+ *   HardBudgetCondition 2  — token hard limit reached
+ *   MaxIterations       3  — iteration limit reached
+ *   LoopDetected        4  — same tools called 3x in a row
+ *   NoToolCalls         5  — agent returned no tool calls
+ *
+ * Custom conditions: use priority >= 10.
+ */
+
+interface StopConditionResult {
+    /** Human-readable reason label */
+    reason: string;
+    /** Machine-readable code (e.g. 'report_complete', 'max_iterations') */
+    reasonCode: string;
+    /** Priority of this condition (lower = more important) */
+    priority: number;
+}
+interface StopCondition {
+    name: string;
+    /**
+     * Evaluated after each LLM response.
+     * Return a StopConditionResult if this condition fires, null otherwise.
+     */
+    evaluate(ctx: RunContext, response: LLMCallResult): StopConditionResult | null;
+}
+
+/**
+ * OutputProcessor — transforms tool output before it enters the message context.
+ *
+ * Processors run in registration order after tool execution, before
+ * the output is appended to the conversation history.
+ *
+ * Built-in processors in agent-core:
+ *   TruncationProcessor    — truncates output > N chars (fixes 55k token problem)
+ *   DeduplicationProcessor — removes repeated content across iterations
+ *   CompressionProcessor   — compresses large structured outputs (JSON, logs)
+ */
+
+interface OutputProcessor {
+    name: string;
+    /**
+     * Transforms the raw tool output string.
+     * Return the transformed string — or the original if no change needed.
+     */
+    process(output: string, ctx: ToolExecCtx): string | Promise<string>;
+}
+
+/**
+ * ToolGuard — security layer around tool execution.
+ *
+ * Guards run inside ToolManager, forming a GuardPipeline:
+ *   LLM → validateInput() → [reject = error result] → ToolManager.execute()
+ *       → validateOutput() → [sanitize or reject] → OutputProcessors → context
+ *
+ * Guards are the single enforcement point for permissions.
+ * Tool implementations do NOT check permissions themselves.
+ *
+ * Built-in guards in agent-core:
+ *   PromptInjectionGuard  — detects injection attempts in tool input
+ *   SecretRedactionGuard  — scrubs api keys / tokens from output
+ *   PathSandboxGuard      — enforces allowed filesystem paths
+ *   NetworkGuard          — controls outbound requests (MCP tools)
+ */
+
+type ValidationResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+    action: 'reject';
+} | {
+    ok: false;
+    reason: string;
+    action: 'sanitize';
+    sanitized: string;
+};
+interface ToolGuard {
+    name: string;
+    /**
+     * Called BEFORE tool execution.
+     * Return { ok: false, action: 'reject' } to block the call entirely —
+     * the tool output will be an error message.
+     */
+    validateInput?(toolName: string, input: Record<string, unknown>, ctx: ToolExecCtx): ValidationResult | Promise<ValidationResult>;
+    /**
+     * Called AFTER tool execution.
+     * Return { ok: false, action: 'sanitize', sanitized } to replace the output.
+     * Return { ok: false, action: 'reject' } to replace output with an error message.
+     */
+    validateOutput?(toolName: string, output: string, ctx: ToolExecCtx): ValidationResult | Promise<ValidationResult>;
+}
+
+/**
+ * InputNormalizer — transforms tool inputs before guards and execution.
+ *
+ * Normalizers run inside ToolExecutor in registration order, BEFORE guards:
+ *   LLM → InputNormalizer.normalize() → ToolGuard.validateInput() → execute() → OutputProcessor
+ *
+ * Use cases:
+ *   - Path resolution (.bak → source, .js → .ts)
+ *   - Glob pattern expansion (bare filename → `**\/*name*`)
+ *   - Adaptive read limits per tier
+ *   - Directory field normalization
+ *   - Shell cwd defaulting
+ *
+ * Contract:
+ *   - Return a new (or same) input object — never throw.
+ *   - If normalization doesn't apply to this tool, return input unchanged.
+ *   - Normalizers are composable — each receives the output of the previous one.
+ */
+
+interface InputNormalizer {
+    name: string;
+    /**
+     * Transforms tool input before guards and execution.
+     * Return the (possibly modified) input object.
+     *
+     * @param toolName - Name of the tool being called
+     * @param input    - Current input (may have been modified by a prior normalizer)
+     * @param ctx      - Execution context (run, iteration, tier, etc.)
+     * @returns Normalized input — same reference or a new object
+     */
+    normalize(toolName: string, input: Record<string, unknown>, ctx: ToolExecCtx): Record<string, unknown> | Promise<Record<string, unknown>>;
+}
+
+/**
+ * ContextStrategy — controls how the conversation history is built and trimmed.
+ *
+ * Called before each LLM call to produce the message list that will be sent.
+ * Responsible for context window management.
+ *
+ * Built-in: LinearContextStrategy (agent-core) — keeps full history
+ * Custom examples:
+ *   SummaryContextStrategy — summarizes old messages to save tokens
+ *   RAGContextStrategy     — retrieves relevant history via vector search
+ */
+
+interface ContextStrategy {
+    /**
+     * Builds the message list to send to the LLM for this iteration.
+     * May summarize, truncate, or retrieve from memory.
+     */
+    build(history: ReadonlyArray<LLMMessage>, task: string, iteration: number): Promise<LLMMessage[]>;
+    /**
+     * Called after each iteration to append new messages to history.
+     * May apply deduplication or compression before returning the new history.
+     */
+    append(history: ReadonlyArray<LLMMessage>, newMessages: LLMMessage[]): LLMMessage[];
+}
+
+/**
+ * IBudgetManager — token and iteration budget tracking.
+ *
+ * BudgetSnapshot is the read-only view of current state.
+ * BudgetDecision is what the manager recommends doing next.
+ *
+ * The BudgetMiddleware in agent-core calls snapshot() + decide() in
+ * beforeIteration() and returns the appropriate ControlAction.
+ */
+
+interface BudgetSnapshot {
+    totalTokens: number;
+    iterationsUsed: number;
+    /** 0 = unlimited */
+    tokenBudget: number;
+    iterationBudget: number;
+    /** ~80% of token budget consumed */
+    softLimitReached: boolean;
+    /** ~95% of token budget consumed */
+    hardLimitReached: boolean;
+}
+interface BudgetDecision {
+    action: 'continue' | 'escalate' | 'stop';
+    reason?: string;
+    /** If true: stop iterating and synthesize a partial answer from history */
+    forceSynthesis?: boolean;
+    /** Target tier for escalation */
+    escalateTo?: LLMTier;
+}
+interface IBudgetManager {
+    /** Current budget state */
+    snapshot(): BudgetSnapshot;
+    /** Recommend an action based on current state */
+    decide(snapshot: BudgetSnapshot): BudgetDecision;
+    /** Record tokens consumed in one LLM call */
+    record(promptTokens: number, completionTokens: number): void;
+    /** Total tokens consumed so far */
+    readonly totalTokens: number;
+}
+
+/**
+ * AgentProfile — defines the role and capabilities of an agent.
+ *
+ * Three roles:
+ *   orchestrator — full rights, all modes (plan, spec), human-in-loop support
+ *   sub-agent    — same rights as orchestrator but scoped context, limited iterations
+ *   atomic       — minimal rights: one tool pack, no spawn, isolated execution
+ *
+ * Profiles are registered via sdk.withProfile() and applied at createRunner() time.
+ */
+
+type AgentRole = 'orchestrator' | 'sub-agent' | 'atomic';
+interface AgentProfile {
+    id: string;
+    role: AgentRole;
+    /** Base system prompt for this profile (appended to global system prompt) */
+    systemPrompt?: string;
+    /** Additional instruction bullets (appended after systemPrompt) */
+    instructions?: string[];
+    budget?: {
+        maxIterations?: number;
+        tier?: LLMTier;
+        enableEscalation?: boolean;
+        /** 0 = unlimited */
+        tokenBudget?: number;
+    };
+    /**
+     * Spawn configuration — only applicable for orchestrator and sub-agent roles.
+     * Atomic agents cannot spawn sub-agents.
+     */
+    spawn?: {
+        /** Maximum sub-agent depth (default: 3). Prevents infinite recursion. */
+        maxDepth?: number;
+        /** If set, only profiles in this list can be spawned by this agent */
+        allowedProfiles?: string[];
+    };
+}
+
+interface ResponseRequirements {
+    requirements: EvidenceRequirements;
+    rationale: string;
+}
+interface ToolPolicy {
+    access: 'restricted' | 'read-only' | 'controlled' | 'balanced' | 'aggressive';
+    allowedToolNames?: string[];
+    allowedCapabilities?: ToolCapability[];
+    blockedCapabilities?: ToolCapability[];
+}
+interface DirectAnswerResolution {
+    answer: string;
+    confidence: number;
+    filesRead?: string[];
+}
+interface ModePolicy {
+    id: string;
+    mode: AgentMode$1 | 'assistant' | 'autonomous';
+    describe(): {
+        responseStyle: 'dialogue-first' | 'execution-first' | 'planning-first';
+        toolUse: 'controlled' | 'balanced' | 'aggressive';
+    };
+}
+interface RepositoryDiagnosticsProvider {
+    id: string;
+    describe(input: {
+        workingDir: string;
+        mode: AgentMode$1 | 'assistant' | 'autonomous';
+        profile: RuntimeProfile | null;
+        kernel: KernelState | null;
+    }): Promise<RepositoryModel | null> | RepositoryModel | null;
+}
+interface RepositoryProbeObservation {
+    topology?: RepositoryTopology;
+    stack?: Partial<RepositoryStack>;
+    fingerprints?: Partial<RepositoryFingerprints>;
+    workspace?: Partial<RepositoryWorkspaceLayout>;
+    conventions?: Partial<RepositoryConventions>;
+    riskSignals?: string[];
+    sources?: string[];
+}
+interface RepositoryProbe {
+    id: string;
+    probe(input: {
+        workingDir: string;
+        mode: AgentMode$1 | 'assistant' | 'autonomous';
+        profile: RuntimeProfile | null;
+        kernel: KernelState | null;
+        fileNames: string[];
+    }): Promise<RepositoryProbeObservation | null> | RepositoryProbeObservation | null;
+}
+interface ToolCapabilityResolver {
+    id: string;
+    resolve(input: {
+        workingDir: string;
+        mode: AgentMode$1 | 'assistant' | 'autonomous';
+        profile: RuntimeProfile | null;
+        repositoryModel: RepositoryModel | null;
+        kernel: KernelState | null;
+    }): Promise<ToolCapability[] | null> | ToolCapability[] | null;
+}
+interface MemoryCapability {
+    id: string;
+    apply(state: KernelState): KernelState | Promise<KernelState>;
+}
+interface PromptProjector {
+    id: string;
+    project(input: {
+        state: KernelState;
+        messages: LLMMessage[];
+        repositoryModel?: RepositoryModel | null;
+        toolCapabilities?: ToolCapability[];
+    }): string | Promise<string>;
+}
+interface PromptContextSelector {
+    id: string;
+    select(input: {
+        state: KernelState;
+        messages: LLMMessage[];
+        responseRequirements?: ResponseRequirements;
+    }): PromptContextSelection | Promise<PromptContextSelection>;
+}
+interface ResponseRequirementsSelector {
+    id: string;
+    select(input: {
+        state: KernelState | null;
+        messages: LLMMessage[];
+        task: string;
+    }): ResponseRequirements | Promise<ResponseRequirements>;
+}
+interface SessionRecallResolver {
+    id: string;
+    resolve(input: {
+        state: KernelState;
+        messages: LLMMessage[];
+        task: string;
+        toolRecords: ToolCallRecord[];
+        responseRequirements?: ResponseRequirements;
+    }): Promise<DirectAnswerResolution | null> | DirectAnswerResolution | null;
+}
+interface OutputValidationResult {
+    verdict: 'allow' | 'warn' | 'block';
+    rationale: string;
+}
+interface OutputValidator {
+    id: string;
+    validate(input: {
+        state: KernelState;
+        answer: string;
+        mode: AgentMode$1 | 'assistant' | 'autonomous';
+        metadata?: Record<string, unknown>;
+    }): Promise<OutputValidationResult | null> | OutputValidationResult | null;
+}
+interface ArtifactWriter {
+    id: string;
+    write(input: {
+        state: KernelState;
+        sessionId: string;
+        summary: string;
+        runId?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<void> | void;
+}
+interface ResultMapperResult {
+    taskResult?: Partial<TaskResult>;
+    runtimeMetadata?: Record<string, unknown>;
+    summary?: string;
+}
+interface ResultMapper {
+    id: string;
+    map(input: {
+        state: KernelState | null;
+        answer: string;
+        mode: AgentMode$1 | 'assistant' | 'autonomous';
+        task: string;
+        sessionId?: string;
+        workingDir: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<ResultMapperResult | null> | ResultMapperResult | null;
+}
+interface CompletionPolicy {
+    requireReportTool?: boolean;
+    requireValidatorsToPass?: boolean;
+}
+interface RuntimeProfile {
+    id: string;
+    mode: AgentMode$1 | 'assistant' | 'autonomous';
+    description?: string;
+    toolPolicy?: ToolPolicy;
+    repositoryDiagnosticsProviders?: RepositoryDiagnosticsProvider[];
+    repositoryProbes?: RepositoryProbe[];
+    toolCapabilityResolvers?: ToolCapabilityResolver[];
+    promptContextSelectors?: PromptContextSelector[];
+    responseRequirementsSelectors?: ResponseRequirementsSelector[];
+    promptProjectors?: PromptProjector[];
+    sessionRecallResolvers?: SessionRecallResolver[];
+    runEvaluators?: RunEvaluator[];
+    resultMappers?: ResultMapper[];
+    outputValidators?: OutputValidator[];
+    artifactWriters?: ArtifactWriter[];
+    completionPolicy?: CompletionPolicy;
+}
+interface RuntimeObserver {
+    id: string;
+    onKernelUpdated?(state: KernelState): void | Promise<void>;
+    onToolCall?(record: ToolCallRecord): void | Promise<void>;
+    onCorrection?(record: CorrectionRecord): void | Promise<void>;
+}
+interface TurnInterpreter {
+    id: string;
+    supports(mode: AgentMode$1 | 'assistant' | 'autonomous'): boolean;
+    interpret(input: {
+        sessionId?: string;
+        mode: AgentMode$1 | 'assistant' | 'autonomous';
+        message: string;
+        kernel: KernelState | null;
+    }): Promise<TurnInterpretation | null> | TurnInterpretation | null;
+}
+interface RunEvaluator {
+    id: string;
+    evaluate(input: {
+        run: RunContext;
+        snapshot: IterationSnapshot;
+    }): Promise<RunEvaluation | null> | RunEvaluation | null;
+}
+
+/**
+ * IAgentSpawner — contract for spawning sub-agents.
+ *
+ * The spawner is registered in RunContext.meta by AgentRunner at startup:
+ *   ctx.meta.get<IAgentSpawner>('core', 'spawner')
+ *
+ * This makes it accessible to any middleware or tool without direct coupling
+ * to AgentRunner.
+ *
+ * Implementation lives in agent-core (AgentSpawner).
+ * Enforcement:
+ *   - canSpawn() checks depth, allowed profiles, and remaining budget
+ *   - budgetPartition is deducted from parent's remaining token budget
+ *   - parent's AbortSignal is wired to all child AbortControllers
+ */
+
+interface SpawnOptions {
+    /** Profile ID to use — must be registered in the parent SDK */
+    profileId: string;
+    /** Task string for the sub-agent */
+    task: string;
+    /** Parent context — used to inherit requestId, abortSignal, deadlineMs */
+    parentContext: RunContext;
+    /**
+     * Fraction of parent's remaining token budget to allocate (0.0–1.0).
+     * Default: 0.3 (30%).
+     */
+    budgetPartition?: number;
+    /** Additional tool packs available only to this sub-agent */
+    additionalPacks?: ToolPack[];
+}
+interface SpawnResult {
+    result: TaskResult;
+    /** Actual tokens consumed — parent should deduct this from its budget */
+    tokensConsumed: number;
+}
+interface IAgentSpawner {
+    /** Spawn a single sub-agent and await its result */
+    spawn(options: SpawnOptions): Promise<SpawnResult>;
+    /**
+     * Spawn multiple sub-agents in parallel.
+     * The budgetPartition is divided equally among all spawned agents.
+     */
+    spawnParallel(options: SpawnOptions[]): Promise<SpawnResult[]>;
+    /**
+     * Check whether spawning is allowed in the current context.
+     * Returns false if depth limit is reached, profile is not allowed,
+     * or remaining budget is insufficient.
+     */
+    canSpawn(profileId: string, ctx: RunContext): boolean;
+}
+
+/**
+ * AgentErrorHandler — defines what to do when a tool or LLM call fails.
+ *
+ * Registered via sdk.withErrorHandler(handler).
+ *
+ * Default behaviour in agent-core:
+ *   tool error  → retry once → skip (return empty output, continue)
+ *   LLM error   → retry with exponential backoff (3x) → stop
+ *
+ * The `attempt` parameter is 1-based — first failure = attempt 1.
+ */
+
+type ToolErrorAction = {
+    action: 'retry';
+    delayMs?: number;
+} | {
+    action: 'skip';
+} | {
+    action: 'stop';
+    reason: string;
+};
+type LLMErrorAction = {
+    action: 'retry';
+    delayMs?: number;
+} | {
+    action: 'stop';
+    reason: string;
+};
+interface AgentErrorHandler {
+    /**
+     * Called when a tool execution throws.
+     * @param attempt 1-based attempt count
+     */
+    onToolError(error: unknown, ctx: ToolExecCtx, attempt: number): ToolErrorAction;
+    /**
+     * Called when an LLM API call throws (rate limit, timeout, network error, etc.).
+     * @param attempt 1-based attempt count
+     */
+    onLLMError(error: unknown, ctx: LLMCtx, attempt: number): LLMErrorAction;
+}
+
+/**
+ * AgentSDK — composable builder + IAgentSDK interface for mocking in tests.
+ *
+ * Usage:
+ *   import { AgentSDK } from '@kb-labs/agent-sdk';
+ *   import { CoreToolPack, PromptInjectionGuard } from '@kb-labs/agent-core';
+ *
+ *   const agent = new AgentSDK()
+ *     .withProfile({ id: 'default', role: 'orchestrator' })
+ *     .register(new CoreToolPack())
+ *     .addGuard(new PromptInjectionGuard())
+ *     .use(new AuditMiddleware());
+ *
+ * extend() returns a deep clone — changes never affect the original:
+ *   const subAgent = agent.extend().withProfile(atomicProfile);
+ *
+ * createRunner() is implemented by agent-core (injected via AgentSDK.setRunnerFactory()).
+ * agent-sdk itself has no runtime dependency on agent-core.
+ */
+
+interface IAgentRunner {
+    readonly agentId: string;
+    execute(task: string): Promise<TaskResult>;
+    requestStop(): void;
+    injectUserContext(message: string): void;
+}
+type RunnerFactory = (config: AgentConfig, sdk: AgentSDK) => IAgentRunner;
+interface IAgentSDK {
+    use(middleware: AgentMiddleware): IAgentSDK;
+    register(pack: ToolPack): IAgentSDK;
+    withTracer(tracer: AgentTracer, level?: TraceLevel): IAgentSDK;
+    withMode(mode: AgentMode): IAgentSDK;
+    withMemory(memory: AgentMemory): IAgentSDK;
+    withProfile(profile: AgentProfile): IAgentSDK;
+    withLoop(loop: ExecutionLoop): IAgentSDK;
+    withContextStrategy(strategy: ContextStrategy): IAgentSDK;
+    withErrorHandler(handler: AgentErrorHandler): IAgentSDK;
+    addStopCondition(condition: StopCondition): IAgentSDK;
+    addOutputProcessor(processor: OutputProcessor): IAgentSDK;
+    addGuard(guard: ToolGuard): IAgentSDK;
+    addInputNormalizer(normalizer: InputNormalizer): IAgentSDK;
+    registerModePolicy(policy: ModePolicy): IAgentSDK;
+    registerMemoryCapability(capability: MemoryCapability): IAgentSDK;
+    registerPromptContextSelector(selector: PromptContextSelector): IAgentSDK;
+    registerResponseRequirementsSelector(selector: ResponseRequirementsSelector): IAgentSDK;
+    registerSessionRecallResolver(resolver: SessionRecallResolver): IAgentSDK;
+    registerRepositoryDiagnosticsProvider(provider: RepositoryDiagnosticsProvider): IAgentSDK;
+    registerRepositoryProbe(probe: RepositoryProbe): IAgentSDK;
+    registerToolCapabilityResolver(resolver: ToolCapabilityResolver): IAgentSDK;
+    registerRuntimeProfile(profile: RuntimeProfile): IAgentSDK;
+    registerPromptProjector(projector: PromptProjector): IAgentSDK;
+    registerRunEvaluator(evaluator: RunEvaluator): IAgentSDK;
+    registerObserver(observer: RuntimeObserver): IAgentSDK;
+    registerTurnInterpreter(interpreter: TurnInterpreter): IAgentSDK;
+    extend(): IAgentSDK;
+    createRunner(config: AgentConfig): IAgentRunner;
+}
+interface SdkState {
+    middlewares: AgentMiddleware[];
+    packs: ToolPack[];
+    tracer: AgentTracer | null;
+    traceLevel: TraceLevel;
+    modes: AgentMode[];
+    memory: AgentMemory | null;
+    profile: AgentProfile | null;
+    loop: ExecutionLoop | null;
+    contextStrategy: ContextStrategy | null;
+    errorHandler: AgentErrorHandler | null;
+    stopConditions: StopCondition[];
+    outputProcessors: OutputProcessor[];
+    guards: ToolGuard[];
+    inputNormalizers: InputNormalizer[];
+    modePolicies: ModePolicy[];
+    memoryCapabilities: MemoryCapability[];
+    promptContextSelectors: PromptContextSelector[];
+    responseRequirementsSelectors: ResponseRequirementsSelector[];
+    sessionRecallResolvers: SessionRecallResolver[];
+    repositoryDiagnosticsProviders: RepositoryDiagnosticsProvider[];
+    repositoryProbes: RepositoryProbe[];
+    toolCapabilityResolvers: ToolCapabilityResolver[];
+    runtimeProfiles: RuntimeProfile[];
+    promptProjectors: PromptProjector[];
+    runEvaluators: RunEvaluator[];
+    observers: RuntimeObserver[];
+    turnInterpreters: TurnInterpreter[];
+}
+declare class AgentSDK implements IAgentSDK {
+    private readonly _state;
+    constructor(state?: SdkState);
+    static setRunnerFactory(factory: RunnerFactory): void;
+    use(middleware: AgentMiddleware): this;
+    register(pack: ToolPack): this;
+    withTracer(tracer: AgentTracer, level?: TraceLevel): this;
+    withMode(mode: AgentMode): this;
+    withMemory(memory: AgentMemory): this;
+    withProfile(profile: AgentProfile): this;
+    withLoop(loop: ExecutionLoop): this;
+    withContextStrategy(strategy: ContextStrategy): this;
+    withErrorHandler(handler: AgentErrorHandler): this;
+    addStopCondition(condition: StopCondition): this;
+    addOutputProcessor(processor: OutputProcessor): this;
+    addGuard(guard: ToolGuard): this;
+    addInputNormalizer(normalizer: InputNormalizer): this;
+    registerModePolicy(policy: ModePolicy): this;
+    registerMemoryCapability(capability: MemoryCapability): this;
+    registerPromptContextSelector(selector: PromptContextSelector): this;
+    registerResponseRequirementsSelector(selector: ResponseRequirementsSelector): this;
+    registerSessionRecallResolver(resolver: SessionRecallResolver): this;
+    registerRepositoryDiagnosticsProvider(provider: RepositoryDiagnosticsProvider): this;
+    registerRepositoryProbe(probe: RepositoryProbe): this;
+    registerToolCapabilityResolver(resolver: ToolCapabilityResolver): this;
+    registerRuntimeProfile(profile: RuntimeProfile): this;
+    registerPromptProjector(projector: PromptProjector): this;
+    registerRunEvaluator(evaluator: RunEvaluator): this;
+    registerObserver(observer: RuntimeObserver): this;
+    registerTurnInterpreter(interpreter: TurnInterpreter): this;
+    extend(): AgentSDK;
+    get middlewares(): ReadonlyArray<AgentMiddleware>;
+    get packs(): ReadonlyArray<ToolPack>;
+    get tracer(): AgentTracer | null;
+    get traceLevel(): TraceLevel;
+    get modes(): ReadonlyArray<AgentMode>;
+    get memory(): AgentMemory | null;
+    get profile(): AgentProfile | null;
+    get loop(): ExecutionLoop | null;
+    get contextStrategy(): ContextStrategy | null;
+    get errorHandler(): AgentErrorHandler | null;
+    get stopConditions(): ReadonlyArray<StopCondition>;
+    get outputProcessors(): ReadonlyArray<OutputProcessor>;
+    get guards(): ReadonlyArray<ToolGuard>;
+    get inputNormalizers(): ReadonlyArray<InputNormalizer>;
+    get modePolicies(): ReadonlyArray<ModePolicy>;
+    get memoryCapabilities(): ReadonlyArray<MemoryCapability>;
+    get promptContextSelectors(): ReadonlyArray<PromptContextSelector>;
+    get responseRequirementsSelectors(): ReadonlyArray<ResponseRequirementsSelector>;
+    get sessionRecallResolvers(): ReadonlyArray<SessionRecallResolver>;
+    get repositoryDiagnosticsProviders(): ReadonlyArray<RepositoryDiagnosticsProvider>;
+    get repositoryProbes(): ReadonlyArray<RepositoryProbe>;
+    get toolCapabilityResolvers(): ReadonlyArray<ToolCapabilityResolver>;
+    get runtimeProfiles(): ReadonlyArray<RuntimeProfile>;
+    get promptProjectors(): ReadonlyArray<PromptProjector>;
+    get runEvaluators(): ReadonlyArray<RunEvaluator>;
+    get observers(): ReadonlyArray<RuntimeObserver>;
+    get turnInterpreters(): ReadonlyArray<TurnInterpreter>;
+    createRunner(config: AgentConfig): IAgentRunner;
+}
+
+export { type AbortEvent, type AgentErrorHandler, type AgentMemory, AgentMiddleware, type AgentMode, type AgentProfile, type AgentRole, AgentSDK, type AgentTracer, type ArtifactWriter, type BudgetDecision, type BudgetSnapshot, type CompletionPolicy, type ContextStrategy, type DirectAnswerResolution, type EscalateEvent, ExecutionLoop, type IAgentRunner, type IAgentSDK, type IAgentSpawner, type IBudgetManager, type InputNormalizer, type IterEndEvent, type IterStartEvent, LLMCallResult, LLMCtx, type LLMEndEvent, type LLMErrorAction, type LLMStartEvent, type MemoryCapability, type MemoryEntry, type ModePolicy, type OutputProcessor, type OutputValidationResult, type OutputValidator, type PromptContextSelector, type PromptProjector, type RepositoryDiagnosticsProvider, type RepositoryProbe, type RepositoryProbeObservation, type ResponseRequirements, type ResponseRequirementsSelector, type ResultMapper, type ResultMapperResult, RunContext, type RunEndEvent, type RunEvaluator, type RunStartEvent, type RunnerFactory, type RuntimeObserver, type RuntimeProfile, type SessionRecallResolver, type SpawnEvent, type SpawnOptions, type SpawnResult, type StopCondition, type StopConditionResult, type ToolCapabilityResolver, type ToolEndEvent, type ToolErrorAction, ToolExecCtx, type ToolFilter, type ToolFilterFn, type ToolGuard, type ToolPolicy, type ToolStartEvent, type TraceEvent, type TraceLevel, type TurnInterpreter, type ValidationResult };