qlogicagent 0.5.0 → 0.5.3

package/dist/types/orchestration/task-types.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Task Type Taxonomy — CC-aligned sub-agent task state system.
+ *
+ * CC defines 7 task types for sub-agent dispatch. Each type has different:
+ *   - Execution model (in-process, subprocess, remote)
+ *   - Isolation level (shared, worktree, container)
+ *   - Permission handling (interactive, coordinator, worker)
+ *   - Tool access (full, restricted, read-only)
+ *
+ * Reference: claude-code src/tasks/types.ts
+ */
+/**
+ * The 7 task types from CC's sub-agent architecture.
+ *
+ * - local_bash: Subprocess shell execution (bash/powershell)
+ * - local_agent: Background forked Node process with its own tool loop
+ * - remote_agent: Cloud environment (polling-based, e.g., CCR sandbox)
+ * - in_process_teammate: Same process, AsyncLocalStorage-isolated agent
+ * - local_workflow: DAG/pipeline execution (planned)
+ * - monitor_mcp: MCP server monitoring agent (planned)
+ * - dream: Background memory consolidation agent
+ */
+export type TaskType = "local_bash" | "local_agent" | "remote_agent" | "in_process_teammate" | "local_workflow" | "monitor_mcp" | "dream";
+/**
+ * How a sub-agent is isolated from the parent execution.
+ *
+ * - shared: Same working directory, same filesystem (default fork)
+ * - worktree: Git worktree checkout — separate branch, merges back
+ * - container: Container sandbox (docker/remote)
+ */
+export type IsolationMode = "shared" | "worktree" | "container";
+/**
+ * Permission context for sub-agent execution.
+ * Determines which PermissionChecker variant is used.
+ *
+ * CC reference: 3 permission handler variants
+ * - interactive: User-facing agent, prompts for approval
+ * - coordinator: Orchestrator agent, auto-approves most non-destructive ops
+ * - worker: Headless worker, classifier-only (no user prompts)
+ */
+export type PermissionRole = "interactive" | "coordinator" | "worker";
+/** Common state fields shared by all task types. */
+export interface TaskStateBase {
+    /** Unique task ID. */
+    taskId: string;
+    /** Task type discriminant. */
+    type: TaskType;
+    /** Human-readable label. */
+    label: string;
+    /** The permission role for this task's agent. */
+    permissionRole: PermissionRole;
+    /** Isolation mode. */
+    isolation: IsolationMode;
+    /** Current lifecycle state. */
+    lifecycle: TaskLifecycle;
+    /** Parent task ID (for nested sub-agents). */
+    parentTaskId?: string;
+    /** Execution depth (0 = root). */
+    depth: number;
+    /** Maximum turns before forced stop. */
+    maxTurns: number;
+    /** Token budget for this task. */
+    tokenBudget: number;
+    /** Start timestamp (ms). */
+    startedAt: number;
+    /** End timestamp (ms), set when completed/failed. */
+    endedAt?: number;
+}
+export type TaskLifecycle = "pending" | "running" | "completed" | "failed" | "cancelled" | "timeout";
+/** Local bash task — subprocess shell execution. */
+export interface LocalBashTaskState extends TaskStateBase {
+    type: "local_bash";
+    command: string;
+    cwd: string;
+    pid?: number;
+}
+/** Local agent task — forked agent with its own tool loop. */
+export interface LocalAgentTaskState extends TaskStateBase {
+    type: "local_agent";
+    agentName: string;
+    systemPrompt: string;
+    /** Restricted tool set (empty = inherit parent). */
+    allowedTools: string[];
+    /** Worktree branch name (if isolation === "worktree"). */
+    worktreeBranch?: string;
+}
+/** Remote agent task — cloud sandbox execution. */
+export interface RemoteAgentTaskState extends TaskStateBase {
+    type: "remote_agent";
+    /** Remote session/environment ID. */
+    remoteSessionId: string;
+    /** Polling endpoint for status checks. */
+    pollEndpoint?: string;
+}
+/** In-process teammate — AsyncLocalStorage-isolated, same process. */
+export interface InProcessTeammateTaskState extends TaskStateBase {
+    type: "in_process_teammate";
+    teamName: string;
+    agentName: string;
+    /** Teammate's independent permission mode. */
+    permissionMode: string;
+    /** Async mailbox for coordinator ↔ worker communication. */
+    mailboxId?: string;
+}
+/** A single dream agent turn — text output + tool use count. */
+export interface DreamTurn {
+    text: string;
+    toolUseCount: number;
+}
+/** Dream phase lifecycle — CC alignment. */
+export type DreamPhase = "starting" | "updating" | "completed" | "failed";
+/** Dream task — background memory consolidation agent (CC autoDream parity). */
+export interface DreamTaskState extends TaskStateBase {
+    type: "dream";
+    sessionId: string;
+    /** Current dream phase. */
+    phase: DreamPhase;
+    /** Number of sessions being reviewed. */
+    sessionsReviewing: number;
+    /** Memory files touched by the dream agent. */
+    filesTouched: string[];
+    /** Dream agent turn history (capped). */
+    turns: DreamTurn[];
+    /** Stashed lock mtime for rollback on failure. */
+    priorLockMtime: number;
+}
+/** Placeholder for planned task types. */
+export interface PlannedTaskState extends TaskStateBase {
+    type: "local_workflow" | "monitor_mcp";
+}
+/** Union of all concrete task states. */
+export type TaskState = LocalBashTaskState | LocalAgentTaskState | RemoteAgentTaskState | InProcessTeammateTaskState | DreamTaskState | PlannedTaskState;
+/**
+ * Filter available tools by permission role.
+ *
+ * @param role - The agent's permission role
+ * @param availableTools - Full set of tool names
+ * @returns Filtered tool names appropriate for the role
+ */
+export declare function filterToolsByRole(role: PermissionRole, availableTools: string[]): string[];
+/** Create a new task state with defaults populated. */
+export declare function createTaskState(overrides: Pick<TaskStateBase, "taskId" | "type" | "label"> & Partial<TaskStateBase>): TaskStateBase;

