@cuylabs/agent-core 4.9.0 → 5.0.0

package/dist/types/messages.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Message and token types for @cuylabs/agent-core
+ *
+ * Defines the message model used across conversations,
+ * including all role variants and token usage tracking.
+ */
+import type { ToolMetadata } from "./tool.js";
+import type { AgentContextFragmentMessageMetadata } from "../context/fragments/types.js";
+/**
+ * Message roles
+ */
+export type MessageRole = "user" | "assistant" | "tool" | "system";
+/**
+ * Base message interface
+ */
+export interface MessageBase {
+    id: string;
+    role: MessageRole;
+    createdAt: Date;
+    /**
+     * Metadata for model-visible runtime context injected as a context fragment instead
+     * of authored as a normal conversation turn.
+     */
+    contextFragment?: AgentContextFragmentMessageMetadata;
+}
+/**
+ * User message
+ */
+export interface UserMessage extends MessageBase {
+    role: "user";
+    content: string;
+    /** Optional custom system prompt for this message */
+    system?: string;
+}
+/**
+ * Assistant message
+ */
+export interface AssistantMessage extends MessageBase {
+    role: "assistant";
+    content: string;
+    /** Finish reason */
+    finish?: "stop" | "length" | "tool-calls" | "content-filter" | "error" | "unknown";
+    /** Token usage for this response */
+    tokens?: TokenUsage;
+    /** Cost in USD */
+    cost?: number;
+    /** Error if any */
+    error?: MessageError;
+    /** Tool calls made by the assistant (when finish === "tool-calls") */
+    toolCalls?: Array<{
+        toolCallId: string;
+        toolName: string;
+        args: unknown;
+    }>;
+}
+/**
+ * Tool result message
+ */
+export interface ToolMessage extends MessageBase {
+    role: "tool";
+    content: string;
+    toolCallId: string;
+    toolName: string;
+    result: unknown;
+    metadata?: ToolMetadata;
+    /**
+     * Timestamp when this tool result was compacted/pruned.
+     * Once set, this message won't be pruned again.
+     */
+    compactedAt?: number;
+}
+/**
+ * System message
+ */
+export interface SystemMessage extends MessageBase {
+    role: "system";
+    content: string;
+}
+/**
+ * Union of all message types
+ */
+export type Message = UserMessage | AssistantMessage | ToolMessage | SystemMessage;
+/**
+ * Error in a message
+ */
+export interface MessageError {
+    name: string;
+    message: string;
+    code?: string;
+    status?: number;
+}
+/**
+ * Token usage statistics
+ */
+export interface TokenUsage {
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+    /** Cache read tokens (if supported) */
+    cacheReadTokens?: number;
+    /** Cache write tokens (if supported) */
+    cacheWriteTokens?: number;
+}
+/** Accumulate token usage across multiple steps/turns. */
+export declare function accumulateUsage(current: TokenUsage | undefined, next: TokenUsage | undefined): TokenUsage | undefined;
+/**
+ * Session state
+ */
+export interface Session {
+    id: string;
+    messages: Message[];
+    createdAt: Date;
+    updatedAt: Date;
+    /** Optional title */
+    title?: string;
+    /** Parent session ID for forking */
+    parentID?: string;
+}
+//# sourceMappingURL=messages.d.ts.map

package/dist/types/messages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"messages.d.ts","sourceRoot":"","sources":["../../src/types/messages.ts"],"names":[],"mappings":"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"}

package/dist/types/stream.d.ts

