actoviq-agent-sdk 0.2.0 → 0.3.1

package/dist/src/types.d.ts

@@ -21,6 +21,9 @@ export interface ToolExecutionContext {
     classifier?: ActoviqToolClassifier;
     approver?: ActoviqToolApprover;
     hooks?: ActoviqHooks;
+    modelApi?: ModelApi;
+    model?: string;
+    provider?: string;
 }
 export type ActoviqPermissionMode = 'default' | 'acceptEdits' | 'bypassPermissions' | 'plan' | 'auto';
 export type ActoviqPermissionBehavior = 'allow' | 'deny' | 'ask';
@@ -81,6 +84,27 @@ export type ActoviqCanUseToolResult = {
     reason?: string;
 } | void;
 export type ActoviqCanUseTool = (context: ActoviqCanUseToolContext) => Promise<ActoviqCanUseToolResult> | ActoviqCanUseToolResult;
+export interface ToolProgressData {
+    type: string;
+    [key: string]: unknown;
+}
+export interface ToolProgress<P extends ToolProgressData = ToolProgressData> {
+    toolUseID: string;
+    data: P;
+}
+export type ToolCallProgress<P extends ToolProgressData = ToolProgressData> = (progress: ToolProgress<P>) => void;
+export type ValidationResult = {
+    result: true;
+} | {
+    result: false;
+    message: string;
+    errorCode?: number;
+};
+export interface ToolPromptOptions {
+    tools: string[];
+    workDir: string;
+    permissionMode?: ActoviqPermissionMode;
+}
 export interface CreateToolOptions<Input = any, Output = any> {
     name: string;
     description: string;
@@ -98,6 +122,26 @@ export interface CreateToolOptions<Input = any, Output = any> {
         runId: string;
         sessionId?: string;
     }) => Promise<'allow' | 'deny' | 'ask' | void> | 'allow' | 'deny' | 'ask' | void;