package/dist/types/orchestration/team-orchestration.d.ts

@@ -0,0 +1,195 @@
+/**
+ * Team Orchestration Strategy — multi-agent coordination layer.
+ *
+ * Extends the existing sidechain foundation with team/swarm semantics:
+ * - Parallel agent spawning (multiple sidechains at once)
+ * - Role-based agent assignment (planner / executor / reviewer)
+ * - Shared knowledge pool via merge policies
+ * - Budget-aware concurrency limits
+ * - Lifecycle state machine for team coordination
+ *
+ * Architecture:
+ *   Gateway ─── Hub ─── orchestration (this module, pure strategy)
+ *                │
+ *   ┌───────────┼───────────┐
+ *   │   TeamCoordinator     │  ← Hub runtime (multi-sidechain-coordinator.ts)
+ *   │   │                   │
+ *   │   ├── Agent #1 (planner)
+ *   │   ├── Agent #2 (executor)
+ *   │   └── Agent #3 (reviewer)
+ *   └───────────────────────┘
+ *
+ * This module provides:
+ * 1. Type definitions (TeamPlan, AgentRole, TeamLifecycle)
+ * 2. Pure strategy functions (plan resolution, role assignment, budget allocation)
+ * 3. Merge/aggregation policies (how agent results combine)
+ *
+ * Hub consumes these types and strategy functions in its coordinator runtime.
+ * Gateway consumes TeamPlan to spawn/manage multiple sidechain executions.
+ */
+import type { SidechainType, SidechainMergePolicy, SidechainBudgetTier, SidechainToolAccessMode } from "./index.js";
+/** Roles an agent can take within a team execution. */
+export type AgentRole = "planner" | "executor" | "reviewer" | "researcher" | "custom";
+/** Execution mode for a team. */
+export type TeamExecutionMode = "parallel" | "sequential" | "pipeline" | "adaptive";
+/** How team results are aggregated into the parent execution. */
+export type TeamAggregationPolicy = "first-success" | "majority-vote" | "merge-all" | "reviewer-gate" | "planner-sync";
+/** Current lifecycle state of a team execution. */
+export type TeamLifecycleState = "planning" | "spawning" | "executing" | "aggregating" | "reviewing" | "completed" | "failed" | "cancelled";
+/** Specification for a single agent within a team. */
+export interface TeamAgentSpec {
+    /** Unique ID within the team (e.g., "agent-1", "researcher-a"). */
+    agentId: string;
+    /** Role this agent plays. */
+    role: AgentRole;
+    /** Human-readable label for tracing. */
+    label: string;
+    /** The sidechain type this agent maps to. */
+    sidechainType: SidechainType;
+    /** Task description / system prompt override for this agent. */
+    taskDescription: string;
+    /** Tool access mode for this agent's sidechain. */
+    toolAccessMode: SidechainToolAccessMode;
+    /** Budget tier for this agent. */
+    budgetTier: SidechainBudgetTier;
+    /** Which agents this one depends on (for sequential/pipeline modes). */
+    dependsOn: string[];
+    /** Maximum tokens this agent can consume. */
+    maxTokenBudget: number;
+    /** Maximum tool calls this agent can make. */
+    maxToolCalls: number;
+    /** Timeout in milliseconds (0 = inherit from team). */
+    timeoutMs: number;
+}
+/** A complete team execution plan. */
+export interface TeamPlan {
+    /** Unique team execution ID. */
+    teamId: string;
+    /** Execution mode for this team. */
+    mode: TeamExecutionMode;
+    /** How results from all agents are aggregated. */
+    aggregationPolicy: TeamAggregationPolicy;
+    /** All agent specs in this team. */
+    agents: TeamAgentSpec[];
+    /** Maximum concurrent agent executions (0 = unlimited). */
+    maxConcurrency: number;
+    /** Team-level timeout in ms (0 = no timeout). */
+    timeoutMs: number;
+    /** Total token budget across all agents. */
+    totalTokenBudget: number;
+    /** Whether early termination is allowed when one agent fails. */
+    failFast: boolean;
+    /** Shared context provided to all agents. */
+    sharedContext: string;
+    /** Merge policy for the final team output back to parent. */
+    mergePolicy: SidechainMergePolicy;
+}
+/** Result from a single agent within a team. */
+export interface TeamAgentResult {
+    agentId: string;
+    role: AgentRole;
+    status: "completed" | "failed" | "cancelled" | "timeout";
+    output: string;
+    tokenUsage: {
+        prompt: number;
+        completion: number;
+    };
+    toolCallCount: number;
+    durationMs: number;
+    error?: string;
+}
+/** Aggregated result from team execution. */
+export interface TeamResult {
+    teamId: string;
+    state: TeamLifecycleState;
+    agentResults: TeamAgentResult[];
+    aggregatedOutput: string;
+    totalTokenUsage: {
+        prompt: number;
+        completion: number;
+    };
+    totalDurationMs: number;
+}
+/** Maximum agents allowed in a team (safety bound). */
+export declare const TEAM_MAX_AGENTS = 8;
+/** Maximum recursion depth (teams spawning teams). */
+export declare const TEAM_MAX_DEPTH = 2;
+/**
+ * Resolve a team plan from a high-level task decomposition.
+ *
+ * This is the main entry point: given a set of subtasks and constraints,
+ * produce a concrete TeamPlan that the coordinator can execute.
+ */
+export declare function resolveTeamPlan(params: {
+    teamId: string;
+    subtasks: Array<{
+        id: string;
+        role: AgentRole;
+        label: string;
+        task: string;
+        dependsOn?: string[];
+    }>;
+    mode?: TeamExecutionMode;
+    aggregationPolicy?: TeamAggregationPolicy;
+    totalTokenBudget?: number;
+    timeoutMs?: number;
+    failFast?: boolean;
+    sharedContext?: string;
+    mergePolicy?: SidechainMergePolicy;
+}): TeamPlan;
+/**
+ * Map agent role to sidechain type for existing Hub plumbing compatibility.
+ */
+export declare function mapRoleToSidechainType(role: AgentRole): SidechainType;
+/**
+ * Resolve tool access mode for a given role.
+ */
+export declare function resolveAgentToolAccess(role: AgentRole): SidechainToolAccessMode;
+/**
+ * Allocate token budgets proportionally by role weight.
+ */
+export declare function allocateTokenBudgets(agents: TeamAgentSpec[], totalBudget: number): TeamAgentSpec[];
+/**
+ * Infer execution mode from agent dependency graph.
+ */
+export declare function inferExecutionMode(agents: TeamAgentSpec[]): TeamExecutionMode;
+/**
+ * Infer aggregation policy from mode and agent composition.
+ */
+export declare function inferAggregationPolicy(mode: TeamExecutionMode, agents: TeamAgentSpec[]): TeamAggregationPolicy;
+/**
+ * Determine the execution order for agents given their dependency graph.
+ * Returns groups of agent IDs that can execute concurrently.
+ *
+ * Example: [[planner], [executor-a, executor-b], [reviewer]]
+ */
+export declare function resolveExecutionOrder(agents: TeamAgentSpec[]): string[][];
+/**
+ * Aggregate team results into a single output string.
+ */
+export declare function aggregateTeamResults(results: TeamAgentResult[], policy: TeamAggregationPolicy): string;
+/**
+ * Validate a team plan before execution.
+ * Returns a list of issues (empty = valid).
+ */
+export declare function validateTeamPlan(plan: TeamPlan): string[];
+/**
+ * Determine if a team execution should be cancelled early based on current state.
+ */
+export declare function shouldCancelTeam(params: {
+    plan: TeamPlan;
+    results: TeamAgentResult[];
+    elapsedMs: number;
+}): {
+    cancel: boolean;
+    reason: string;
+};
+/**
+ * Build the task prompt for a specific agent, incorporating shared context
+ * and outputs from dependency agents.
+ */
+export declare function buildAgentTaskPrompt(params: {
+    agent: TeamAgentSpec;
+    plan: TeamPlan;
+    dependencyResults: TeamAgentResult[];
+}): string;