@@ -0,0 +1,172 @@
+/**
+ * Stream types for @cuylabs/agent-core
+ *
+ * Defines the canonical StreamChunk union and related types
+ * for both AI SDK native and custom stream providers.
+ */
+/**
+ * Stream chunk types (AI SDK compatible + custom streams)
+ *
+ * This is the single canonical definition — used by both the
+ * streaming module and custom stream providers.
+ */
+export type StreamChunk = {
+    type: "text-start";
+} | {
+    type: "text-delta";
+    text: string;
+} | {
+    type: "text-end";
+} | {
+    type: "reasoning-start";
+    id: string;
+} | {
+    type: "reasoning-delta";
+    id: string;
+    text: string;
+} | {
+    type: "reasoning-end";
+    id: string;
+} | {
+    type: "tool-call";
+    toolName: string;
+    toolCallId: string;
+    input: unknown;
+} | {
+    type: "tool-result";
+    toolName: string;
+    toolCallId: string;
+    output: unknown;
+} | {
+    type: "tool-error";
+    toolName: string;
+    toolCallId: string;
+    error: unknown;
+} | {
+    type: "finish-step";
+    usage?: {
+        inputTokens?: number;
+        outputTokens?: number;
+        totalTokens?: number;
+    };
+    finishReason?: string;
+} | {
+    type: "finish";
+    totalUsage?: {
+        inputTokens?: number;
+        outputTokens?: number;
+        totalTokens?: number;
+    };
+} | {
+    type: "error";
+    error: unknown;
+} | {
+    type: "start-step";
+} | {
+    type: "start";
+} | {
+    type: "abort";
+} | {
+    type: "computer-call";
+    callId: string;
+    action: unknown;
+    pendingSafetyChecks?: unknown[];
+} | {
+    type: "step-usage";
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+    };
+};
+/**
+ * Custom stream provider function type.
+ *
+ * This matches the signature needed for agent-core's inference module,
+ * returning a StreamProviderResult-compatible object.
+ */
+export type StreamProvider = (input: StreamProviderInput) => Promise<StreamProviderResult>;
+/**
+ * Input for custom stream providers
+ */
+export interface StreamProviderInput {
+    /** Session ID for the active inference call */
+    sessionID?: string;
+    /** Turn ID for the active inference call */
+    turnID?: string;
+    /** Step number within the active turn */
+    step?: number;
+    /** System prompt */
+    system: string;
+    /** Messages to send */
+    messages: Array<{
+        role: string;
+        content: unknown;
+    }>;
+    /** Abort signal */
+    abortSignal?: AbortSignal;
+    /** Max iterations */
+    maxSteps?: number;
+}
+/**
+ * Result from custom stream providers (AI SDK StreamTextResult compatible)
+ */
+export interface StreamProviderResult {
+    /** Async iterable of stream chunks */
+    fullStream: AsyncIterable<StreamChunk>;
+    /** Promise resolving to final text */
+    text: Promise<string>;
+    /** Promise resolving to usage stats */
+    usage: Promise<{
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+    }>;
+    /** Promise resolving to finish reason */
+    finishReason: Promise<string>;
+}
+/**
+ * Configuration for stream provider factory.
+ * Contains everything needed to create a stream provider for a specific model.
+ */
+export interface StreamProviderConfig {
+    /** API key to use */
+    apiKey?: string;
+    /** Display dimensions */
+    display?: {
+        width: number;
+        height: number;
+    };
+    /** Environment type */
+    environment?: string;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+/**
+ * Stream provider factory - creates a stream provider for a given model.
+ *
+ * This is attached to enhanced tools (like computer tools) to allow
+ * the Agent to automatically configure the right stream provider
+ * when a model requires custom handling (e.g., OpenAI computer-use-preview).
+ */
+export type StreamProviderFactory = (modelId: string, config: StreamProviderConfig) => StreamProvider;
+/**
+ * Enhanced tools array with additional capabilities.
+ *
+ * This extends the standard Tool.AnyInfo[] with optional metadata
+ * that the Agent can use for automatic configuration.
+ */
+export interface EnhancedTools extends Array<unknown> {
+    /**
+     * Factory to create a stream provider for models that need custom streaming.
+     * Called by the Agent when it detects a model that requires special handling.
+     */
+    __streamProviderFactory?: StreamProviderFactory;
+    /**
+     * Model patterns that require the custom stream provider.
+     * Used by the Agent to detect when to use the factory.
+     * Default patterns: ["computer-use-preview"]
+     */
+    __customStreamModels?: string[];
+}
+//# sourceMappingURL=stream.d.ts.map

package/dist/types/stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.d.ts","sourceRoot":"","sources":["../../src/types/stream.ts"],"names":[],"mappings":"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"}

package/dist/types/tool.d.ts

@@ -0,0 +1,309 @@
+/**
+ * Tool-related types for @cuylabs/agent-core
+ *
+ * Defines the interfaces for tool execution context, results,
+ * and metadata used throughout the agent system.
+ */
+import type { ToolHost } from "../tool/host/types.js";
+import type { ScopeSnapshot } from "../execution/scope/types.js";
+import type { ApprovalCorrection, RiskLevel } from "../safety/types.js";
+import type { AgentEvent } from "./events.js";
+import type { HumanInputController } from "../human/controller.js";
+/**
+ * Turn tracker interface for tool context
+ * Minimal interface to avoid circular dependencies
+ */
+export interface TurnTrackerContext {
+    /** Capture baseline before writing to a file */
+    beforeWrite(path: string): Promise<boolean>;
+    /** Check if a file is being tracked */
+    isTracking(path: string): boolean;
+    /** Current turn identifier when a turn is active. */
+    getCurrentTurnId?(): string | null;
+}
+/**
+ * Declares a tool's runtime characteristics so the framework can make
+ * informed decisions about parallelism, approval flow, and interruption.
+ *
+ * All fields are optional — unset fields use conservative defaults
+ * (serial execution, moderate risk, non-read-only).
+ */
+export interface ToolCapabilities {
+    /**
+     * Whether this tool can safely execute in parallel with other tool calls
+     * in the same step. When `false` (default), the runtime serializes
+     * execution to avoid conflicts.
+     *
+     * Can be a static boolean or a function that inspects the input
+     * (e.g., read commands are parallel-safe, write commands are not).
+     */
+    parallelSafe?: boolean | ((input: unknown) => boolean);
+    /**
+     * Whether this tool only reads state without modifying it.
+     * Informs approval (read-only tools may skip confirmation),
+     * replay policy, and parallelism decisions.
+     *
+     * Can be a static boolean or a function of the input.
+     */
+    readOnly?: boolean | ((input: unknown) => boolean);
+    /**
+     * Whether this tool performs irreversible operations (delete, overwrite,
+     * send to external service). Destructive tools get stricter approval
+     * treatment and may be blocked in non-interactive sessions.
+     */
+    destructive?: boolean | ((input: unknown) => boolean);
+    /**
+     * Risk classification for the approval system.
+     * Overrides the default risk map in `safety/risk.ts` for this specific tool.
+     * When unset, falls back to the framework's built-in classification.
+     */
+    riskLevel?: RiskLevel;
+    /**
+     * What should happen when the user submits a new message while this
+     * tool is still running.
+     *
+     * - `"cancel"` — abort the tool and discard its partial result
+     * - `"finish"` — let the tool complete before processing the new message
+     *
+     * Defaults to `"finish"`.
+     */
+    onInterrupt?: "cancel" | "finish";
+    /**
+     * Maximum output size in characters before truncation kicks in.
+     * Overrides the global truncation limits for this specific tool.
+     * Set to `Infinity` to disable truncation (use with care).
+     */
+    maxOutputChars?: number;
+    /**
+     * Whether this tool represents a human-input request rather than a
+     * normal side-effecting tool call.
+     *
+     * Durable runtimes can use this to pause on workflow events instead of
+     * blocking inside a tool execution activity.
+     */
+    humanInput?: boolean;
+}
+/**
+ * Declares how a tool uses the configured execution host.
+ *
+ * This metadata is descriptive first: it makes host-backed tools explicit
+ * in inventories, reviews, and future capability gating. The executor also
+ * uses it to fail early when a tool requires a host but none was provided.
+ */
+export interface ToolHostRequirements {
+    /**
+     * Whether this tool expects an execution host to be present.
+     *
+     * Framework-created agents always provide a host by default, but direct
+     * executor callers may omit one. When unset, the framework derives this
+     * from the filesystem and shell fields.
+     */
+    required?: boolean;
+    /**
+     * Filesystem access level used through the host.
+     *
+     * - `"none"` — the tool does not use host-backed file operations
+     * - `"read"` — reads, stats, existence checks, or directory listings
+     * - `"write"` — writes, creates directories, deletes, or otherwise mutates files
+     */
+    filesystem?: "none" | "read" | "write";
+    /**
+     * Whether the tool runs shell commands through `host.exec(...)`.
+     */
+    shell?: boolean;
+}
+/**
+ * Determine whether a tool requires an execution host.
+ */
+export declare function requiresToolHost(requirements: ToolHostRequirements | undefined): boolean;
+/**
+ * Return the configured execution host or throw a clear author-facing error.
+ *
+ * Prefer this helper inside host-backed tools instead of `ctx.host!`.
+ */
+export declare function getRequiredToolHost(ctx: Pick<ToolContext, "host">, options?: {
+    toolName?: string;
+    usage?: string;
+}): ToolHost;
+/**
+ * Resolve a capability that may be static or input-dependent.
+ */
+export declare function resolveCapability(cap: boolean | ((input: unknown) => boolean) | undefined, input: unknown, fallback: boolean): boolean;
+/**
+ * Result of validating tool input before execution.
+ *
+ * Validation runs before middleware hooks and approval — a failed
+ * validation never triggers side effects or user prompts.
+ */
+export type InputCheckResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Tool execution context
+ */
+export interface ToolContext {
+    /** Working directory for file operations */
+    cwd: string;
+    /** Abort signal for cancellation */
+    abort: AbortSignal;
+    /** Session ID */
+    sessionID: string;
+    /** Turn ID when the tool call belongs to an active turn. */
+    turnID?: string;
+    /** Message ID */
+    messageID: string;
+    /** Agent name */
+    agent: string;
+    /** Active execution scope snapshot for this tool call. */
+    scope?: ScopeSnapshot;
+    /**
+     * Managed human-input controller for tools that need user decisions.
+     */
+    humanInputController?: HumanInputController;
+    /**
+     * Optional event sink for tools that need to raise framework lifecycle
+     * events during execution.
+     */
+    emitEvent?: (event: AgentEvent) => void | Promise<void>;
+    /**
+     * Execution environment for file and process operations.
+     *
+     * Tools should call `ctx.host.readFile()`, `ctx.host.exec()`, etc.
+     * instead of importing `fs` and `child_process` directly. This
+     * allows the same tools to work on local and custom host backends
+     * without code changes.
+     *
+     * Prefer `getRequiredToolHost(ctx, ...)` inside host-backed tools
+     * instead of `ctx.host!` so missing-host failures stay explicit.
+     *
+     * When not provided, tools may fall back to direct Node.js APIs,
+     * but new tools should always prefer `ctx.host`.
+     */
+    host?: ToolHost;
+    /**
+     * Turn change tracker - automatically captures file baselines.
+     * Call `turnTracker.beforeWrite(path)` before modifying files
+     * for undo/diff capabilities.
+     */
+    turnTracker?: TurnTrackerContext;
+    /**
+     * Capabilities declared by the tool after initialization.
+     *
+     * Populated by the executor before middleware hooks run so that
+     * middleware (e.g. approval) can inspect `readOnly`, `riskLevel`,
+     * and `destructive` without re-initializing the tool.
+     */
+    toolCapabilities?: ToolCapabilities;
+    /**
+     * Host usage declared by the tool after initialization.
+     *
+     * Useful for inventories, diagnostics, and runtime checks that want to know
+     * whether a tool depends on host-backed files or shell execution.
+     */
+    hostRequirements?: ToolHostRequirements;
+    /**
+     * Tool-declared pattern extractor for the approval system.
+     *
+     * When set, the approval handler uses this instead of the generic
+     * `extractApprovalPatterns` heuristic. Lets each tool control how
+     * its inputs map to glob-matchable permission strings.
+     */
+    permissionPatterns?: (input: unknown) => string[];
+    /** Extra context data */
+    extra?: Record<string, unknown>;
+}
+/**
+ * Result returned by a tool
+ */
+export interface ToolResult {
+    /** Short title for display */
+    title: string;
+    /** Main output text */
+    output: string;
+    /** Optional metadata */
+    metadata?: ToolMetadata;
+}
+/**
+ * File operation metadata - declare how a tool modifies files
+ * Used by TurnChangeTracker for automatic baseline capture
+ */
+export interface FileOperationMeta {
+    /**
+     * Names of parameters that contain file paths to track.
+     * The tracker will capture baselines for these files before the tool runs.
+     * @example ['path'] for write tool, ['filePath'] for edit tool
+     */
+    pathArgs?: string[];
+    /**
+     * Type of file operation - determines if baseline capture is needed.
+     * - 'read': No baseline capture (file not modified)
+     * - 'write': Capture baseline before overwriting
+     * - 'create': Capture baseline (to know file didn't exist)
+     * - 'delete': Capture baseline before deletion
+     */
+    operationType?: "read" | "write" | "delete" | "create";
+}
+/**
+ * Replay mode used by resume-capable runtimes after a crash.
+ *
+ * - `replay` — the tool may be executed again automatically
+ * - `skip` — the tool should not be replayed automatically
+ * - `manual` — a higher-level runtime must require an explicit decision
+ */
+export type ToolReplayMode = "replay" | "skip" | "manual";
+/**
+ * Coarse side-effect classification for tool execution.
+ *
+ * - `none` — read-only or otherwise safe to repeat
+ * - `local` — mutates local state such as files
+ * - `external` — may affect processes, networks, services, or systems
+ */
+export type ToolSideEffectLevel = "none" | "local" | "external";
+/**
+ * Declares how a resume-capable runtime should treat a tool after failure.
+ *
+ * This stays infrastructure-agnostic so Dapr and other runtimes can consume
+ * the same semantics without leaking runtime-specific types into `agent-core`.
+ */
+export interface ToolReplayPolicy {
+    /** Replay behavior requested by the tool author. */
+    mode?: ToolReplayMode;
+    /** Coarse side-effect classification. */
+    sideEffectLevel?: ToolSideEffectLevel;
+    /** Optional human-readable rationale for audits and recovery UIs. */
+    reason?: string;
+}
+/**
+ * Fully resolved replay policy with defaults applied.
+ */
+export interface NormalizedToolReplayPolicy {
+    mode: ToolReplayMode;
+    sideEffectLevel: ToolSideEffectLevel;
+    reason?: string;
+}
+/**
+ * Tool metadata
+ */
+export interface ToolMetadata {
+    /** Whether output was truncated */
+    truncated?: boolean;
+    /** Path to full output if truncated */
+    outputPath?: string;
+    /**
+     * File operation metadata for automatic turn tracking.
+     * When set, the agent will automatically capture file baselines
+     * before tool execution for undo/diff capabilities.
+     */
+    fileOps?: FileOperationMeta;
+    /**
+     * Structured HITL correction metadata when a tool call is denied before
+     * execution and the runtime wants to preserve that signal explicitly.
+     */
+    approvalCorrection?: ApprovalCorrection;
+    /** Additional metadata */
+    [key: string]: unknown;
+}
+//# sourceMappingURL=tool.d.ts.map

package/dist/types/tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../../src/types/tool.ts"],"names":[],"mappings":"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"}

package/dist/types/turn-source.d.ts

@@ -0,0 +1,36 @@
+import type { AgentEvent } from "./events.js";
+/**
+ * Options accepted by the canonical chat-turn source contract.
+ *
+ * This type is intentionally small and transport-neutral. Additive optional
+ * fields are safe; renaming, removing, or narrowing fields is a breaking
+ * change for every channel adapter and runtime source.
+ *
+ * @public
+ * @stable
+ */
+export interface AgentTurnSourceChatOptions {
+    /** Aborts the turn when the signal fires. */
+    abort?: AbortSignal;
+    /** Per-turn system prompt override. */
+    system?: string;
+}
+/**
+ * Canonical chat-turn source for the @cuylabs agent platform.
+ *
+ * Any object that can run a chat turn and yield `AgentEvent`s satisfies this
+ * shape. It is consumed by `Agent`, `agent-server` adapters, channel adapters
+ * such as M365 and Slack, custom runtimes, and test stubs.
+ *
+ * Breaking changes to this interface require coordinated major releases of
+ * `@cuylabs/agent-core`, `@cuylabs/agent-server`, and every published channel
+ * adapter. Additive optional fields on `AgentTurnSourceChatOptions` are
+ * non-breaking but should be called out in the changeset.
+ *
+ * @public
+ * @stable
+ */
+export interface AgentTurnSource {
+    chat(sessionId: string, message: string, options?: AgentTurnSourceChatOptions): AsyncGenerator<AgentEvent>;
+}
+//# sourceMappingURL=turn-source.d.ts.map

package/dist/types/turn-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn-source.d.ts","sourceRoot":"","sources":["../../src/types/turn-source.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C;;;;;;;;;GASG;AACH,MAAM,WAAW,0BAA0B;IACzC,6CAA6C;IAC7C,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,uCAAuC;IACvC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,CACF,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,0BAA0B,GACnC,cAAc,CAAC,UAAU,CAAC,CAAC;CAC/B"}

package/dist/utils/sleep.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Promise-based sleep utility.
+ *
+ * @param ms - Duration to wait in milliseconds.
+ */
+export declare function sleep(ms: number): Promise<void>;
+//# sourceMappingURL=sleep.d.ts.map

package/dist/utils/sleep.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sleep.d.ts","sourceRoot":"","sources":["../../src/utils/sleep.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/C"}