@xiaozhiclaw/qlogicagent-core 0.1.4 → 0.1.6

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

@@ -0,0 +1,76 @@
+import { type AgentContentBlock } from "./content-blocks.js";
+import type { CreateEmbeddedAgentOptions, ToolResult, TurnCheckpoint, TurnEvent, TurnRequest } from "./contracts.js";
+export interface CloudExecutionContext {
+    applicationId: string;
+    tenantId: string;
+    actorId: string;
+    scopeId: string;
+    definitionVersion: string;
+}
+export interface CloudToolInvocation {
+    context: Readonly<CloudExecutionContext>;
+    turnId: string;
+    sessionId: string;
+    callId: string;
+    round: number;
+    name: string;
+    arguments: string;
+}
+export interface CloudCheckpoint extends TurnCheckpoint {
+    schemaVersion: 1;
+    context: CloudExecutionContext;
+    /** Exact model/tool/Skill configuration, not a credential or an authorization. */
+    binding: string;
+    contentBlocks: AgentContentBlock[];
+}
+export interface CloudTurnRequest extends Omit<TurnRequest, "continuation"> {
+    context: CloudExecutionContext;
+    resume?: CloudCheckpoint;
+}
+export interface CloudToolWait {
+    kind: "wait";
+    wait: {
+        id: string;
+        kind: "input" | "confirmation" | "external";
+        reference: string;
+    };
+}
+export type CloudTurnEvent = TurnEvent | {
+    type: "waiting";
+    turnId: string;
+    invocation: CloudToolInvocation;
+    wait: CloudToolWait["wait"];
+};
+export interface CloudToolReceipt {
+    invocation: CloudToolInvocation;
+    result: ToolResult;
+}
+/** Only the product may supply reconciled receipts; this function never executes tools. */
+export declare function completeCloudToolCheckpoint(input: CloudCheckpoint, receipts: CloudToolReceipt[]): CloudCheckpoint;
+export interface CloudAgentOptions extends Omit<CreateEmbeddedAgentOptions, "toolInvoker" | "runtime"> {
+    toolInvoker: {
+        invoke(invocation: CloudToolInvocation, signal?: AbortSignal): Promise<ToolResult | CloudToolWait>;
+    };
+    /** The product revalidates the authenticated actor before inference and each effect. */
+    authorize(context: Readonly<CloudExecutionContext>, action: {
+        type: "model";
+    } | {
+        type: "tool";
+        name: string;
+        callId: string;
+    }): Promise<void>;
+    runtime?: Omit<NonNullable<CreateEmbeddedAgentOptions["runtime"]>, "onCheckpoint">;
+    checkpoints?: {
+        save(checkpoint: CloudCheckpoint): Promise<void>;
+    };
+    /** 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>;
+}
+export interface CloudAgent {
+    run(request: CloudTurnRequest, signal?: AbortSignal): AsyncGenerator<CloudTurnEvent>;
+}
+declare function canonical(value: unknown): string;
+export { canonical as canonicalCloudValue };
+/** A product-hosted adapter over the canonical loop; it owns no database or job scheduler. */
+export declare function createCloudAgent(options: CloudAgentOptions): CloudAgent;

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

@@ -0,0 +1,76 @@
+import { type CloudAgentOptions, type CloudCheckpoint, type CloudExecutionContext, type CloudToolReceipt, type CloudToolWait, type CloudTurnEvent, type CloudTurnRequest } from "./cloud-agent.js";
+import type { ToolResult } from "./contracts.js";
+export type CloudTaskStatus = "queued" | "running" | "waiting_input" | "waiting_confirmation" | "waiting_external" | "reconciliation_required" | "completed" | "stopped" | "failed" | "cancelled";
+export interface CloudTaskSnapshot {
+    id: string;
+    revision: number;
+    cursor: number;
+    status: CloudTaskStatus;
+    request: CloudTurnRequest;
+    checkpoint?: CloudCheckpoint;
+    receipts: CloudToolReceipt[];
+    wait?: {
+        invocation: CloudToolReceipt["invocation"];
+        descriptor: CloudToolWait["wait"];
+    };
+    errorCode?: string;
+}
+export type CloudTaskEventPayload = CloudTurnEvent | {
+    type: "task_status";
+    status: CloudTaskStatus;
+} | {
+    type: "checkpoint";
+    phase: CloudCheckpoint["phase"];
+} | {
+    type: "receipt";
+    callId: string;
+    round: number;
+    name: string;
+};
+export interface CloudTaskEvent {
+    cursor: number;
+    event: CloudTaskEventPayload;
+}
+export interface CloudTaskClaim {
+    task: CloudTaskSnapshot;
+    leaseId: string;
+}
+/** Product-owned atomic persistence. Every query is scope-bound; update and cancel fence workers. */
+export interface CloudTaskStore {
+    /** Deduplicate the id/request in the authenticated product scope. */
+    create(task: CloudTaskSnapshot): Promise<CloudTaskSnapshot>;
+    load(context: CloudExecutionContext, id: string): Promise<CloudTaskSnapshot>;
+    /** Atomically claim only queued work; never steal a running or terminal task. */
+    claim(context: CloudExecutionContext, id: string): Promise<CloudTaskClaim | null>;
+    /** False on expired/revoked lease or cancellation. Products set their lease duration. */
+    renew(context: CloudExecutionContext, id: string, leaseId: string): Promise<boolean>;
+    /** CAS + live lease check + snapshot + next contiguous event cursor in one transaction. */
+    update(context: CloudExecutionContext, id: string, expectedRevision: number, task: CloudTaskSnapshot, event: CloudTaskEventPayload, leaseId?: string): Promise<CloudTaskSnapshot>;
+    release(context: CloudExecutionContext, id: string, leaseId: string): Promise<void>;
+    events(context: CloudExecutionContext, id: string, after: number, limit: number): Promise<CloudTaskEvent[]>;
+    /** Atomic cancel and lease invalidation; terminal tasks stay unchanged. */
+    cancel(context: CloudExecutionContext, id: string): Promise<CloudTaskSnapshot>;
+    /** Only an expired worker may be fenced and moved to reconciliation_required. */
+    interrupt(context: CloudExecutionContext, id: string): Promise<CloudTaskSnapshot>;
+}
+export interface CloudTaskRuntimeOptions {
+    store: CloudTaskStore;
+    agent: Omit<CloudAgentOptions, "checkpoints" | "onToolResult" | "onWait">;
+    authorize(context: CloudExecutionContext, action: "create" | "read" | "execute" | "cancel" | "complete_wait" | "recover"): Promise<void>;
+    /** Validate actual employee 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<void>;
+    heartbeatMs?: number;
+}
+export interface CloudTaskRuntime {
+    create(id: string, request: CloudTurnRequest): Promise<CloudTaskSnapshot>;
+    get(context: CloudExecutionContext, id: string): Promise<CloudTaskSnapshot>;
+    events(context: CloudExecutionContext, id: string, after?: number, limit?: number): Promise<CloudTaskEvent[]>;
+    /** 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>;
+    completeWait(context: CloudExecutionContext, id: string, waitId: string, result: ToolResult): Promise<CloudTaskSnapshot>;
+    recover(context: CloudExecutionContext, id: string, receipts?: CloudToolReceipt[]): Promise<CloudTaskSnapshot>;
+}
+export declare function createCloudTaskRuntime(options: CloudTaskRuntimeOptions): CloudTaskRuntime;

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

@@ -0,0 +1,109 @@
+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 {
+    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;
+}
+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);
+}
+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;

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

@@ -1,3 +1,4 @@
+import type { AgentContentBlock } from "./content-blocks.js";
 export interface AgentLogger {
     info(message: string): void;
     info(context: Record<string, unknown>, message: string): void;
@@ -31,6 +32,9 @@ export interface ChatMessage {
 }
 export interface ToolDefinition {
     type: "function";
+    meta?: {
+        executionTimeoutMs?: number;
+    };
     function: {
         name: string;
         description: string;
@@ -97,6 +101,7 @@ export type LLMChunk = {
 } | {
     type: "error";
     message: string;
+    outcome?: "rejected" | "unknown";
 } | {
     type: "done";
     finishReason: string;
@@ -104,14 +109,32 @@ export type LLMChunk = {
 export interface LLMTransport {
     stream(request: LLMRequest, apiKey: string, signal?: AbortSignal): AsyncGenerator<LLMChunk>;
 }
+/** All three must be true on a thrown transport error before core can retry a model request. */
+export interface ModelRetryAuthorization {
+    retryable: boolean;
+    safeToRetry: boolean;
+    automaticRetryAuthorized: boolean;
+    /** Product transport evidence: a definitive rejection is terminal; unknown outcomes require reconciliation. */
+    outcome?: "rejected" | "unknown";
+}
+export interface ToolInvocationContext {
+    callId: string;
+    sessionId: string;
+    round: number;
+}
+export interface ToolResult {
+    result: string;
+    error?: string;
+    toolReferences?: string[];
+    imageUrls?: string[];
+    contentBlocks?: AgentContentBlock[];
+    structuredContent?: Record<string, unknown>;
+    mcpMeta?: Record<string, unknown>;
+    mcpIsError?: boolean;
+    details?: Record<string, unknown>;
+}
 export interface ToolInvoker {
-    invoke(turnId: string, name: string, args: string, signal?: AbortSignal): Promise<{
-        result: string;
-        error?: string;
-        toolReferences?: string[];
-        imageUrls?: string[];
-        details?: Record<string, unknown>;
-    }>;
+    invoke(turnId: string, name: string, args: string, signal?: AbortSignal, invocation?: ToolInvocationContext): Promise<ToolResult>;
 }
 export interface TurnConfig {
     model?: string;
@@ -126,6 +149,11 @@ export interface TurnConfig {
     parallelToolCalls?: boolean;
     streamRequired?: boolean;
     toolChoice?: "auto" | "none" | "required";
+    reasoning?: LLMRequest["reasoning"];
+    promptCacheKey?: string;
+    promptCacheRetention?: LLMRequest["promptCacheRetention"];
+    serviceTier?: LLMRequest["serviceTier"];
+    textVerbosity?: LLMRequest["textVerbosity"];
 }
 export interface TurnRequest {
     turnId: string;
@@ -135,6 +163,11 @@ export interface TurnRequest {
     tools: ToolDefinition[];
     systemPrompt?: string;
     config?: TurnConfig;
+    /** product-validated continuation; cloud consumers should use CloudCheckpoint. */
+    continuation?: {
+        completedRounds: number;
+        usage: TokenUsage;
+    };
 }
 export interface TokenUsage {
     inputTokens?: number;
@@ -190,6 +223,12 @@ export type TurnEvent = {
     type: "reasoning_delta";
     turnId: string;
     text: string;
+} | {
+    type: "lifecycle";
+    turnId: string;
+    kind: "context_compression";
+    status: string;
+    detail: string;
 } | {
     type: "annotations";
     turnId: string;
@@ -221,6 +260,7 @@ export type TurnEvent = {
     model?: string;
     provider?: string;
     recoveryTrace?: Record<string, number>;
+    contentBlocks?: AgentContentBlock[];
 } | {
     type: "error";
     turnId: string;
@@ -230,6 +270,15 @@ export type TurnEvent = {
 };
 export interface EmbeddedRuntimeOptions {
     maxToolResultChars?: number;
+    onCheckpoint?: (checkpoint: TurnCheckpoint) => Promise<void>;
+}
+export interface TurnCheckpoint {
+    turnId: string;
+    sessionId: string;
+    phase: "model_ready" | "tools_pending";
+    messages: ChatMessage[];
+    completedRounds: number;
+    usage: TokenUsage;
 }
 export interface EmbeddedAgent {
     run(request: TurnRequest, signal?: AbortSignal): AsyncGenerator<TurnEvent>;

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

@@ -0,0 +1,2 @@
+import type { CreateEmbeddedAgentOptions, EmbeddedAgent } from "./contracts.js";
+export declare function createEmbeddedAgent(options: CreateEmbeddedAgentOptions): EmbeddedAgent;

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

@@ -1,3 +1,8 @@
-import type { CreateEmbeddedAgentOptions, EmbeddedAgent } from "./contracts.js";
-export declare function createEmbeddedAgent(options: CreateEmbeddedAgentOptions): EmbeddedAgent;
-export type { AgentLogger, ChatMessage, CreateEmbeddedAgentOptions, EmbeddedAgent, EmbeddedRuntimeOptions, LLMChunk, LLMRequest, LLMTransport, ToolDefinition, ToolInvoker, TurnConfig, TurnEvent, TurnRequest, } from "./contracts.js";
+export { createEmbeddedAgent } from "./embedded-agent.js";
+export { AgentContentBlockValidationError, analyzeEngineeringFile, createStandardPresentationToolResult, isEngineeringFile, parseAgentContentBlock, standardPresentationToolDefinitions, standardPresentationToolNames, } from "./content-blocks.js";
+export type { AgentLogger, ChatMessage, CreateEmbeddedAgentOptions, EmbeddedAgent, EmbeddedRuntimeOptions, LLMChunk, LLMRequest, LLMTransport, ModelRetryAuthorization, ToolDefinition, ToolInvoker, ToolInvocationContext, ToolResult, TurnCheckpoint, TokenUsage, TurnConfig, TurnEvent, TurnRequest, } from "./contracts.js";
+export { createCloudAgent, completeCloudToolCheckpoint } 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";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@xiaozhiclaw/qlogicagent-core",
-  "version": "0.1.4",
-  "description": "Host-neutral qlogicagent tool-loop runtime for server embedding",
+  "version": "0.1.6",
+  "description": "Shared SaaS Agent inference and durable task runtime",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/types/embedded/index.d.ts",
@@ -15,19 +15,13 @@
     "dist/",
     "README.md"
   ],
-  "scripts": {
-    "build": "node scripts/build.mjs",
-    "prepare": "node scripts/build.mjs"
-  },
   "publishConfig": {
     "access": "public"
   },
   "engines": {
     "node": ">=24.0.0 <25"
   },
-  "devDependencies": {
-    "@types/node": "^22.15.0",
-    "esbuild": "^0.28.0",
-    "typescript": "^5.9.3"
+  "scripts": {
+    "build": "node scripts/build.mjs"
   }
-}
+}