package/dist/types/orchestration/team-tool-loop-wiring.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Team Tool Loop Wiring — Connects team orchestration to the tool loop.
+ *
+ * When the LLM invokes `team_create`, this module:
+ * 1. Validates the team plan
+ * 2. Maps team agents to fork contexts
+ * 3. Coordinates execution according to the team execution mode
+ * 4. Aggregates results according to the aggregation policy
+ * 5. Returns the aggregated result as a tool_result
+ *
+ * This bridges the gap between the pure strategy layer (team-orchestration.ts)
+ * and the Hub's tool loop.
+ */
+import type { AgentRole, TeamExecutionMode, TeamAggregationPolicy, TeamLifecycleState } from "./team-orchestration.js";
+import type { AgentDefinition } from "./agent-registry.js";
+import type { ForkResult } from "./fork-subagent.js";
+export interface TeamToolRequest {
+    /** Team name for identification. */
+    name: string;
+    /** Agent specs for the team. */
+    agents: TeamAgentRequest[];
+    /** Execution mode. */
+    mode: TeamExecutionMode;
+    /** How to aggregate results. */
+    aggregation: TeamAggregationPolicy;
+}
+export interface TeamAgentRequest {
+    /** Role within the team. */
+    role: AgentRole;
+    /** Agent type from built-in registry. */
+    agentType: string;
+    /** Task prompt for this agent. */
+    prompt: string;
+    /** Max turns override. */
+    maxTurns?: number;
+    /** Dependencies (agent IDs that must complete before this one). */
+    dependsOn?: string[];
+}
+export interface TeamExecutionPlan {
+    /** Ordered batches for execution. */
+    batches: TeamExecutionBatch[];
+    /** Total estimated token budget. */
+    totalBudget: number;
+    /** Lifecycle state. */
+    state: TeamLifecycleState;
+}
+export interface TeamExecutionBatch {
+    /** Agents in this batch (run in parallel within a batch). */
+    agents: TeamAgentRequest[];
+    /** Batch mode (parallel or sequential within the batch). */
+    mode: "parallel" | "serial";
+}
+/**
+ * Resolve the execution plan for a team request.
+ * Validates the request, resolves dependencies into ordered batches,
+ * and determines the execution topology.
+ */
+export declare function resolveTeamExecutionPlan(request: TeamToolRequest): TeamExecutionPlan;
+export interface TeamAggregatedResult {
+    /** Whether the team execution succeeded overall. */
+    ok: boolean;
+    /** Aggregated output text. */
+    output: string;
+    /** Individual agent results. */
+    agentResults: Array<{
+        agentId: string;
+        role: AgentRole;
+        result: ForkResult;
+    }>;
+    /** Total tokens consumed by all agents. */
+    totalTokensUsed: number;
+    /** Lifecycle state after aggregation. */
+    finalState: TeamLifecycleState;
+}
+/**
+ * Aggregate results from team agents according to the aggregation policy.
+ */
+export declare function aggregateTeamToolResults(results: Array<{
+    agentId: string;
+    role: AgentRole;
+    result: ForkResult;
+}>, policy: TeamAggregationPolicy): TeamAggregatedResult;
+/**
+ * Map a team tool_call into the format needed for the tool loop to dispatch.
+ * Returns the list of fork configs the tool loop should execute.
+ */
+export declare function mapTeamRequestToForkConfigs(request: TeamToolRequest, agentRegistry: (name: string) => AgentDefinition | undefined): Array<{
+    agentDef: AgentDefinition;
+    prompt: string;
+    maxTurns?: number;
+    role: AgentRole;
+}>;

