@xiaozhiclaw/qlogicagent-core 0.5.0 → 0.6.0

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

@@ -35,7 +35,7 @@ export interface ContextEnvelope {
     itemId: string;
     anchors: ContextAnchor[];
 }
-/** Thinking block from Anthropic Messages API (DeepSeek, Claude, etc.) */
+/** Transport-supplied signed reasoning, preserved for subsequent model rounds. */
 export interface ThinkingBlock {
     thinking: string;
     signature: string;
@@ -68,11 +68,11 @@ export interface ChatMessage {
     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. */
+    /** Transport-supplied reasoning carried across tool-call rounds. */
     reasoning_content?: string;
-    /** Anthropic tool_reference metadata for tool_result blocks. */
+    /** Transport-supplied result references. */
     toolReferences?: string[];
-    /** Anthropic thinking blocks — must be passed back to API in subsequent requests. */
+    /** Original signed reasoning, passed back unchanged through the transport. */
     thinkingBlocks?: ThinkingBlock[];
     /** Image URLs for vision-capable models. */
     imageUrls?: string[];
@@ -86,14 +86,9 @@ export interface ChatMessage {
     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). */
+    /** Sampling hint interpreted and validated by the injected transport. */
     videoFps?: number;
     /** Audio format hint: 'mp3' | 'wav' | 'aac' | 'm4a'. */
     audioFormat?: "mp3" | "wav" | "aac" | "m4a";
@@ -105,17 +100,9 @@ export interface ChatMessage {
         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";
+/** Product vocabulary; Core neither classifies tools nor restricts new categories. */
+export type ToolCapabilityCategory = string;
 export interface LocalizedToolText {
     key: string;
     fallback: string;
@@ -129,7 +116,7 @@ export interface ToolIdentity {
     schemaVersion: 1;
     wireName: string;
     logicalName: string;
-    family: "business" | "skill" | "mcp" | "orchestration";
+    family: string;
     owner: "product";
     serverId?: string;
     capabilityId: string;

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

@@ -3,11 +3,12 @@ export interface ToolCallExecutionEvidence {
     sequence: number;
     callId: string;
     name: string;
-    identity: ToolIdentity;
+    /** Product-authored identity only; absence is not inferred from a wire name. */
+    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";
+    failureKind?: "policy_blocked" | "tool_execution_failed";
 }
 export declare function classifyToolFailureKind(result: {
     blocked?: boolean;

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

@@ -0,0 +1,26 @@
+/** Execution and model controls supplied by the SaaS product. Credentials belong to its injected transport. */
+export interface TurnConfig {
+    model?: string;
+    /** Undefined means no Core-imposed round ceiling. */
+    maxRounds?: number;
+    temperature?: number;
+    contextWindowTokens?: number;
+    maxOutputTokens?: number;
+    toolChoice?: "auto" | "none" | "required";
+    /** Zero or undefined uses maxRounds. */
+    maxTurns?: number;
+    /** Zero permits unlimited concurrent tool execution. */
+    maxConcurrentTools?: number;
+    streamRequired?: boolean;
+    reasoning?: {
+        effort: "auto" | "minimal" | "low" | "medium" | "high" | "xhigh";
+        includeEncryptedReasoning?: boolean;
+    };
+    promptCacheKey?: string;
+    promptCacheRetention?: "in_memory" | "24h";
+    serviceTier?: "auto" | "default" | "flex" | "priority";
+    /** Executable calls accepted from one model response; resets each round. */
+    maxToolCalls?: number;
+    parallelToolCalls?: boolean;
+    textVerbosity?: "low" | "medium" | "high";
+}

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

@@ -21,7 +21,6 @@ export type TurnEvent = {
     name: string;
     displayName?: string;
     arguments: string;
-    inputSummary?: string;
 } | {
     type: "end";
     turnId: string;

package/dist/types/embedded/business-tool-adapter.d.ts

@@ -1,5 +1,5 @@
 import type { ToolResult } from "./contracts.js";
-import type { CloudToolInvocation, CloudToolWait } from "./cloud-agent.js";
+import { type CloudToolInvocation, type CloudToolWait } from "./cloud-agent.js";
 /** External job state is supplied by its product owner; Core owns no job queue or polling policy. */
 export type BusinessToolObservation = {
     kind: "result";

package/dist/types/embedded/context-projection.d.ts

@@ -0,0 +1,3 @@
+import type { ChatMessage, EmbeddedRuntimeOptions, ModelContextPreparation, ModelContextProjection } from "./contracts.js";
+/** Reuse the canonical fallback after product retrieval; token estimates are advisory. */
+export declare function prepareSlidingWindowContext(messages: readonly ChatMessage[], context: ModelContextPreparation, countMessageTokens?: EmbeddedRuntimeOptions["countMessageTokens"]): ModelContextProjection;

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

@@ -17,7 +17,7 @@ import type { ToolResult } from '../contracts/tool-result.js';
 export type { WireUsageRecord as UsageRecord, WireUsageSource as UsageSource } from '../contracts/usage.js';
 export type TokenUsage = import('../contracts/usage.js').WireTokenUsage;
 export type TurnEvent = import('../contracts/turn-event.js').TurnEvent;
-export type TurnConfig = Omit<import('../agent/types.js').TurnConfig, 'apiKey'>;
+export type TurnConfig = import('../contracts/turn-config.js').TurnConfig;
 /** All three must be true on a thrown transport error before core can retry a model request. */
 export interface ModelRetryAuthorization {
     retryable: boolean;

package/dist/types/embedded/index.d.ts

@@ -1,5 +1,5 @@
 export { createEmbeddedAgent } from "./embedded-agent.js";
-export { prepareSlidingWindowContext } from "./default-runtime-ports.js";
+export { prepareSlidingWindowContext } from "./context-projection.js";
 export { corePackageVersion } from "./package-version.js";
 export { AgentContentBlockValidationError, parseAgentContentBlock, } from "./content-blocks.js";
 export type { ContextAnchor, ContextEnvelope, SemanticToolCapability, ToolIdentity, UsageRecord, UsageSource, AgentLogger, ChatMessage, CreateEmbeddedAgentOptions, EmbeddedAgent, EmbeddedRuntimeOptions, ModelContextPreparation, ModelContextProjection, LLMChunk, LLMRequest, LLMTransport, ModelRetryAuthorization, ToolDefinition, ToolInvoker, ToolInvocationContext, ToolResult, TurnCheckpoint, TokenUsage, TurnConfig, TurnEvent, TurnRequest, } from "./contracts.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xiaozhiclaw/qlogicagent-core",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Shared SaaS Agent inference and durable task runtime",
   "type": "module",
   "main": "dist/index.js",

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

@@ -1,164 +0,0 @@
-/**
- * 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/embedded/default-runtime-ports.d.ts

@@ -1,6 +0,0 @@
-import type { AgentRuntimePorts } from "../runtime/ports/agent-runtime-ports.js";
-import type { EmbeddedRuntimeOptions, ModelContextPreparation, ModelContextProjection } from "./contracts.js";
-import type { ChatMessage } from "./contracts.js";
-/** Reuse the canonical fallback after product retrieval; no second compression implementation. */
-export declare function prepareSlidingWindowContext(messages: readonly ChatMessage[], context: ModelContextPreparation, countMessageTokens?: EmbeddedRuntimeOptions["countMessageTokens"]): ModelContextProjection;
-export declare function createEmbeddedRuntimePorts(options?: EmbeddedRuntimeOptions): AgentRuntimePorts;

package/dist/types/runtime/ports/agent-runtime-ports.d.ts

@@ -1,70 +0,0 @@
-import type { HookRegistry } from "../../contracts/hooks.js";
-import type { OpenAiToolCall } from "./tool-call-contracts.js";
-import type { AgentLogger, ChatMessage, TokenUsage, ToolInvoker } from "./agent-execution-contracts.js";
-export interface RuntimeCompressibleMessage {
-    role: string;
-    content?: string | unknown;
-}
-export interface RuntimeCompressionResult {
-    messages: RuntimeCompressibleMessage[];
-    droppedCount: number;
-    tokensFreed?: number;
-    strategy: string;
-}
-export interface ToolExecutionResultPort {
-    callId: string;
-    toolName: string;
-    ok: boolean;
-    error?: string;
-    blocked?: boolean;
-    blockReason?: string;
-    durationMs?: number;
-    details?: Record<string, unknown>;
-    message: unknown;
-}
-export interface StreamingToolExecutorPort {
-    addTool(toolCall: OpenAiToolCall): void;
-    getRemainingResults(): AsyncIterable<ToolExecutionResultPort>;
-}
-export interface StreamingToolExecutorPortConfig {
-    toolInvoker: ToolInvoker;
-    round?: number;
-    hooks?: HookRegistry;
-    sessionId: string;
-    turnId: string;
-    log: AgentLogger;
-    signal?: AbortSignal;
-    maxConcurrentTools?: number;
-    maxExecutionMs?: number;
-    executionTimeoutMsByTool?: ReadonlyMap<string, number>;
-}
-export interface ToolLoopRuntimePorts {
-    reviewCompletion?(messages: readonly ChatMessage[], answer: string): Promise<ChatMessage[]>;
-    saveCheckpoint?(checkpoint: {
-        turnId: string;
-        sessionId: string;
-        phase: "model_ready" | "tools_pending";
-        messages: ChatMessage[];
-        completedRounds: number;
-        usage: TokenUsage;
-    }): Promise<void>;
-    enforceToolResultBudget(messages: Array<{
-        role: string;
-        content?: string | unknown;
-        tool_call_id?: string;
-    }>): Promise<{
-        messages: unknown[];
-        newlyReplacedCount: number;
-    }>;
-    compressMessages(messages: RuntimeCompressibleMessage[], options: {
-        budget: number;
-        model: string;
-        sessionId: string;
-        turnId: string;
-        signal?: AbortSignal;
-    }): RuntimeCompressionResult | Promise<RuntimeCompressionResult>;
-    createStreamingToolExecutor(config: StreamingToolExecutorPortConfig): StreamingToolExecutorPort;
-}
-export interface AgentRuntimePorts {
-    toolLoop: ToolLoopRuntimePorts;
-}

package/dist/types/runtime/ports/index.d.ts

@@ -1,5 +0,0 @@
-export { buildToolResultMessage, type OpenAiToolCall, type ToolResultMessageInput } from "./tool-call-contracts.js";
-export type { AgentLogger, ChatMessage, TokenUsage, ToolDefinition, ToolInvoker, TurnEvent } from "./agent-execution-contracts.js";
-export type { AccumulatedToolCall, LLMChunk, LLMRequest, LLMTransport } from "./model-transport-contracts.js";
-export { accumulateToolCalls } from "./model-transport-contracts.js";
-export type { AgentRuntimePorts, RuntimeCompressibleMessage, RuntimeCompressionResult, StreamingToolExecutorPort, StreamingToolExecutorPortConfig, ToolExecutionResultPort, ToolLoopRuntimePorts } from "./agent-runtime-ports.js";

package/dist/types/runtime/ports/tool-call-contracts.d.ts

@@ -1,20 +0,0 @@
-export interface OpenAiToolCall {
-    id: string;
-    type: "function";
-    function: {
-        name: string;
-        arguments: string;
-    };
-}
-export interface ToolResultMessageInput {
-    ok: boolean;
-    payload?: unknown;
-    error?: string;
-    toolReferences?: string[];
-    imageUrls?: string[];
-    contentBlocks?: import("../../contracts/tool-result.js").ToolResult["contentBlocks"];
-    structuredContent?: Record<string, unknown>;
-    mcpMeta?: Record<string, unknown>;
-    mcpIsError?: boolean;
-}
-export declare function buildToolResultMessage(callId: string, result: ToolResultMessageInput): import("../../contracts/chat.js").ChatMessage;