@xiaozhiclaw/qlogicagent-core 0.4.1 → 0.5.0

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

@@ -28,6 +28,8 @@ export type TurnEvent = {
     content: string;
     /** Adapter lifecycle only; it is not a semantic task-success claim. */
     turnStatus?: "completed" | "stopped";
+    /** Product-requested pause at a durable model-ready boundary. */
+    stopReason?: "paused";
     /** Task success remains unverified unless a higher-level product workflow proves it. */
     taskOutcome?: "unverified";
     usage?: WireTokenUsage;

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

@@ -1,5 +1,5 @@
-/** Token accounting returned by an Agent turn. */
-export type WireUsageSource = "llmrouter.settlement" | "provider.reported" | "host.observed" | "estimated";
+/** Opaque provenance supplied by the product transport, not a Core billing classification. */
+export type WireUsageSource = string;
 export interface WireUsageRecord {
     schemaVersion: 1;
     source: WireUsageSource;

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

@@ -1,43 +1,10 @@
 import type { ToolDefinition } from "./contracts.js";
-/** Versioned platform knowledge; enterprise data and permission facts stay product-owned. */
+/** Product-owned context. Core does not require any particular domain, resources or roles. */
 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;
-        }>;
-    };
+    /** Explicit trusted instructions from the product; no other context field becomes a system instruction. */
+    instructions?: string;
+    /** JSON-serializable facts, revisions and references whose names and meanings belong to the product. */
+    [section: string]: unknown;
 }
 export interface BusinessGoal {
     id: string;
@@ -64,7 +31,7 @@ export interface BusinessGoalEvidence {
 export interface BusinessGoalOutcome extends BusinessGoalEvidence {
     status: "satisfied" | "incomplete";
 }
-/** Validate the product's versioned context without choosing or narrowing its tools. */
+/** Check only the transport shape; product validation and authorization stay outside Core. */
 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;

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

@@ -0,0 +1,37 @@
+import type { ToolResult } from "./contracts.js";
+import type { CloudToolInvocation, 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";
+    result: ToolResult;
+} | {
+    kind: "pending";
+    reference: string;
+    progress?: Record<string, unknown>;
+    resources?: string[];
+} | {
+    kind: "unknown";
+    reference: string;
+    detail?: string;
+};
+export interface BusinessToolPort {
+    /** Persist/deduplicate by the complete original invocation before acknowledging a job.
+     * Forward invocation.taskBudget unchanged to every paid generation endpoint.
+     */
+    submit(invocation: Readonly<CloudToolInvocation>, signal?: AbortSignal): Promise<BusinessToolObservation>;
+    /** Query the original invocation only. Absence/unknown is never permission to submit again. */
+    query(invocation: Readonly<CloudToolInvocation>, signal?: AbortSignal): Promise<BusinessToolObservation>;
+    /** Product cancellation is a request, not proof that a job or its charge did not execute. */
+    cancel?(invocation: Readonly<CloudToolInvocation>, signal?: AbortSignal): Promise<BusinessToolObservation>;
+}
+export interface BusinessToolAdapter {
+    invoke(invocation: CloudToolInvocation, signal?: AbortSignal): Promise<ToolResult | CloudToolWait>;
+    /** Resume an external wait or reconcile an interrupted submission by querying its original operation. */
+    resolve(invocation: CloudToolInvocation, signal?: AbortSignal): Promise<ToolResult | CloudToolWait>;
+    cancel(invocation: CloudToolInvocation, signal?: AbortSignal): Promise<ToolResult | CloudToolWait>;
+}
+export declare function createBusinessToolAdapter(options: {
+    port: BusinessToolPort;
+    /** Durable product progress/resource projection. Awaited before acknowledging any observation. */
+    observe?(invocation: Readonly<CloudToolInvocation>, observation: Readonly<BusinessToolObservation>): Promise<void>;
+}): BusinessToolAdapter;

package/dist/types/embedded/cloud-agent.d.ts

@@ -5,7 +5,9 @@ import { type AgentContentBlock } from "./content-blocks.js";
 import type { CreateEmbeddedAgentOptions, ToolResult, TurnCheckpoint, TurnEvent, TurnRequest, LLMRequest } from "./contracts.js";
 export interface CloudExecutionContext {
     applicationId: string;
+    /** Opaque product data namespace, such as a personal workspace; it need not represent an organization. */
     tenantId: string;
+    /** Product-defined user or service identity; Core does not require an employee role. */
     actorId: string;
     scopeId: string;
     definitionVersion: string;
@@ -58,6 +60,8 @@ export type CloudTurnEvent = TurnEvent | {
 export interface CloudToolReceipt {
     invocation: CloudToolInvocation;
     result: ToolResult;
+    /** Original wait identity, retained in the same receipt for lost-acknowledgement recovery. */
+    wait?: CloudToolWait["wait"];
 }
 /** Only the product may supply reconciled receipts; this function never executes tools. */
 export declare function completeCloudToolCheckpoint(input: CloudCheckpoint, receipts: CloudToolReceipt[]): CloudCheckpoint;
@@ -77,6 +81,9 @@ export interface CloudAgentOptions extends Omit<CreateEmbeddedAgentOptions, "too
     checkpoints?: {
         save(checkpoint: CloudCheckpoint): Promise<void>;
     };
+    /** Product-owned pause intent. Checked after saving a safe model-ready boundary;
+     * an in-flight inference or atomic tool operation is never interrupted as a pause. */
+    shouldPause?(context: Readonly<CloudExecutionContext>, checkpoint: Readonly<CloudCheckpoint>): Promise<boolean>;
     /** Awaited before a successful result is acknowledged or another model step starts. */
     onToolResult?(invocation: CloudToolInvocation, result: ToolResult): Promise<void>;
     onWait?(invocation: CloudToolInvocation, wait: CloudToolWait["wait"]): Promise<void>;

package/dist/types/embedded/cloud-task.d.ts

@@ -82,8 +82,8 @@ export interface CloudTaskRuntimeOptions {
     resolveGoal?(task: CloudTaskSnapshot): Promise<BusinessGoal | undefined>;
     /** Feed independently checked evidence back through the same loop; no separate correction runner. */
     goalFeedback?(task: CloudTaskSnapshot, outcome: BusinessGoalOutcome): Promise<ChatMessage[]>;
-    authorize(context: CloudExecutionContext, action: "create" | "read" | "execute" | "cancel" | "complete_wait" | "recover" | "append_input"): Promise<void>;
-    /** Validate actual employee approval/input or query the original external job; never trust browser results. */
+    authorize(context: CloudExecutionContext, action: "create" | "read" | "execute" | "cancel" | "complete_wait" | "recover" | "append_input" | "resume"): Promise<void>;
+    /** Validate product-authorized approval/input or query the original external job; never trust browser results. */
     authorizeCompletion(task: CloudTaskSnapshot, waitId: string, result: ToolResult): Promise<void>;
     /** Required for interrupted model calls or unresolved effects. The product proves billing/retry safety. */
     authorizeRecovery?(task: CloudTaskSnapshot, receipts: CloudToolReceipt[]): Promise<ModelRecoveryProof[] | void>;
@@ -101,6 +101,8 @@ export interface CloudTaskRuntime {
     /** Called by the existing product worker, independently from browser subscriptions. */
     execute(context: CloudExecutionContext, id: string, workerSignal?: AbortSignal): Promise<void>;
     cancel(context: CloudExecutionContext, id: string): Promise<CloudTaskSnapshot>;
+    /** Resume a durable pause without a new user input, identity or budget. */
+    resume(context: CloudExecutionContext, id: string): Promise<CloudTaskSnapshot>;
     /** Continue a resolved task on explicit user input, preserving its identity and original budgets. */
     appendInput(context: CloudExecutionContext, id: string, input: {
         id: string;

package/dist/types/embedded/content-blocks.d.ts

@@ -1,111 +1,13 @@
-/** MCP wire blocks are opaque product evidence; only presentation blocks go to the UI parser. */
-export declare function parsePresentationBlocks(blocks: Array<AgentContentBlock | Record<string, unknown>>): AgentContentBlock[];
-export type AgentEngineeringFormat = "dxf" | "dwg" | "step" | "stp" | "glb" | "gltf";
-export type AgentEngineeringPreviewMode = "direct" | "browser_conversion" | "external_conversion_required";
-export type AgentEngineeringParseStatus = "parsed" | "partial" | "conversion_required";
-export interface AgentEngineeringMetadata {
-    format: AgentEngineeringFormat;
-    previewMode: AgentEngineeringPreviewMode;
-    parseStatus: AgentEngineeringParseStatus;
-    summary: string;
-}
-export type AgentAttachmentKind = "image" | "spreadsheet" | "presentation" | "document" | "engineering_2d" | "engineering_3d" | "file";
-export interface AgentAttachment {
-    id: string;
-    kind: AgentAttachmentKind;
-    fileName: string;
-    mimeType: string;
-    byteSize: number;
-    downloadUrl: string;
-    expiresAt: string;
-    note: string;
-    engineering: AgentEngineeringMetadata | null;
-}
-export interface AgentInputAttachmentEvidence {
-    id: string;
-    kind: "engineering_2d" | "engineering_3d" | "file";
-    fileName: string;
-    mimeType: string;
-    byteSize: number;
-    engineering: AgentEngineeringMetadata | null;
-    extractedText: string;
-}
-export interface AgentAttachmentContentBlock {
-    id: string;
-    type: "attachment";
-    attachment: AgentAttachment;
-}
-export interface AgentChoiceContentBlock {
+/** Product-defined presentation payload. Core only owns its transport identity. */
+export interface AgentContentBlock {
     id: string;
-    type: "choice";
-    prompt: string;
-    selection: "single" | "multiple";
-    options: Array<{
-        id: string;
-        label: string;
-        description: string;
-    }>;
-    required: boolean;
-    minSelections: number;
-    maxSelections: number;
-    submitLabel: string;
+    type: string;
+    [key: string]: unknown;
 }
-export type AgentTableCell = string | number | boolean | null;
-export interface AgentTableContentBlock {
-    id: string;
-    type: "table";
-    title: string;
-    caption: string;
-    columns: Array<{
-        key: string;
-        label: string;
-        align: "start" | "center" | "end";
-    }>;
-    rows: Array<Record<string, AgentTableCell>>;
-}
-export interface AgentDiagramContentBlock {
-    id: string;
-    type: "diagram";
-    title: string;
-    direction: "horizontal" | "vertical";
-    nodes: Array<{
-        id: string;
-        label: string;
-        description: string;
-        tone: "neutral" | "info" | "success" | "warning" | "danger";
-    }>;
-    edges: Array<{
-        from: string;
-        to: string;
-        label: string;
-    }>;
-}
-export type AgentContentBlock = AgentAttachmentContentBlock | AgentChoiceContentBlock | AgentTableContentBlock | AgentDiagramContentBlock;
-export interface StandardPresentationToolDefinition {
-    type: "function";
-    function: {
-        name: StandardPresentationToolName;
-        description: string;
-        parameters: Record<string, unknown>;
-    };
-}
-export declare const standardPresentationToolNames: readonly ["response_present_choice", "response_present_table", "response_present_diagram"];
-export type StandardPresentationToolName = typeof standardPresentationToolNames[number];
-export declare const standardPresentationToolDefinitions: StandardPresentationToolDefinition[];
 export declare class AgentContentBlockValidationError extends Error {
     constructor(message: string);
 }
+/** Check the envelope without interpreting product types, fields or UI constraints. */
 export declare function parseAgentContentBlock(value: unknown): AgentContentBlock;
-export declare function createStandardPresentationToolResult(toolName: string, rawArguments: string, createId?: () => string): {
-    result: string;
-    contentBlocks: AgentContentBlock[];
-};
-export interface EngineeringFileAnalysis {
-    format: AgentEngineeringFormat;
-    status: AgentEngineeringParseStatus;
-    previewMode: AgentEngineeringPreviewMode;
-    metadata: Record<string, unknown>;
-    extractedText: string;
-}
-export declare function isEngineeringFile(fileName: string): boolean;
-export declare function analyzeEngineeringFile(fileName: string, bytes: Uint8Array): EngineeringFileAnalysis | null;
+/** Standard MCP evidence stays in tool receipts; product presentations also reach the result projection. */
+export declare function parsePresentationBlocks(blocks: Array<AgentContentBlock | Record<string, unknown>>): AgentContentBlock[];

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

@@ -49,12 +49,32 @@ export interface TurnRequest {
     };
 }
 export interface EmbeddedRuntimeOptions {
+    /** Product-owned retrieval and model context projection before each inference.
+     * Original tool receipts remain complete; checkpoints retain the projected context.
+     * Keep task facts and complete tool call/result groups, and honour cancellation.
+     */
+    prepareContext?: (messages: readonly ChatMessage[], context: ModelContextPreparation) => Promise<ModelContextProjection>;
+    /** Model-aware message measurement; the fallback is an advisory estimate. */
+    countMessageTokens?: (message: Readonly<ChatMessage>, model: string) => number;
     /** Product-owned model projection; receipts retain the full result. Return undefined to keep it. */
     projectToolResult?: (message: Readonly<ChatMessage>) => Promise<string | undefined>;
     /** Evidence or new questions supplied by the product before accepting a model's final answer. */
     reviewCompletion?: (messages: readonly ChatMessage[], answer: string) => Promise<ChatMessage[]>;
     onCheckpoint?: (checkpoint: TurnCheckpoint) => Promise<void>;
 }
+export interface ModelContextPreparation {
+    model: string;
+    /** Context capacity after reserving configured output; Infinity when capacity metadata is disabled. */
+    inputBudgetTokens: number;
+    sessionId: string;
+    turnId: string;
+    signal?: AbortSignal;
+}
+export interface ModelContextProjection {
+    messages: ChatMessage[];
+    droppedCount: number;
+    strategy: string;
+}
 export interface TurnCheckpoint {
     turnId: string;
     sessionId: string;

package/dist/types/embedded/default-runtime-ports.d.ts

@@ -0,0 +1,6 @@
+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/embedded/index.d.ts

@@ -1,12 +1,15 @@
 export { createEmbeddedAgent } from "./embedded-agent.js";
+export { prepareSlidingWindowContext } from "./default-runtime-ports.js";
 export { corePackageVersion } from "./package-version.js";
-export { AgentContentBlockValidationError, analyzeEngineeringFile, createStandardPresentationToolResult, isEngineeringFile, parseAgentContentBlock, standardPresentationToolDefinitions, standardPresentationToolNames, } from "./content-blocks.js";
-export type { ContextAnchor, ContextEnvelope, SemanticToolCapability, ToolIdentity, UsageRecord, UsageSource, AgentLogger, ChatMessage, CreateEmbeddedAgentOptions, EmbeddedAgent, EmbeddedRuntimeOptions, LLMChunk, LLMRequest, LLMTransport, ModelRetryAuthorization, ToolDefinition, ToolInvoker, ToolInvocationContext, ToolResult, TurnCheckpoint, TokenUsage, TurnConfig, TurnEvent, TurnRequest, } from "./contracts.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";
 export type { ModelOperation, ModelRecoveryProof } from "./model-operation.js";
 export type { TaskMonetaryBudget } from "../runtime/ports/model-transport-contracts.js";
 export type { BusinessAssistantContext, BusinessGoal, BusinessGoalEvidence, BusinessGoalOutcome } from "./business-contracts.js";
+export { createBusinessToolAdapter } from "./business-tool-adapter.js";
+export type { BusinessToolAdapter, BusinessToolPort, BusinessToolObservation } from "./business-tool-adapter.js";
 export { createCloudAgent, completeCloudToolCheckpoint, canonicalCloudValue } from "./cloud-agent.js";
 export type { CloudAgent, CloudAgentOptions, CloudCheckpoint, CloudExecutionContext, CloudToolInvocation, CloudToolReceipt, CloudToolWait, CloudTurnEvent, CloudTurnRequest, } from "./cloud-agent.js";
 export { createCloudTaskRuntime } from "./cloud-task.js";
 export type { CloudTaskStore, CloudTaskSnapshot, CloudTaskStatus, CloudTaskClaim, CloudTaskEvent, CloudTaskEventPayload, CloudTaskRuntime, CloudTaskRuntimeOptions, } from "./cloud-task.js";
-export type { AgentAttachment, AgentAttachmentContentBlock, AgentAttachmentKind, AgentChoiceContentBlock, AgentContentBlock, AgentDiagramContentBlock, AgentEngineeringFormat, AgentEngineeringMetadata, AgentEngineeringParseStatus, AgentEngineeringPreviewMode, AgentInputAttachmentEvidence, AgentTableCell, AgentTableContentBlock, EngineeringFileAnalysis, StandardPresentationToolDefinition, StandardPresentationToolName, } from "./content-blocks.js";
+export type { AgentContentBlock } from "./content-blocks.js";

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

@@ -59,7 +59,10 @@ export interface ToolLoopRuntimePorts {
     compressMessages(messages: RuntimeCompressibleMessage[], options: {
         budget: number;
         model: string;
-    }): RuntimeCompressionResult;
+        sessionId: string;
+        turnId: string;
+        signal?: AbortSignal;
+    }): RuntimeCompressionResult | Promise<RuntimeCompressionResult>;
     createStreamingToolExecutor(config: StreamingToolExecutorPortConfig): StreamingToolExecutorPort;
 }
 export interface AgentRuntimePorts {

package/dist/types/runtime/ports/model-transport-contracts.d.ts

@@ -4,7 +4,9 @@ import type { ModelOperation, ModelRecoveryProof } from "../../embedded/model-op
 /** Immutable product task ceiling, enforced by the model service's financial authority. */
 export interface TaskMonetaryBudget {
     id: string;
-    currency: "CNY";
+    /** Currency or accounting unit accepted by the product's financial authority. */
+    currency: string;
+    /** Positive exact decimal; precision/range are owned by that financial authority. */
     maxAmount: string;
 }
 export interface LLMRequest {

package/package.json

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