package/dist/types/orchestration/tool-choice-policy.d.ts

@@ -0,0 +1,54 @@
+import type { RuntimeToolEligibilityContract } from "qlogicagent-runtime-contracts";
+export type ToolChoiceLike = "auto" | "none" | "required" | {
+    type: "function";
+    function?: {
+        name?: string;
+    };
+} | Record<string, unknown> | undefined;
+export interface ToolChoiceToolLike {
+    type?: string;
+    function?: {
+        name?: string;
+        description?: string;
+        parameters?: Record<string, unknown>;
+    };
+    name?: string;
+    description?: string;
+    requiresApproval?: boolean;
+}
+export type ToolEligibilityLike = RuntimeToolEligibilityContract;
+export interface ToolChoiceCompatibilityPolicy {
+    allowNamedToolChoice?: boolean;
+    allowRequiredToolChoice?: boolean;
+    requiredFallback?: "required" | "auto" | "none";
+    namedFallback?: "required" | "auto" | "none";
+    requireAutoWhenThinking?: boolean;
+}
+export interface ApplyToolChoicePolicyInput<TTool extends ToolChoiceToolLike> {
+    tools: readonly TTool[];
+    toolChoice: ToolChoiceLike;
+    eligibility?: readonly ToolEligibilityLike[];
+    thinkingEnabled?: boolean;
+    compatibility?: ToolChoiceCompatibilityPolicy;
+}
+export interface ApplyToolChoicePolicyResult<TTool extends ToolChoiceToolLike> {
+    tools: TTool[];
+    normalizedToolChoice?: ToolChoiceLike;
+    extraSystemPrompt?: string;
+    warnings: string[];
+}
+export declare function filterEligibleTools<TTool extends ToolChoiceToolLike>(params: {
+    tools: readonly TTool[];
+    eligibility?: readonly ToolEligibilityLike[];
+}): TTool[];
+export declare function normalizeAnthropicFunctionToolDefinition(tool: unknown): Record<string, unknown> | undefined;
+export declare function normalizeAnthropicToolChoice(toolChoice: unknown): unknown;
+export declare function applyToolChoiceCompatibility(params: {
+    toolChoice: ToolChoiceLike;
+    thinkingEnabled?: boolean;
+    compatibility?: ToolChoiceCompatibilityPolicy;
+}): {
+    normalizedToolChoice?: ToolChoiceLike;
+    warnings: string[];
+};
+export declare function applyToolChoicePolicy<TTool extends ToolChoiceToolLike>(params: ApplyToolChoicePolicyInput<TTool>): ApplyToolChoicePolicyResult<TTool>;

