@xiaozhiclaw/qlogicagent-core 0.1.6 → 0.2.0

package/dist/types/agent/types.d.ts

@@ -0,0 +1,164 @@
+/**
+ * Pure Agent types with zero I/O framework dependencies.
+ *
+ * Wire-level types (ChatMessage, ToolDefinition) are canonical in
+ * contracts/. This file re-exports them and adds
+ * execution configuration supplied by the product.
+ */
+import type { HookRegistry } from "../contracts/hooks.js";
+import type { WireTokenUsage } from "../contracts/usage.js";
+import type { AccumulatedToolCall, LLMChunk, LLMRequest, LLMTransport } from "../runtime/ports/index.js";
+import type { ChatMessage as WireChatMessage, ChatMessageRole as WireChatMessageRole, ThinkingBlock as WireThinkingBlock, ToolCallMessage as WireToolCallMessage, ToolDefinition as WireToolDefinition } from "../contracts/chat.js";
+import type { ToolCallExecutionEvidence } from "../contracts/tool-execution-evidence.js";
+export type ChatMessageRole = WireChatMessageRole;
+export type ThinkingBlock = WireThinkingBlock;
+export type ToolCallMessage = WireToolCallMessage;
+export type ChatMessage = WireChatMessage;
+export type { AccumulatedToolCall, LLMChunk, LLMRequest, LLMTransport, };
+export type ToolDefinition = WireToolDefinition;
+/**
+ * Token usage unified with WireTokenUsage from contracts.
+ * No more internal/wire split: all code uses the same field names
+ * (inputTokens, outputTokens, reasoningTokens, cacheRead, cacheWrite).
+ */
+export type TokenUsage = WireTokenUsage;
+export type { TurnEvent, } from "../contracts/turn-event.js";
+/** Observable reason why the provider loop started another inference round. */
+export type ToolLoopTransition = {
+    reason: "reactive_compact_retry";
+} | {
+    reason: "next_turn";
+};
+/** Terminal exit reasons from the tool loop. */
+export type ToolLoopTerminal = {
+    reason: "completed";
+} | {
+    reason: "aborted";
+} | {
+    reason: "prompt_too_long";
+} | {
+    reason: "image_error";
+} | {
+    reason: "model_error";
+    error?: unknown;
+} | {
+    reason: "max_turns";
+} | {
+    reason: "budget_exhausted";
+} | {
+    reason: "tool_loop_limit";
+} | {
+    reason: "stop_hook_prevented";
+} | {
+    reason: "hook_stopped";
+};
+export interface TurnRequest {
+    turnId: string;
+    sessionId: string;
+    continuation?: {
+        completedRounds: number;
+        usage: TokenUsage;
+    };
+    messages: ChatMessage[];
+    /** Full registered tool surface before per-turn policy filtering. */
+    availableTools?: ToolDefinition[];
+    /** Exact tool names whose full parameter schemas are loaded only after Agent selection. */
+    deferredToolNames?: string[];
+    /**
+     * Session-owned names whose deferred schemas the Agent already selected and loaded.
+     * The loop reconciles this set against the current authoritative tool snapshot and
+     * adds newly loaded names; it never stores schema content or capability authority.
+     */
+    loadedDeferredToolNames?: Set<string>;
+    tools: ToolDefinition[];
+    /**
+     * Live tool-manifest rebuild, consulted each loop iteration (turnCount > 1).
+     * It may retract or restore tools from the turn's initial authoritative snapshot.
+     * Newly registered tools become visible on the next user turn so they cannot bypass
+     * the complete directory, schema deferral, or permission snapshot for this turn.
+     */
+    refreshTools?: () => ToolDefinition[];
+    /**
+     * Drain user guidance queued mid-turn (运行中引导). Consulted at the top of every
+     * tool-loop round; returned strings become user messages before the next LLM call.
+     */
+    drainPendingGuidance?: () => string[];
+    /**
+     * Drain bounded background-task results for this session. Consulted between
+     * rounds so completed product jobs can rejoin the parent without model polling.
+     */
+    drainPendingTaskNotifications?: () => string[];
+    /**
+     * Route media a tool returns that the MAIN model can't consume (e.g. `read` returning an image
+     * for a text-only model) to the understanding model; folds the description into the message text
+     * and drops the raw media. Forwarded to the tool loop; mutates the message in place.
+     */
+    sanitizeToolResultMedia?: (message: Record<string, unknown>) => Promise<void>;
+    systemPrompt?: string;
+    config?: TurnConfig;
+}
+export interface TurnConfig {
+    /** Model id, e.g. "deepseek-v4-flash" */
+    model?: string;
+    /** Inference credential injected by the product service. */
+    apiKey?: string;
+    /** Explicit max tool-call rounds per turn. Undefined means unbounded. */
+    maxRounds?: number;
+    /** Temperature override */
+    temperature?: number;
+    /** Context window size in tokens (for turn-loop-guard budget checks) */
+    contextWindowTokens?: number;
+    /** Max output tokens for current model */
+    maxOutputTokens?: number;
+    /** Tool choice strategy: "auto" (default), "none", "required" */
+    toolChoice?: "auto" | "none" | "required";
+    /** Max turns (tool loop iterations). 0 or undefined = use maxRounds. */
+    maxTurns?: number;
+    /** Max concurrent tool executions (0 = unlimited). */
+    maxConcurrentTools?: number;
+    /** Model requires streaming; disable transport-level non-streaming fallback. */
+    streamRequired?: boolean;
+    /** Reasoning effort for models that support it (GPT-5.x, o-series). */
+    reasoning?: {
+        effort: "auto" | "minimal" | "low" | "medium" | "high" | "xhigh";
+        includeEncryptedReasoning?: boolean;
+    };
+    /** Prompt cache bucketing key used instead of the provider-level `user` field. */
+    promptCacheKey?: string;
+    /** Prompt cache retention: "in_memory" (5-10min) or "24h". */
+    promptCacheRetention?: "in_memory" | "24h";
+    /** Service tier selected by the product model configuration. */
+    serviceTier?: "auto" | "default" | "flex" | "priority";
+    /** Max genuinely executable tool calls accepted from one model response; resets each round. */
+    maxToolCalls?: number;
+    /** Disable parallel tool calling (force sequential). */
+    parallelToolCalls?: boolean;
+    /** Text output verbosity hint: "low", "medium", "high". */
+    textVerbosity?: "low" | "medium" | "high";
+}
+export type { ToolCallExecutionEvidence };
+/**
+ * ToolInvoker: injected execution boundary owned by the SaaS product.
+ */
+export interface ToolInvoker {
+    invoke(turnId: string, name: string, args: string, signal?: AbortSignal, invocation?: {
+        callId: string;
+        sessionId: string;
+        round: number;
+    }): Promise<import("../contracts/tool-result.js").ToolResult>;
+}
+/**
+ * AgentLogger: structured logging interface.
+ * The SaaS service injects its own logging implementation.
+ */
+export interface AgentLogger {
+    info(message: string): void;
+    info(obj: Record<string, unknown>, message: string): void;
+    warn(message: string): void;
+    warn(obj: Record<string, unknown>, message: string): void;
+    error(message: string): void;
+    error(obj: Record<string, unknown>, message: string): void;
+    debug(message: string): void;
+    debug(obj: Record<string, unknown>, message: string): void;
+}
+export type { HookRegistry };

