actoviq-agent-sdk 0.3.0 → 0.4.0

package/dist/src/types.d.ts

@@ -24,8 +24,17 @@ export interface ToolExecutionContext {
     modelApi?: ModelApi;
     model?: string;
     provider?: string;
+    effort?: ActoviqEffort;
 }
 export type ActoviqPermissionMode = 'default' | 'acceptEdits' | 'bypassPermissions' | 'plan' | 'auto';
+export type ActoviqModelTier = 'min' | 'medium' | 'max';
+export type ActoviqEffort = 'low' | 'medium' | 'high' | 'max';
+export type ActoviqRunEffort = ActoviqEffort | 'auto';
+export interface ActoviqModelTierConfig {
+    min?: string;
+    medium?: string;
+    max?: string;
+}
 export type ActoviqPermissionBehavior = 'allow' | 'deny' | 'ask';
 export interface ActoviqPermissionRule {
     toolName: string;
@@ -33,6 +42,10 @@ export interface ActoviqPermissionRule {
     matcher?: string;
     source?: string;
 }
+export interface ActoviqSessionPermissionState {
+    mode?: ActoviqPermissionMode;
+    permissions: ActoviqPermissionRule[];
+}
 export interface ActoviqPermissionDecision {
     toolName: string;
     publicName: string;
@@ -211,6 +224,7 @@ export interface ModelRequest {
     context_management?: Record<string, unknown>;
     stop_sequences?: string[];
     extra_tool_schemas?: Record<string, unknown>[];
+    effort?: ActoviqEffort;
     signal?: AbortSignal;
 }
 export interface ModelStreamHandle extends AsyncIterable<MessageStreamEvent> {
@@ -237,6 +251,8 @@ export interface ResolvedToolAdapter {
     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;
@@ -250,6 +266,8 @@ export interface ResolvedRuntimeConfig {
     authToken?: string;
     baseURL?: string;
     model: string;
+    modelTier?: ActoviqModelTier;
+    modelTiers: ActoviqModelTierConfig;
     maxTokens: number;
     temperature?: number;
     timeoutMs: number;
@@ -259,11 +277,17 @@ 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;
     provider: 'anthropic' | 'openai';
+    effort?: ActoviqEffort;
 }
 export interface ActoviqSessionStartHookContext {
     runId: string;
@@ -338,21 +362,52 @@ export interface ActoviqAgentDefinition {
     description: string;
     systemPrompt?: string;
     model?: string;
+    effort?: ActoviqRunEffort;
+    permissionMode?: ActoviqPermissionMode;
+    maxToolIterations?: number;
+    maxTurns?: number;
     metadata?: Record<string, unknown>;
     hooks?: ActoviqHooks;
     tools?: AgentToolDefinition[];
+    allowedTools?: string[];
+    disallowedTools?: string[];
+    allowedAgents?: string[];
+    skills?: string[];
     mcpServers?: AgentMcpServerDefinition[];
+    requiredMcpServers?: string[];
     inheritDefaultTools?: boolean;
     inheritDefaultMcpServers?: boolean;
+    initialPrompt?: string;
+    memory?: 'user' | 'project' | 'local';
+    background?: boolean;
+    isolation?: 'worktree';
+    cwd?: string;
+    allowNestedAgents?: boolean;
+    source?: 'built-in' | 'user' | 'project' | 'custom';
+    sourcePath?: string;
 }
 export interface ActoviqAgentDefinitionSummary {
     name: string;
     description: string;
     model?: string;
+    effort?: ActoviqRunEffort;
+    permissionMode?: ActoviqPermissionMode;
+    maxToolIterations?: number;
+    maxTurns?: number;
     toolNames: string[];
+    allowedTools: string[];
+    disallowedTools: string[];
+    allowedAgents: string[];
+    skills: string[];
     mcpServerNames: string[];
+    requiredMcpServers: string[];
     inheritDefaultTools: boolean;
     inheritDefaultMcpServers: boolean;
+    background: boolean;
+    isolation?: 'worktree';
+    memory?: 'user' | 'project' | 'local';
+    source?: 'built-in' | 'user' | 'project' | 'custom';
+    sourcePath?: string;
     metadataKeys: string[];
     hasSystemPrompt: boolean;
     hasHooks: boolean;
@@ -492,6 +547,7 @@ export interface CreateAgentSdkOptions {
     apiKey?: string;
     authToken?: string;
     baseURL?: string;
+    /** A full model ID or one of the configured min/medium/max tiers. */
     model?: string;
     maxTokens?: number;
     temperature?: number;
@@ -502,12 +558,20 @@ 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[];
+    agentDirectories?: string[];
+    loadDefaultAgentDirectories?: boolean;
+    disableDefaultAgents?: boolean;
+    maxSubagentDepth?: number;
+    maxSubagentFanout?: number;
     skills?: ActoviqSkillDefinition[];
     skillDirectories?: string[];
     disableDefaultSkills?: boolean;
@@ -520,6 +584,7 @@ export interface CreateAgentSdkOptions {
     approver?: ActoviqToolApprover;
     computerUse?: boolean | CreateActoviqComputerUseOptions;
     provider?: 'anthropic' | 'openai';
+    effort?: ActoviqEffort;
     modelApi?: ModelApi;
     sessionManager?: SessionManagerConfig;
 }
@@ -534,8 +599,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 {
@@ -577,6 +660,7 @@ export interface AgentRunOptions {
     toolChoice?: ToolChoice;
     userId?: string;
     metadata?: Record<string, unknown>;
+    effort?: ActoviqRunEffort;
     hooks?: ActoviqHooks;
     permissionMode?: ActoviqPermissionMode;
     permissions?: ActoviqPermissionRule[];
@@ -584,11 +668,22 @@ export interface AgentRunOptions {
     approver?: ActoviqToolApprover;
     canUseTool?: ActoviqCanUseTool;
     signal?: AbortSignal;
+    /**
+     * Mid-run steering: called between tool iterations to collect user messages
+     * queued while the agent was working. Drained texts are appended to the
+     * next tool-result user message so the model sees them on its next request.
+     */
+    drainQueuedInputs?: () => string[];
+    /** Override the runtime working directory for this run. */
+    workDir?: string;
 }
 export interface SessionCreateOptions {
+    id?: string;
     title?: string;
     systemPrompt?: string;
     model?: string;
+    permissionMode?: ActoviqPermissionMode;
+    permissions?: ActoviqPermissionRule[];
     tags?: string[];
     metadata?: Record<string, unknown>;
     initialMessages?: MessageParam[];
@@ -598,6 +693,17 @@ export interface SessionForkOptions {
     tags?: string[];
     metadata?: Record<string, unknown>;
 }
+export interface SessionResumeOptions {
+    /** Resume into a new session while preserving the source transcript and runtime state. */
+    fork?: boolean;
+    title?: string;
+    tags?: string[];
+    metadata?: Record<string, unknown>;
+    /** A full model ID or configured min/medium/max tier. */
+    model?: string;
+    permissionMode?: ActoviqPermissionMode;
+    permissions?: ActoviqPermissionRule[];
+}
 export interface AgentRequestSummary {
     iteration: number;
     messageId: string;
@@ -606,6 +712,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;
@@ -632,6 +748,8 @@ export interface AgentRunResult {
     messages: MessageParam[];
     surfacedMemories?: ActoviqSurfacedMemory[];
     stopReason: StopReason | null;
+    incompleteReason?: string;
+    maxToolIterationsExceeded?: boolean;
     hookStopReason?: string;
     usage?: Usage;
     requests: AgentRequestSummary[];
@@ -642,8 +760,20 @@ export interface AgentRunResult {
     delegatedAgents?: ActoviqDelegatedAgentRecord[];
     invokedSkills?: ActoviqInvokedSkillRecord[];
     reactiveCompact?: ActoviqSessionCompactResult;
+    /** Mid-run conversation compactions performed inside the tool loop. */
+    loopCompactions?: AgentLoopCompactionRecord[];
     permissionDecisions?: ActoviqPermissionDecision[];
 }
+export interface AgentLoopCompactionRecord {
+    trigger: 'auto' | 'reactive';
+    iteration: number;
+    tokenEstimateBefore: number;
+    tokenEstimateAfter: number;
+    messagesSummarized: number;
+    preservedMessages: number;
+    clearedToolResults: number;
+    summary?: string;
+}
 export interface ActoviqDreamConfig {
     minHours: number;
     minSessions: number;
@@ -703,37 +833,54 @@ export interface AgentSessionCompactOptions {
 export interface ActoviqSessionCompactResult {
     compacted: boolean;
     trigger: ActoviqCompactTrigger;
-    reason: 'disabled' | 'threshold_not_met' | 'no_messages' | 'microcompact' | 'compacted' | 'circuit_breaker_open';
+    reason: 'disabled' | 'threshold_not_met' | 'no_messages' | 'microcompact' | 'compacted' | 'failed' | 'circuit_breaker_open';
     tokenEstimateBefore: number;
     tokenEstimateAfter?: number;
     summaryMessage?: string;
     messagesRemoved?: number;
     compactCount: number;
     microcompactCount: number;
+    consecutiveFailures?: number;
+    error?: string;
     state: ActoviqSessionMemoryRuntimeState;
 }
 export interface ActoviqTaskToolInput {
-    description: string;
+    description?: string;
+    prompt?: string;
+    task?: string;
     subagent_type?: string;
+    agent?: string;
+    agent_type?: string;
+    model?: string;
     run_in_background?: boolean;
+    name?: string;
+    isolation?: 'worktree';
+    cwd?: string;
 }
 export interface ActoviqTaskToolSyncResult {
     status: 'completed';
     subagentType: string;
     runId: string;
     sessionId?: string;
+    agentId?: string;
     model: string;
     text: string;
     toolCallCount: number;
+    toolErrorCount: number;
+    worktreePath?: string;
+    worktreeBranch?: string;
 }
 export interface ActoviqTaskToolAsyncResult {
     status: 'async_launched';
     taskId: string;
     subagentType: string;
     sessionId?: string;
+    agentId?: string;
     outputFile: string;
     canReadOutputFile: boolean;
     description: string;
+    worktreePath?: string;
+    worktreeBranch?: string;
 }
 export type ActoviqTaskToolResult = ActoviqTaskToolSyncResult | ActoviqTaskToolAsyncResult;
 export interface ActoviqDelegatedAgentRecord {
@@ -741,6 +888,17 @@ export interface ActoviqDelegatedAgentRecord {
     count: number;
     lastInvokedAt: string;
     lastDescription?: string;
+    lastRunId?: string;
+    lastSessionId?: string;
+    lastStatus?: 'completed' | 'async_launched' | 'failed' | 'cancelled';
+    lastTaskId?: string;
+    lastTextSummary?: string;
+    runIds?: string[];
+    sessionIds?: string[];
+    taskIds?: string[];
+    totalRequestCount?: number;
+    totalToolCallCount?: number;
+    totalToolErrorCount?: number;
 }
 export interface ActoviqAgentContinuityState {
     currentAgent?: string;
@@ -760,11 +918,24 @@ export interface ActoviqBackgroundTaskRecord {
     completedAt?: string;
     parentRunId?: string;
     parentSessionId?: string;
+    agentName?: string;
     sessionId?: string;
     runId?: string;
     model?: string;
     text?: string;
+    partialText?: string;
     toolCallCount?: number;
+    toolErrorCount?: number;
+    requestCount?: number;
+    currentIteration?: number;
+    currentToolName?: string;
+    progressSummary?: string;
+    queuedMessageCount?: number;
+    resumedFromTaskId?: string;
+    notificationDeliveredAt?: string;
+    worktreePath?: string;
+    worktreeBranch?: string;
+    retainedWorktree?: boolean;
     error?: string;
 }
 export interface ActoviqMailboxMessage {
@@ -867,6 +1038,9 @@ export type AgentEvent = {
     type: 'request.started';
     runId: string;
     iteration: number;
+    requestTokenEstimate?: number;
+    requestByteLength?: number;
+    localMicrocompact?: AgentRequestSummary['localMicrocompact'];
     timestamp: string;
 } | {
     type: 'response.text.delta';
@@ -919,6 +1093,34 @@ export type AgentEvent = {
     trigger: ActoviqCompactTrigger;
     result: ActoviqSessionCompactResult;
     timestamp: string;
+} | {
+    type: 'conversation.compacted';
+    runId: string;
+    iteration: number;
+    /** 'auto' = proactive threshold compact; 'reactive' = provider rejected the request as too long. */
+    trigger?: 'auto' | 'reactive';
+    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;
@@ -1191,6 +1393,9 @@ export interface ActoviqCompactState extends ActoviqMemoryState {
     latestBoundary?: ActoviqTranscriptBoundary;
     compactCount: number;
     microcompactCount: number;
+    consecutiveCompactFailures?: number;
+    lastCompactFailureAt?: string;
+    lastCompactError?: string;
     hasCompacted: boolean;
     pendingPostCompaction?: boolean;
     lastSummarizedMessageUuid?: string;
@@ -1543,6 +1748,32 @@ export interface ActoviqContextUsage {
 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;