package/dist/types/orchestration/tool-loop-state.d.ts

@@ -0,0 +1,50 @@
+import { type ConversationRepairOptions, type OpenAiChatMessageLike, type OpenAiResponsesItemLike } from "./conversation-repair.js";
+export interface ToolLoopState<TMessage = unknown> {
+    round: number;
+    maxRounds: number;
+    pendingToolCallIds: string[];
+    completedToolCallIds: string[];
+    lastStopReason?: string;
+    replayMessages: TMessage[];
+}
+export interface ToolLoopRepairAction {
+    kind: "strip-forced-stop-tool-metadata" | "inject-placeholder-tool-result" | "drop-orphan-tool-result" | "rewrite-openai-function-call-pair" | "drop-trailing-reasoning";
+    detail?: string;
+}
+export interface RepairToolLoopStateResult<TMessage> {
+    state: ToolLoopState<TMessage>;
+    recoveryActions: ToolLoopRepairAction[];
+}
+export declare function createToolLoopState<TMessage>(params: {
+    maxRounds: number;
+    replayMessages?: readonly TMessage[];
+    round?: number;
+    pendingToolCallIds?: readonly string[];
+    completedToolCallIds?: readonly string[];
+    lastStopReason?: string;
+}): ToolLoopState<TMessage>;
+export declare function advanceToolLoopState<TMessage>(state: ToolLoopState<TMessage>, params: {
+    replayMessages?: readonly TMessage[];
+    pendingToolCallIds?: readonly string[];
+    completedToolCallIds?: readonly string[];
+    lastStopReason?: string;
+}): ToolLoopState<TMessage>;
+export declare function settleToolLoopState<TMessage>(state: ToolLoopState<TMessage>, params: {
+    replayMessages?: readonly TMessage[];
+    completedToolCallIds?: readonly string[];
+    lastStopReason?: string;
+}): ToolLoopState<TMessage>;
+export declare function recoverToolLoopStateFromChatConversation<TMessage extends OpenAiChatMessageLike>(params: {
+    maxRounds: number;
+    replayMessages: readonly TMessage[];
+    round?: number;
+    lastStopReason?: string;
+    options?: ConversationRepairOptions;
+}): RepairToolLoopStateResult<TMessage>;
+export declare function recoverToolLoopStateFromResponsesItems<TItem extends OpenAiResponsesItemLike>(params: {
+    maxRounds: number;
+    replayItems: readonly TItem[];
+    round?: number;
+    lastStopReason?: string;
+    options?: ConversationRepairOptions;
+}): RepairToolLoopStateResult<TItem>;