package/dist/types/contracts/chat.d.ts

@@ -0,0 +1,150 @@
+/** Internal SaaS model messages and product-supplied tool metadata. */
+/**
+ * Versioned, model-readable capability semantics supplied by a tool owner.
+ *
+ * These fields describe meaning rather than forming a closed routing taxonomy:
+ * selection remains a semantic model decision over the user's whole request.
+ */
+export interface SemanticToolCapability {
+    schemaVersion: 1;
+    summary: string;
+    scenarios?: string[];
+    prerequisites?: string[];
+    effects?: string[];
+    modalities?: string[];
+    constraints?: string[];
+}
+export type ChatMessageRole = "system" | "user" | "assistant" | "tool";
+export type ContextAnchorCategory = "objective" | "acceptance" | "decision" | "constraint" | "task" | "blocker" | "artifact";
+export interface ContextAnchor {
+    category: ContextAnchorCategory;
+    value: string;
+}
+/**
+ * Canonical Goal/thread facts supplied by the product for one Agent turn.
+ * This is context for Agent-local compaction, never a second Goal state store.
+ */
+export interface ContextEnvelope {
+    threadId: string;
+    turnId: string;
+    itemId: string;
+    anchors: ContextAnchor[];
+}
+/** Thinking block from Anthropic Messages API (DeepSeek, Claude, etc.) */
+export interface ThinkingBlock {
+    thinking: string;
+    signature: string;
+}
+/** Tool call within an assistant message. */
+export interface ToolCallMessage {
+    id: string;
+    type: "function";
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+/** Product-supplied model conversation; no local session store. */
+export interface ChatMessage {
+    role: ChatMessageRole;
+    content: string | null;
+    /** Canonical coordinates and durable facts used by Agent-local compaction receipts. */
+    threadId?: string;
+    turnId?: string;
+    itemId?: string;
+    contextAnchors?: ContextAnchor[];
+    /** Derived projection of product facts, replaceable by the context transform. */
+    contextProjection?: "facts";
+    /** For assistant messages with tool calls. */
+    tool_calls?: ToolCallMessage[];
+    /** For tool result messages. */
+    tool_call_id?: string;
+    /** For tool result messages — tool name. */
+    name?: string;
+    /** Tool-result error flag propagated so every transport can signal failure to the model. */
+    is_error?: boolean;
+    /** OpenAI-chat reasoning content (GLM/DeepSeek) carried across tool-call rounds on the assistant message. */
+    reasoning_content?: string;
+    /** Anthropic tool_reference metadata for tool_result blocks. */
+    toolReferences?: string[];
+    /** Anthropic thinking blocks — must be passed back to API in subsequent requests. */
+    thinkingBlocks?: ThinkingBlock[];
+    /** Image URLs for vision-capable models. */
+    imageUrls?: string[];
+    /** Exact MCP content blocks retained alongside the model-compatible text/media projection. */
+    contentBlocks?: import("./tool-result.js").ToolResult["contentBlocks"];
+    /** Exact standard MCP structuredContent field. */
+    structuredContent?: Record<string, unknown>;
+    /** Exact standard MCP result `_meta` field. */
+    mcpMeta?: Record<string, unknown>;
+    /** Exact standard MCP result isError field, including explicit false. */
+    mcpIsError?: boolean;
+    /** Image detail level: 'auto' | 'low' | 'high' | 'xhigh'. */
+    imageDetail?: "auto" | "low" | "high" | "xhigh";
+    /** Max image pixels budget (Volcengine image_pixel_limit). */
+    imagePixelLimit?: {
+        minPixels?: number;
+        maxPixels?: number;
+    };
+    /** Video URLs for video-understanding models. */
+    videoUrls?: string[];
+    /** Per-video fps for video understanding (0.2-5, default 1). */
+    videoFps?: number;
+    /** Audio format hint: 'mp3' | 'wav' | 'aac' | 'm4a'. */
+    audioFormat?: "mp3" | "wav" | "aac" | "m4a";
+    /** Audio URLs for audio-understanding models. */
+    audioUrls?: string[];
+    /** Pre-uploaded file IDs for document/media understanding. */
+    fileIds?: Array<{
+        id: string;
+        mimeType?: string;
+        size?: number;
+    }>;
+    /** UI-facing structured blocks persisted with transcripts; ignored by model transports. */
+    blocks?: Array<Record<string, unknown>>;
+    /**
+     * Structured attachment entries (product UI: element/browserView/file/image/…),
+     * persisted with the transcript and surfaced to the UI as chips. Opaque to the agent and ignored
+     * by model transports — the model-facing context is derived product-side and appended transiently
+     * to the LLM message, never stored here.
+     */
+    attachmentEntries?: Array<Record<string, unknown>>;
+}
+export type ToolCapabilityCategory = "business" | "skill" | "mcp" | "orchestration";
+export interface LocalizedToolText {
+    key: string;
+    fallback: string;
+    values?: Partial<Record<string, string>>;
+}
+/**
+ * Canonical identity authored by the execution owner. Third-party tools do not
+ * supply this object: the product derives it while projecting the tool.
+ */
+export interface ToolIdentity {
+    schemaVersion: 1;
+    wireName: string;
+    logicalName: string;
+    family: "business" | "skill" | "mcp" | "orchestration";
+    owner: "product";
+    serverId?: string;
+    capabilityId: string;
+}
+/** Product-supplied tool definition; execution remains product-owned. */
+export interface ToolDefinition {
+    type: "function";
+    function: {
+        name: string;
+        description: string;
+        parameters?: Record<string, unknown>;
+    };
+    /** Product-supplied tool identity and execution metadata. */
+    meta?: {
+        identity?: ToolIdentity;
+        category?: ToolCapabilityCategory;
+        displayName?: LocalizedToolText;
+        displayDescription?: LocalizedToolText;
+        semanticCapability?: SemanticToolCapability;
+        /** Tool-specific deadline supplied by the product. */
+        executionTimeoutMs?: number;
+    };
+}

package/dist/types/contracts/hooks.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Hook system types for the Agent Runtime.
+ *
+ * Internal loop hooks allow injected middleware to observe execution
+ * at well-defined lifecycle points during session, turn, and tool execution.
+ */
+/**
+ * All supported hook points in the Agent Runtime lifecycle.
+ */
+export type HookPoint = "turn.submitted" | "turn.before_inference" | "turn.after_inference" | "turn.completed" | "turn.failed" | "tool.before_invoke" | "tool.after_invoke" | "tool.invoke_failed" | "context.before_compact" | "context.after_compact" | "stop" | "stop.failure";
+export interface HookSessionContext {
+    sessionId: string;
+}
+export interface HookTurnContext extends HookSessionContext {
+    turnId: string;
+    executionId?: string;
+    rootExecutionId?: string;
+}
+export interface HookToolContext extends HookTurnContext {
+    callId: string;
+    toolName: string;
+    arguments?: Record<string, unknown>;
+}
+export interface HookStopContext extends HookSessionContext {
+    reason?: string;
+    error?: string;
+}
+export interface HookContextMap {
+    "turn.submitted": HookTurnContext & {
+        prompt?: string;
+    };
+    "turn.before_inference": HookTurnContext & {
+        model?: string;
+        messages?: unknown[];
+    };
+    "turn.after_inference": HookTurnContext & {
+        model?: string;
+        response?: unknown;
+        success?: boolean;
+        error?: string;
+    };
+    "turn.completed": HookTurnContext & {
+        outcomeId?: string;
+        prompt?: string;
+        response?: string;
+    };
+    "turn.failed": HookTurnContext & {
+        code?: string;
+        error?: string;
+    };
+    "tool.before_invoke": HookToolContext;
+    "tool.after_invoke": HookToolContext & {
+        result?: unknown;
+        ok: boolean;
+    };
+    "tool.invoke_failed": HookToolContext & {
+        error?: string;
+    };
+    "context.before_compact": HookTurnContext & {
+        tokenCount?: number;
+        messageCount?: number;
+    };
+    "context.after_compact": HookTurnContext & {
+        tokenCount?: number;
+        removedCount?: number;
+    };
+    "stop": HookStopContext;
+    "stop.failure": HookStopContext & {
+        errorDetails?: string;
+    };
+}
+/**
+ * Result of a hook handler invocation.
+ *
+ * - `continue`: proceed normally (optionally with modified context)
+ * - `abort`: stop execution (for "before" hooks only)
+ * - `skip`: skip this step but continue the overall flow
+ */
+export interface HookResult<T = unknown> {
+    action: "continue" | "abort" | "skip" | "prevent";
+    /** Modified context to pass downstream (only for "continue") */
+    context?: T;
+    /** Reason for abort/skip/prevent (for logging) */
+    reason?: string;
+}
+/**
+ * A hook handler function.
+ *
+ * @param point - The hook point being invoked
+ * @param context - Event-specific context data
+ * @returns A HookResult or void (treated as "continue")
+ */
+export type HookHandler<P extends HookPoint = HookPoint> = (point: P, context: HookContextMap[P]) => HookResult<HookContextMap[P]> | void | Promise<HookResult<HookContextMap[P]> | void>;
+/**
+ * Hook registration entry.
+ */
+export interface HookRegistration<P extends HookPoint = HookPoint> {
+    point: P;
+    handler: HookHandler<P>;
+    /** Priority (lower = earlier). Default: 100 */
+    priority?: number;
+    /** Optional label for debugging */
+    label?: string;
+    /**
+     * Critical hooks are part of the execution preflight. If they throw, the
+     * registry returns an abort result instead of treating the failure as a
+     * non-blocking observer error.
+     */
+    critical?: boolean;
+}
+/**
+ * Interface for a hook registry that manages hook handlers.
+ */
+export interface HookRegistry {
+    register<P extends HookPoint>(registration: HookRegistration<P>): () => void;
+    invoke<P extends HookPoint>(point: P, context: HookContextMap[P]): Promise<HookResult<HookContextMap[P]>>;
+}

package/dist/types/contracts/tool-execution-evidence.d.ts

@@ -0,0 +1,24 @@
+import type { ToolIdentity } from "./chat.js";
+export interface ToolCallExecutionEvidence {
+    sequence: number;
+    callId: string;
+    name: string;
+    identity: ToolIdentity;
+    status: "running" | "succeeded" | "failed" | "blocked";
+    arguments?: string;
+    error?: string;
+    failureKind?: "policy_blocked" | "semantic_quality_failed" | "timeout" | "mcp_start_failed" | "mcp_unavailable" | "tool_execution_failed";
+}
+export declare function classifyToolFailureKind(result: {
+    blocked?: boolean;
+    blockReason?: string;
+    error?: string;
+    details?: Record<string, unknown>;
+}): ToolCallExecutionEvidence["failureKind"];
+export declare function summarizeToolExecutionOutcomes(toolCalls: readonly Pick<ToolCallExecutionEvidence, "name" | "status">[], blockedToolCalls: readonly {
+    name: string;
+    reason: string;
+}[]): {
+    failedTools: string[];
+    blockedTools: string[];
+};

package/dist/types/contracts/tool-result.d.ts

@@ -0,0 +1,13 @@
+import type { AgentContentBlock } from "../embedded/content-blocks.js";
+/** Original product result, including opaque standard MCP blocks and provenance. */
+export interface ToolResult {
+    result: string;
+    error?: string;
+    toolReferences?: string[];
+    imageUrls?: string[];
+    contentBlocks?: Array<AgentContentBlock | Record<string, unknown>>;
+    structuredContent?: Record<string, unknown>;
+    mcpMeta?: Record<string, unknown>;
+    mcpIsError?: boolean;
+    details?: Record<string, unknown>;
+}

package/dist/types/contracts/turn-event.d.ts

@@ -0,0 +1,123 @@
+import type { WireTokenUsage } from "./usage.js";
+export type TurnEvent = {
+    type: "start";
+    turnId: string;
+    /**
+     * Effective caller max-rounds and per-model-round tool-call limit after provider
+     * normalization. A zero/absent round limit is unbounded; the tool-call limit resets
+     * for every model response and is not a cumulative turn execution budget.
+     */
+    effectiveMaxRounds?: number;
+    /** Maximum executable calls accepted from one model response. */
+    effectiveMaxToolCalls?: number;
+} | {
+    type: "delta";
+    turnId: string;
+    text: string;
+} | {
+    type: "tool_call";
+    turnId: string;
+    callId: string;
+    name: string;
+    displayName?: string;
+    arguments: string;
+    inputSummary?: string;
+} | {
+    type: "end";
+    turnId: string;
+    content: string;
+    /** Adapter lifecycle only; it is not a semantic task-success claim. */
+    turnStatus?: "completed" | "stopped";
+    /** Task success remains unverified unless a higher-level product workflow proves it. */
+    taskOutcome?: "unverified";
+    usage?: WireTokenUsage;
+    model?: string;
+    provider?: string;
+    /** Per-turn recovery trace (action -> count); present only when recoveries fired. */
+    recoveryTrace?: Record<string, number>;
+    contentBlocks?: import("../embedded/content-blocks.js").AgentContentBlock[];
+} | {
+    type: "error";
+    turnId: string;
+    error: string;
+    code?: string;
+    usage?: WireTokenUsage;
+} | {
+    type: "tool_result";
+    turnId: string;
+    callId: string;
+    name: string;
+    ok: boolean;
+    error?: string;
+    outputPreview?: string;
+    durationMs?: number;
+    details?: Record<string, unknown>;
+} | {
+    type: "tool_blocked";
+    turnId: string;
+    callId: string;
+    name: string;
+    reason: string;
+} | {
+    type: "recovery";
+    turnId: string;
+    action: string;
+    detail?: string;
+} | {
+    /**
+     * 作废本回合已发出但随后被丢弃的助手文本。
+     *
+     * 为什么不复用 `recovery`:recovery 同时覆盖"丢弃本轮文本"与"保留前缀并续写"两类
+     * (max_output_tokens 续写把上一轮 roundText 当作 assistant 前缀带进下一轮)。把它当作
+     * 统一作废信号会在最常见的长输出续写场景下错抹合法前缀,因此作废必须是独立事件。
+     *
+     * 语义:作废永远是**后缀截断**,截断点由 Agent 权威下发,消费端只执行不推断。
+     * 一个 turn 内只有一条线性文本流,因此不需要 roundId/segmentId 编号体系。
+     */
+    type: "text_rollback";
+    turnId: string;
+    /**
+     * 本 turn 保留的助手文本长度,单位 **UTF-16 code unit**,按全部已发出文本段的逻辑拼接计算
+     * (activity 等非文本段不计入长度,也不被截断删除)。
+     *
+     * 必须满足 `committedLength <= keepLength <= sentLength`:下界是已提交轮次的累计长度,
+     * 低于它会删掉早先轮次的合法过程性文本(那些文本不由 `turn.end.content` 覆盖,删了不会回来)。
+     * 重复下发同一 keepLength 必须幂等。
+     */
+    keepLength: number;
+    /** 供 UI 呈现"已重试/已重新生成"的轻量状态,以及诊断归因。 */
+    reason: string;
+} | {
+    type: "tool_use_summary";
+    turnId: string;
+    telemetrySource?: "agent";
+    /** Versioned terminal ledger for per-call execution evidence. */
+    ledgerSchemaVersion: 5;
+    toolCalls: import("./tool-execution-evidence.js").ToolCallExecutionEvidence[];
+    availableToolNames: string[];
+    enabledToolNames: string[];
+    toolCallNames: string[];
+    blockedToolCalls: Array<{
+        name: string;
+        reason: string;
+    }>;
+} | {
+    type: "lifecycle";
+    turnId: string;
+    kind: "context_compression";
+    status: string;
+    detail: string;
+} | {
+    type: "reasoning_delta";
+    turnId: string;
+    text: string;
+} | {
+    type: "annotations";
+    turnId: string;
+    annotations: Array<{
+        type: string;
+        url?: string;
+        title?: string;
+        [key: string]: unknown;
+    }>;
+};

package/dist/types/contracts/usage.d.ts

@@ -0,0 +1,27 @@
+/** Token accounting returned by an Agent turn. */
+export type WireUsageSource = "llmrouter.settlement" | "provider.reported" | "host.observed" | "estimated";
+export interface WireUsageRecord {
+    schemaVersion: 1;
+    source: WireUsageSource;
+    requestIds: string[];
+    tokens: {
+        inputTokens?: number;
+        outputTokens?: number;
+        totalTokens?: number;
+        reasoningTokens?: number;
+        cacheReadTokens?: number;
+        cacheWriteTokens?: number;
+    };
+    cost?: {
+        currency: string;
+        amount: string;
+    };
+}
+export interface WireTokenUsage {
+    inputTokens: number;
+    outputTokens: number;
+    reasoningTokens?: number;
+    cacheRead?: number;
+    cacheWrite?: number;
+    records?: WireUsageRecord[];
+}

package/dist/types/embedded/business-contracts.d.ts

@@ -0,0 +1,63 @@
+import type { ToolDefinition } from "./contracts.js";
+/** Versioned platform knowledge; enterprise data and permission facts stay product-owned. */
+export interface BusinessAssistantContext {
+    module: {
+        id: string;
+        version: string;
+        fields: Record<string, unknown>[];
+        operations: Array<{
+            id: string;
+            description: string;
+            prerequisites: string[];
+        }>;
+    };
+    enterprise: {
+        configurationRevision: string;
+        configuration: Record<string, unknown>;
+        dataSources: Array<{
+            id: string;
+            state: "ready" | "missing" | "unavailable";
+            reference?: string;
+        }>;
+    };
+    employee: {
+        permissionRevision: string;
+        allowedOperations: string[];
+    };
+    knowledge: {
+        revision: string;
+        skill: string;
+        examples: Array<{
+            operation: string;
+            input: string;
+            expectedOutcome: string;
+            evidenceReference: string;
+        }>;
+        exceptions: Array<{
+            code: string;
+            handling: string;
+        }>;
+    };
+}
+export interface BusinessGoal {
+    id: string;
+    description: string;
+    criteria: Array<{
+        id: string;
+        description: string;
+    }>;
+}
+export interface BusinessGoalEvidence {
+    criteria: Array<{
+        id: string;
+        status: "satisfied" | "missing" | "failed";
+        references: string[];
+    }>;
+}
+export interface BusinessGoalOutcome extends BusinessGoalEvidence {
+    status: "satisfied" | "incomplete";
+}
+/** Validate the product's versioned context without choosing or narrowing its tools. */
+export declare function validateBusinessAssistantContext(value: BusinessAssistantContext, tools: ToolDefinition[]): void;
+export declare function validateBusinessGoal(goal: BusinessGoal): void;
+export declare function verifyBusinessGoalEvidence(goal: BusinessGoal, evidence: BusinessGoalEvidence): BusinessGoalOutcome;