+    /** Alternative names for backwards compatibility when a tool is renamed. */
+    aliases?: string[];
+    /** Human-readable display name shown in the UI. Defaults to name. */
+    userFacingName?: (input?: Input) => string;
+    /** One-line capability phrase (3-10 words) for tool search keyword matching. */
+    searchHint?: string;
+    /** Behavior when a new user message arrives during tool execution. Defaults to 'block'. */
+    interruptBehavior?: 'cancel' | 'block';
+    /** Whether the non-verbose rendering is truncated (gates expand affordance). */
+    isResultTruncated?: (output: Output) => boolean;
+    /** Maximum size in characters before result is persisted to disk. Defaults to 50000. */
+    maxResultSizeChars?: number;
+    /** Whether two inputs are equivalent (for dedup). */
+    inputsEquivalent?: (a: Input, b: Input) => boolean;
+    /** Pre-flight validation — determines if the tool is allowed to run with this input. */
+    validateInput?: (input: Input, context: ToolExecutionContext) => Promise<ValidationResult> | ValidationResult;
+    /** Compact summary for the tool invocation in collapsed views. */
+    getToolUseSummary?: (input: Input) => string;
+    /** System prompt text teaching the model how to use this tool. */
+    prompt?: (options: ToolPromptOptions) => Promise<string> | string;
 }
 export interface AgentToolDefinition<Input = any, Output = any> {
     kind: 'local';
@@ -107,7 +151,7 @@ export interface AgentToolDefinition<Input = any, Output = any> {
     outputSchema?: z.ZodType<Output>;
     inputJsonSchema: Record<string, unknown>;
     serialize?: (output: Output) => string | ToolResultBlockParam['content'];
-    execute: (input: Input, context: ToolExecutionContext) => Promise<Output> | Output;
+    execute: (input: Input, context: ToolExecutionContext, onProgress?: ToolCallProgress) => Promise<Output> | Output;
     strict?: boolean;
     examples?: Array<Record<string, unknown>>;
     isReadOnly?: (input?: Input) => boolean;
@@ -119,6 +163,16 @@ export interface AgentToolDefinition<Input = any, Output = any> {
         runId: string;
         sessionId?: string;
     }) => Promise<'allow' | 'deny' | 'ask' | void> | 'allow' | 'deny' | 'ask' | void;
+    aliases?: string[];
+    userFacingName?: (input?: Input) => string;
+    searchHint?: string;
+    interruptBehavior?: 'cancel' | 'block';
+    isResultTruncated?: (output: Output) => boolean;
+    maxResultSizeChars?: number;
+    inputsEquivalent?: (a: Input, b: Input) => boolean;
+    validateInput?: (input: Input, context: ToolExecutionContext) => Promise<ValidationResult> | ValidationResult;
+    getToolUseSummary?: (input: Input) => string;
+    prompt?: (options: ToolPromptOptions) => Promise<string> | string;
 }
 export interface LocalMcpServerDefinition {
     kind: 'local';
@@ -156,6 +210,7 @@ export interface ModelRequest {
     metadata?: Metadata;
     context_management?: Record<string, unknown>;
     stop_sequences?: string[];
+    extra_tool_schemas?: Record<string, unknown>[];
     signal?: AbortSignal;
 }
 export interface ModelStreamHandle extends AsyncIterable<MessageStreamEvent> {
@@ -177,11 +232,13 @@ export interface ResolvedToolAdapter {
     provider: 'local' | 'mcp';
     mcpServerName?: string;
     providerTool: ProviderTool;
-    execute: (input: unknown, context: ToolExecutionContext) => Promise<ResolvedToolExecutionResult>;
+    execute: (input: unknown, context: ToolExecutionContext, onProgress?: ToolCallProgress) => Promise<ResolvedToolExecutionResult>;
     isReadOnly?: (input?: unknown) => boolean;
     isDestructive?: (input?: unknown) => boolean;
     requiresUserInteraction?: () => boolean;
     isConcurrencySafe?: () => boolean;
+    /** Per-tool result size cap in chars before artifacting to disk. */
+    maxResultSizeChars?: number;
     checkPermissions?: (context: {
         mode: ActoviqPermissionMode;
         runId: string;
@@ -204,7 +261,12 @@ export interface ResolvedRuntimeConfig {
     clientName: string;
     clientVersion: string;
     systemPrompt?: string;
+    /** ReAct loop turn cap. Defaults to Infinity (no cap) like Claude Code's main agent. */
     maxToolIterations: number;
+    /** Model switched to after repeated overload/rate-limit failures. */
+    fallbackModel?: string;
+    /** Add a prompt-cache breakpoint to Anthropic requests. Defaults to true. */
+    promptCachingEnabled: boolean;
     userId?: string;
     metadata: Record<string, unknown>;
     compact: ActoviqCompactConfig;
@@ -283,6 +345,7 @@ export interface ActoviqAgentDefinition {
     description: string;
     systemPrompt?: string;
     model?: string;
+    maxToolIterations?: number;
     metadata?: Record<string, unknown>;
     hooks?: ActoviqHooks;
     tools?: AgentToolDefinition[];
@@ -294,6 +357,7 @@ export interface ActoviqAgentDefinitionSummary {
     name: string;
     description: string;
     model?: string;
+    maxToolIterations?: number;
     toolNames: string[];
     mcpServerNames: string[];
     inheritDefaultTools: boolean;
@@ -447,12 +511,16 @@ export interface CreateAgentSdkOptions {
     clientName?: string;
     clientVersion?: string;
     systemPrompt?: string;
+    /** Optional ReAct loop turn cap. Unset means unlimited. */
     maxToolIterations?: number;
+    fallbackModel?: string;
+    promptCachingEnabled?: boolean;
     userId?: string;
     metadata?: Record<string, unknown>;
     tools?: AgentToolDefinition[];
     mcpServers?: AgentMcpServerDefinition[];
     agents?: ActoviqAgentDefinition[];
+    disableDefaultAgents?: boolean;
     skills?: ActoviqSkillDefinition[];
     skillDirectories?: string[];
     disableDefaultSkills?: boolean;
@@ -479,8 +547,26 @@ export interface ActoviqCompactConfig {
     apiMicrocompactEnabled?: boolean;
     apiMicrocompactMaxInputTokens?: number;
     apiMicrocompactTargetInputTokens?: number;
+    apiMicrocompactMaxRequestBytes?: number;
     apiMicrocompactClearToolResults?: boolean;
     apiMicrocompactClearToolUses?: boolean;
+    toolResultArtifactMaxChars?: number;
+    /**
+     * Aggregate budget for all tool_result blocks produced in one iteration
+     * (one user message). Largest results are artifacted to disk until the
+     * batch fits. Mirrors Claude Code's per-message tool result budget.
+     */
+    toolResultsPerMessageMaxChars?: number;
+    /**
+     * In-loop auto-compact: summarize old conversation turns mid-run when the
+     * estimated input tokens approach the model context window. Mirrors
+     * Claude Code's per-iteration autocompact. Defaults to true.
+     */
+    loopAutoCompactEnabled?: boolean;
+    /** Model context window in tokens used to derive the in-loop compact threshold. */
+    contextWindowTokens?: number;
+    /** Explicit in-loop compact trigger in estimated tokens. Overrides the derived threshold. */
+    loopAutoCompactThresholdTokens?: number;
 }
 export type ActoviqWorkspaceKind = 'directory' | 'temp' | 'git-worktree';
 export interface ActoviqWorkspaceInfo {
@@ -531,6 +617,7 @@ export interface AgentRunOptions {
     signal?: AbortSignal;
 }
 export interface SessionCreateOptions {
+    id?: string;
     title?: string;
     systemPrompt?: string;
     model?: string;
@@ -551,6 +638,16 @@ export interface AgentRequestSummary {
     usage?: Usage;
     text: string;
     createdAt: string;
+    requestTokenEstimate?: number;
+    requestByteLength?: number;
+    localMicrocompact?: {
+        enabled: boolean;
+        clearedToolResults: number;
+        tokenEstimateBefore: number;
+        tokenEstimateAfter: number;
+        requestByteLengthBefore?: number;
+        requestByteLengthAfter?: number;
+    };
 }
 export interface AgentToolCallEventPayload {
     id: string;
@@ -577,6 +674,8 @@ export interface AgentRunResult {
     messages: MessageParam[];
     surfacedMemories?: ActoviqSurfacedMemory[];
     stopReason: StopReason | null;
+    incompleteReason?: string;
+    maxToolIterationsExceeded?: boolean;
     hookStopReason?: string;
     usage?: Usage;
     requests: AgentRequestSummary[];
@@ -658,8 +757,12 @@ export interface ActoviqSessionCompactResult {
     state: ActoviqSessionMemoryRuntimeState;
 }
 export interface ActoviqTaskToolInput {
-    description: string;
+    description?: string;
+    prompt?: string;
+    task?: string;
     subagent_type?: string;
+    agent?: string;
+    agent_type?: string;
     run_in_background?: boolean;
 }
 export interface ActoviqTaskToolSyncResult {
@@ -670,6 +773,7 @@ export interface ActoviqTaskToolSyncResult {
     model: string;
     text: string;
     toolCallCount: number;
+    toolErrorCount: number;
 }
 export interface ActoviqTaskToolAsyncResult {
     status: 'async_launched';
@@ -686,6 +790,16 @@ export interface ActoviqDelegatedAgentRecord {
     count: number;
     lastInvokedAt: string;
     lastDescription?: string;
+    lastRunId?: string;
+    lastSessionId?: string;
+    lastStatus?: 'completed' | 'async_launched';
+    lastTaskId?: string;
+    lastTextSummary?: string;
+    runIds?: string[];
+    sessionIds?: string[];
+    taskIds?: string[];
+    totalToolCallCount?: number;
+    totalToolErrorCount?: number;
 }
 export interface ActoviqAgentContinuityState {
     currentAgent?: string;
@@ -710,6 +824,7 @@ export interface ActoviqBackgroundTaskRecord {
     model?: string;
     text?: string;
     toolCallCount?: number;
+    toolErrorCount?: number;
     error?: string;
 }
 export interface ActoviqMailboxMessage {
@@ -812,6 +927,9 @@ export type AgentEvent = {
     type: 'request.started';
     runId: string;
     iteration: number;
+    requestTokenEstimate?: number;
+    requestByteLength?: number;
+    localMicrocompact?: AgentRequestSummary['localMicrocompact'];
     timestamp: string;
 } | {
     type: 'response.text.delta';
@@ -850,6 +968,13 @@ export type AgentEvent = {
     iteration: number;
     result: AgentToolCallRecord;
     timestamp: string;
+} | {
+    type: 'tool.progress';
+    runId: string;
+    iteration: number;
+    toolUseId: string;
+    data: ToolProgressData;
+    timestamp: string;
 } | {
     type: 'session.compacted';
     runId: string;
@@ -857,6 +982,32 @@ export type AgentEvent = {
     trigger: ActoviqCompactTrigger;
     result: ActoviqSessionCompactResult;
     timestamp: string;
+} | {
+    type: 'conversation.compacted';
+    runId: string;
+    iteration: number;
+    tokenEstimateBefore: number;
+    tokenEstimateAfter: number;
+    messagesSummarized: number;
+    preservedMessages: number;
+    clearedToolResults: number;
+    timestamp: string;
+} | {
+    type: 'model.fallback';
+    runId: string;
+    iteration: number;
+    fromModel: string;
+    toModel: string;
+    reason: string;
+    timestamp: string;
+} | {
+    type: 'request.interrupted';
+    runId: string;
+    iteration: number;
+    retry: number;
+    maxRetries: number;
+    reason: string;
+    timestamp: string;
 } | {
     type: 'response.completed';
     runId: string;
@@ -1265,4 +1416,275 @@ export interface HatchActoviqBuddyOptions extends ActoviqBuddyOptions {
 export interface ActoviqBuddyPromptContextOptions extends ActoviqBuddyOptions {
     announcedNames?: string[];
 }
+export interface CronSchedule {
+    /** 5-field cron expression: "minute hour dayOfMonth month dayOfWeek" */
+    cron: string;
+    /** IANA timezone (e.g. "Asia/Shanghai"). Omit for local timezone. */
+    timezone?: string;
+}
+export interface ScheduledTaskDefinition<TOutput = unknown> {
+    id: string;
+    schedule: CronSchedule;
+    task: (context: ScheduledTaskContext) => Promise<TOutput> | TOutput;
+    description?: string;
+    enabled?: boolean;
+    maxRetries?: number;
+    retryDelayMs?: number;
+    timeoutMs?: number;
+}
+export interface ScheduledTaskContext {
+    taskId: string;
+    scheduledAt: string;
+    invocationCount: number;
+    previousResult?: unknown;
+}
+export interface ScheduledTaskRecord {
+    id: string;
+    schedule: string;
+    description?: string;
+    enabled: boolean;
+    lastRunAt?: string;
+    lastResult?: 'success' | 'failure' | 'timeout';
+    lastError?: string;
+    nextRunAt: string;
+    invocationCount: number;
+    createdAt: string;
+}
+export interface ScheduledTaskStore {
+    save(task: ScheduledTaskRecord): Promise<void>;
+    load(id: string): Promise<ScheduledTaskRecord | undefined>;
+    list(): Promise<ScheduledTaskRecord[]>;
+    delete(id: string): Promise<void>;
+}
+export interface TaskSchedulerOptions {
+    tickIntervalMs?: number;
+    store?: ScheduledTaskStore;
+    defaultTimeoutMs?: number;
+    defaultMaxRetries?: number;
+    defaultRetryDelayMs?: number;
+}
+export type ActoviqBridgePermissionMode = 'acceptEdits' | 'bypassPermissions' | 'default' | 'dontAsk' | 'plan';
+export type ActoviqBridgeToolsOption = 'default' | 'none' | string[];
+export interface ActoviqBridgeJsonEvent extends Record<string, unknown> {
+    type: string;
+    subtype?: string;
+    session_id?: string;
+    uuid?: string;
+}
+export interface CreateActoviqBridgeSdkOptions {
+    executable?: string;
+    cliPath?: string;
+    homeDir?: string;
+    workDir?: string;
+    model?: string;
+    fallbackModel?: string;
+    effort?: 'low' | 'medium' | 'high' | 'max';
+    systemPrompt?: string;
+    appendSystemPrompt?: string;
+    permissionMode?: ActoviqBridgePermissionMode;
+    dangerouslySkipPermissions?: boolean;
+    maxTurns?: number;
+    maxBudgetUsd?: number;
+    agent?: string;
+    agents?: Record<string, unknown>;
+    tools?: ActoviqBridgeToolsOption;
+    allowedTools?: string[];
+    disallowedTools?: string[];
+    addDirs?: string[];
+    mcpConfigs?: Array<string | Record<string, unknown>>;
+    strictMcpConfig?: boolean;
+    settings?: string | Record<string, unknown>;
+    settingSources?: string;
+    jsonSchema?: string | Record<string, unknown>;
+    files?: string[];
+    bare?: boolean;
+    disableSlashCommands?: boolean;
+    includePartialMessages?: boolean;
+    includeHookEvents?: boolean;
+    verbose?: boolean;
+    pluginDirs?: string[];
+    env?: Record<string, string>;
+    cliArgs?: string[];
+}
+export interface ActoviqBridgeRunOptions extends CreateActoviqBridgeSdkOptions {
+    sessionId?: string;
+    resume?: string | true;
+    continueMostRecent?: boolean;
+    forkSession?: boolean;
+    name?: string;
+    signal?: AbortSignal;
+}
+export interface ActoviqBridgeSessionCreateOptions extends Omit<ActoviqBridgeRunOptions, 'continueMostRecent' | 'forkSession' | 'name' | 'resume' | 'sessionId' | 'signal'> {
+    sessionId?: string;
+    title?: string;
+}
+export type ActoviqBridgeAgentRunOptions = Omit<ActoviqBridgeRunOptions, 'agent'>;
+export type ActoviqBridgeAgentSessionOptions = Omit<ActoviqBridgeSessionCreateOptions, 'agent'>;
+export type ActoviqBridgeSkillRunOptions = Omit<ActoviqBridgeRunOptions, 'resume' | 'sessionId'>;
+export interface ActoviqBridgeRunResult {
+    text: string;
+    sessionId: string;
+    isError: boolean;
+    subtype?: string;
+    stopReason?: string;
+    durationMs?: number;
+    totalCostUsd?: number;
+    numTurns?: number;
+    exitCode: number | null;
+    stderr: string;
+    initEvent?: ActoviqBridgeJsonEvent;
+    resultEvent: ActoviqBridgeJsonEvent;
+    assistantMessages: ActoviqBridgeJsonEvent[];
+    events: ActoviqBridgeJsonEvent[];
+}
+export interface ActoviqRuntimeMcpServer {
+    name: string;
+    status?: string;
+}
+export interface ActoviqRuntimePluginInfo {
+    name: string;
+    path?: string;
+    source?: string;
+}
+export interface ActoviqRuntimeInfo {
+    sessionId: string;
+    cwd?: string;
+    model?: string;
+    permissionMode?: string;
+    tools: string[];
+    mcpServers: ActoviqRuntimeMcpServer[];
+    slashCommands: string[];
+    agents: string[];
+    skills: string[];
+    plugins: ActoviqRuntimePluginInfo[];
+    rawInitEvent: ActoviqBridgeJsonEvent;
+}
+export interface ActoviqAgentSummary {
+    name: string;
+    sourceGroup: string;
+    active: boolean;
+    rawLine: string;
+    model?: string;
+    memory?: string;
+    shadowedBy?: string;
+}
+export interface ActoviqAgentMetadata extends ActoviqAgentSummary {
+    contextSource?: string;
+    tokens?: string;
+}
+export interface ActoviqToolMetadata {
+    name: string;
+    kind: 'builtin' | 'mcp';
+    server?: string;
+    tokens?: string;
+}
+export interface ActoviqSkillMetadata {
+    name: string;
+    slashCommand: string;
+    source?: string;
+    tokens?: string;
+}
+export interface ActoviqSlashCommandMetadata {
+    name: string;
+    kind: 'builtin' | 'skill';
+    skillName?: string;
+}
+export interface ActoviqRuntimeCatalog {
+    runtime: ActoviqRuntimeInfo;
+    agents: ActoviqAgentMetadata[];
+    tools: ActoviqToolMetadata[];
+    skills: ActoviqSkillMetadata[];
+    slashCommands: ActoviqSlashCommandMetadata[];
+    context?: ActoviqContextUsage;
+}
+export interface ActoviqContextCategory {
+    name: string;
+    tokens: string;
+    percentage: string;
+}
+export interface ActoviqContextSkillUsage {
+    name: string;
+    source?: string;
+    tokens: string;
+}
+export interface ActoviqContextAgentUsage {
+    agentType: string;
+    source?: string;
+    tokens: string;
+}
+export interface ActoviqContextMcpToolUsage {
+    tool: string;
+    server: string;
+    tokens: string;
+}
+export interface ActoviqContextUsage {
+    markdown: string;
+    model?: string;
+    tokensUsed?: string;
+    tokenLimit?: string;
+    percentage?: number;
+    categories: ActoviqContextCategory[];
+    skills: ActoviqContextSkillUsage[];
+    agents: ActoviqContextAgentUsage[];
+    mcpTools: ActoviqContextMcpToolUsage[];
+    rawResult: ActoviqBridgeRunResult;
+}
+export interface ActoviqBridgeCapabilityLookupOptions extends Omit<ActoviqBridgeRunOptions, 'resume' | 'sessionId'> {
+    includeContext?: boolean;
+}
+export type ActoviqCleanBridgeParityStatus = 'exact' | 'mapped' | 'simulated' | 'unsupported';
+export interface ActoviqCleanBridgeParityMatrixEntry {
+    option: keyof ActoviqBridgeRunOptions | keyof CreateActoviqBridgeSdkOptions;
+    status: ActoviqCleanBridgeParityStatus;
+    cleanTarget?: string;
+    notes: string;
+}
+export interface ActoviqCleanBridgeUnsupportedOption {
+    option: string;
+    value: unknown;
+    reason: string;
+}
+export interface ActoviqCleanBridgeCompatibilityReport {
+    mapped: Array<{
+        option: string;
+        cleanTarget: string;
+        status: Exclude<ActoviqCleanBridgeParityStatus, 'unsupported'>;
+        note?: string;
+    }>;
+    unsupported: ActoviqCleanBridgeUnsupportedOption[];
+}
+export type ActoviqCleanBridgeUnsupportedOptionPolicy = 'metadata' | 'warn' | 'throw';
+export interface CreateActoviqCleanBridgeSdkOptions extends CreateAgentSdkOptions {
+    bridgeDefaults?: CreateActoviqBridgeSdkOptions;
+    unsupportedOptionPolicy?: ActoviqCleanBridgeUnsupportedOptionPolicy;
+}
+export type ActoviqBridgeToolProvider = 'runtime' | 'server' | 'mcp' | 'unknown';
+export interface ActoviqBridgeToolRequest {
+    id?: string;
+    name: string;
+    provider: ActoviqBridgeToolProvider;
+    blockType: string;
+    input?: unknown;
+}
+export interface ActoviqBridgeToolResultSummary {
+    toolUseId: string;
+    isError: boolean;
+    blockType: string;
+    content?: unknown;
+}
+export interface ActoviqBridgeTaskInvocation {
+    id?: string;
+    name: string;
+    provider: ActoviqBridgeToolProvider;
+    description?: string;
+    prompt?: string;
+    subagentType?: string;
+    input: Record<string, unknown>;
+}
+export interface ActoviqBridgeEventAnalysis {
+    textDeltas: string[];
+    toolRequests: ActoviqBridgeToolRequest[];
+    toolResults: ActoviqBridgeToolResultSummary[];
+    taskInvocations: ActoviqBridgeTaskInvocation[];
+}
 //# sourceMappingURL=types.d.ts.map