package/dist/types/orchestration/tool-schema.d.ts

@@ -0,0 +1,39 @@
+import type { OpenAiToolCall } from "./conversation-repair.js";
+export type ToolSchemaProvider = {
+    modelProvider?: string;
+    modelId?: string;
+};
+export interface FunctionToolSource {
+    name: string;
+    description?: string;
+    parameters?: Record<string, unknown>;
+}
+export interface FunctionToolDefinition {
+    type: "function";
+    function: {
+        name: string;
+        description?: string;
+        parameters: Record<string, unknown>;
+    };
+}
+export interface CapabilityToolManifestLike {
+    name: string;
+    description?: string;
+    requiredParameters?: string[];
+}
+export declare function isXaiProvider(modelProvider?: string, modelId?: string): boolean;
+export declare function normalizeFunctionToolParameters(parameters: Record<string, unknown> | undefined, options?: ToolSchemaProvider): Record<string, unknown>;
+export declare function convertFunctionTools(tools: readonly FunctionToolSource[], options?: ToolSchemaProvider): FunctionToolDefinition[];
+export declare function convertCapabilityToolManifestsToFunctionTools(tools: readonly CapabilityToolManifestLike[]): FunctionToolDefinition[];
+export declare function normalizeMessageTextContent(content: unknown): string;
+export declare function parseOpenAiToolCallsFromChatResponse(responseBody: string): {
+    toolCalls: OpenAiToolCall[];
+    responseText: string;
+};
+export declare function buildAssistantToolCallMessage(toolCalls: OpenAiToolCall[]): Record<string, unknown>;
+export declare function buildToolResultMessage(callId: string, result: {
+    ok: boolean;
+    payload?: unknown;
+    error?: string;
+}): Record<string, unknown>;
+export declare function cleanToolSchemaForGemini(schema: Record<string, unknown>): unknown;

package/dist/types/orchestration/turn-loop-guard.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Turn Loop Guard — Abort signal + token budget warning for preventive termination.
+ *
+ * Aligned with Claude Code's multi-condition termination:
+ * 1. AbortSignal from user cancellation
+ * 2. Token budget pre-check (don't send API call if over budget)
+ * 3. max_output_tokens escalation on truncation
+ * 4. Prompt-too-long reactive compact trigger
+ */
+export interface TurnLoopGuardConfig {
+    /** Context window size in tokens. */
+    contextWindowTokens: number;
+    /** Buffer reserved for response (default: 13000). */
+    responseBufferTokens: number;
+    /** Max output tokens for current model. */
+    maxOutputTokens: number;
+    /** Abort signal for user cancellation. */
+    abortSignal?: AbortSignal;
+    /** Whether reactive compact is available. */
+    reactiveCompactEnabled: boolean;
+    /** Whether max_output_tokens escalation is allowed. */
+    outputEscalationEnabled: boolean;
+}
+export type TokenWarningState = {
+    level: "ok";
+} | {
+    level: "warning";
+    usagePercent: number;
+    remainingTokens: number;
+} | {
+    level: "blocking";
+    usagePercent: number;
+    reason: "prompt_too_long" | "budget_exhausted";
+};
+export interface TurnLoopGuardState {
+    /** Current accumulated prompt tokens. */
+    promptTokens: number;
+    /** Whether reactive compact has already been attempted this turn. */
+    hasAttemptedReactiveCompact: boolean;
+    /** Current max_output_tokens (may escalate). */
+    currentMaxOutputTokens: number;
+    /** Number of consecutive max_tokens truncations. */
+    consecutiveTruncations: number;
+    /** Whether the turn has been aborted. */
+    aborted: boolean;
+}
+/** Initial guard state. */
+export declare function createTurnLoopGuardState(config: TurnLoopGuardConfig): TurnLoopGuardState;
+/**
+ * Calculate token warning state before making an API call.
+ * If level is "blocking", do NOT send the API call.
+ */
+export declare function calculateTokenWarningState(state: TurnLoopGuardState, config: TurnLoopGuardConfig): TokenWarningState;
+/**
+ * Handle API error and determine recovery action.
+ */
+export type ApiErrorRecovery = {
+    action: "reactive_compact";
+} | {
+    action: "escalate_output_tokens";
+    newMax: number;
+} | {
+    action: "retry";
+    reason: string;
+} | {
+    action: "abort";
+    reason: string;
+};
+export declare function resolveApiErrorRecovery(error: {
+    type?: string;
+    status?: number;
+    message?: string;
+}, state: TurnLoopGuardState, config: TurnLoopGuardConfig): ApiErrorRecovery;
+/**
+ * Handle finish_reason === "max_tokens" — escalate max_output_tokens.
+ *
+ * CC pattern: double the output token budget up to model max.
+ */
+export declare function resolveOutputTokenEscalation(state: TurnLoopGuardState, config: TurnLoopGuardConfig, modelMaxOutput: number): {
+    shouldEscalate: boolean;
+    newMax: number;
+};
+/**
+ * Check if the turn should be aborted (user cancellation).
+ */
+export declare function shouldAbortTurn(state: TurnLoopGuardState, config: TurnLoopGuardConfig): boolean;