qlogicagent 0.5.2 → 0.6.0

package/dist/types/orchestration/context/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;

package/dist/types/orchestration/error-handling/error-classification.d.ts

@@ -0,0 +1,12 @@
+import type { FailoverReason } from "./failover-classification.js";
+export type ErrorCategory = "RETRYABLE_TRANSIENT" | "RETRYABLE_DEGRADED" | "NON_RETRYABLE_AUTH" | "NON_RETRYABLE_CONTENT" | "NON_RETRYABLE_QUOTA" | "TOOL_EXECUTION_FAILED";
+export interface RetryStrategy {
+    retryable: boolean;
+    maxRetries: number;
+    baseDelayMs: number;
+    backoffMultiplier: number;
+    switchProvider: boolean;
+}
+export declare function classifyError(status: number | undefined, message?: string): ErrorCategory;
+export declare function classifyErrorFromReason(reason: FailoverReason): ErrorCategory;
+export declare function getRetryStrategy(category: ErrorCategory): RetryStrategy;

package/dist/types/orchestration/error-handling/failover-classification.d.ts

@@ -0,0 +1,8 @@
+export type FailoverReason = "auth" | "auth_permanent" | "format" | "rate_limit" | "overloaded" | "billing" | "timeout" | "model_not_found" | "session_expired" | "unknown";
+export declare function isTimeoutErrorMessage(raw: string): boolean;
+export declare function isCloudflareOrHtmlErrorPage(raw: string): boolean;
+export declare function isTransientHttpError(raw: string): boolean;
+export declare function classifyFailoverReasonFromHttpStatus(status: number | undefined, message?: string): FailoverReason | null;
+export declare function isModelNotFoundErrorMessage(raw: string): boolean;
+export declare function classifyFailoverReason(raw: string): FailoverReason | null;
+export declare function isFailoverErrorMessage(raw: string): boolean;

package/dist/types/orchestration/error-handling/failover-error.d.ts

@@ -0,0 +1,33 @@
+import { type FailoverReason } from "./failover-classification.js";
+export declare class FailoverError extends Error {
+    readonly reason: FailoverReason;
+    readonly provider?: string;
+    readonly model?: string;
+    readonly profileId?: string;
+    readonly status?: number;
+    readonly code?: string;
+    constructor(message: string, params: {
+        reason: FailoverReason;
+        provider?: string;
+        model?: string;
+        profileId?: string;
+        status?: number;
+        code?: string;
+        cause?: unknown;
+    });
+}
+export declare function isFailoverError(err: unknown): err is FailoverError;
+export declare function resolveFailoverStatus(reason: FailoverReason): number | undefined;
+export declare function isTimeoutError(err: unknown): boolean;
+export declare function resolveFailoverReasonFromError(err: unknown): FailoverReason | null;
+export declare function describeFailoverError(err: unknown): {
+    message: string;
+    reason?: FailoverReason;
+    status?: number;
+    code?: string;
+};
+export declare function coerceToFailoverError(err: unknown, context?: {
+    provider?: string;
+    model?: string;
+    profileId?: string;
+}): FailoverError | null;

package/dist/types/orchestration/error-handling/retry-loop.d.ts

@@ -0,0 +1,69 @@
+export declare function executeBoundedRetryLoop<TResult>(params: {
+    maxIterations: number;
+    onRetryLimit: (params: {
+        iterations: number;
+        maxIterations: number;
+    }) => Promise<TResult> | TResult;
+    executeIteration: (params: {
+        iteration: number;
+    }) => Promise<{
+        kind: "continue";
+    } | {
+        kind: "return";
+        result: TResult;
+    }>;
+}): Promise<TResult>;
+export declare function resolveScaledRetryIterations(params: {
+    candidateCount: number;
+    baseIterations?: number;
+    perCandidateIterations?: number;
+    minIterations?: number;
+    maxIterations?: number;
+}): number;
+export declare function isForegroundSource(source: string | undefined): boolean;
+/** Is this a transient capacity error (429 or 529/overloaded)? */
+export declare function isTransientCapacityError(status: number | undefined): boolean;
+/**
+ * Compute exponential backoff delay with jitter.
+ * CC parity: withRetry.ts — BASE_DELAY_MS=500, 2^n backoff, capped.
+ */
+export declare function computeRetryBackoff(attempt: number, baseDelayMs?: number, maxDelayMs?: number): number;
+/**
+ * Persistent retry mode — for unattended sessions.
+ * Retries 429/529 indefinitely with higher backoff.
+ * Yields heartbeat events periodically so the host doesn't mark us idle.
+ *
+ * CC parity: withRetry.ts CLAUDE_CODE_UNATTENDED_RETRY
+ */
+export interface PersistentRetryConfig {
+    /** Max backoff interval (CC: 5 min). */
+    maxBackoffMs: number;
+    /** Total cap before giving up (CC: 6 hours). */
+    resetCapMs: number;
+    /** Heartbeat interval during waits (CC: 30 seconds). */
+    heartbeatIntervalMs: number;
+}
+export declare const DEFAULT_PERSISTENT_RETRY_CONFIG: PersistentRetryConfig;
+/**
+ * Check if persistent retry is enabled via environment variable.
+ * CC parity: CLAUDE_CODE_UNATTENDED_RETRY
+ */
+export declare function isPersistentRetryEnabled(): boolean;
+/**
+ * Error class for triggering model fallback after repeated 529s.
+ * CC parity: FallbackTriggeredError
+ */
+export declare class FallbackTriggeredError extends Error {
+    readonly originalModel: string;
+    readonly fallbackModel: string;
+    constructor(originalModel: string, fallbackModel: string);
+}
+/**
+ * Error class for when retries are exhausted and cannot continue.
+ * CC parity: CannotRetryError
+ */
+export declare class CannotRetryError extends Error {
+    readonly originalError: unknown;
+    readonly model: string;
+    constructor(originalError: unknown, model: string);
+}

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

@@ -0,0 +1,15 @@
+export { buildAssistantToolCallMessage, buildToolResultMessage, type FunctionToolDefinition, } from "./tool-loop/tool-schema.js";
+export { classifyError, getRetryStrategy, type ErrorCategory, type RetryStrategy, } from "./error-handling/error-classification.js";
+export { composeStrategies, composeAsyncStrategies, SlidingWindowStrategy, SummarizeOldStrategy, ToolResultTrimStrategy, HeadTailProtectedStrategy, IncrementalCompactStrategy, CacheAwareCompressionStrategy, CompressionMetricsCollector, ContextEngineRegistry, MicroCompactStrategy, postCompactFileRecovery, type PostCompactRecoveryConfig, buildStructuredSummaryPrompt, computeAdaptiveBudget, isAsyncCompressionStrategy, selectCompressionTier, DEFAULT_ADAPTIVE_BUDGET_CONFIG, type AdaptiveBudgetConfig, type AsyncCompressionStrategy, type CacheAwareCompressionConfig, type CompressibleMessage, type CompressionEvent, type CompressionMetrics, type CompressionMetricsSnapshot, type CompressionResult, type CompressionStrategy, type CompressionTier, type ContextEngine, type HeadTailProtectionConfig, type IncrementalCompactConfig, type SummarizeFn, } from "./context/context-compression.js";
+export { snipCompactIfNeeded, type SnipResult, } from "./context/context-compression.js";
+export { applyCollapsesIfNeeded as applyContextCollapsesIfNeeded, recoverFromOverflow as recoverContextCollapseFromOverflow, createCollapseStore, type CollapseStore, type CollapseStage, } from "./context/context-collapse.js";
+export { buildSkillInstruction, type SkillCreateInstruction, type SkillImproveInstruction, type SkillInstruction, type SkillTurnResult, } from "./skill-improvement.js";
+export { applyToolChoicePolicy, type ApplyToolChoicePolicyInput, type ApplyToolChoicePolicyResult, } from "./tool-loop/tool-choice-policy.js";
+export { repairOpenAiChatConversation, type ConversationRepairOptions, type OpenAiChatMessageLike, type OpenAiToolCall, } from "./tool-loop/conversation-repair.js";
+export { advanceToolLoopState, recoverToolLoopStateFromChatConversation, recoverToolLoopStateFromResponsesItems, settleToolLoopState, type RepairToolLoopStateResult, type ToolLoopRepairAction, type ToolLoopState, } from "./tool-loop/tool-loop-state.js";
+export { isForegroundSource, isTransientCapacityError, computeRetryBackoff, isPersistentRetryEnabled, FallbackTriggeredError, type PersistentRetryConfig, } from "./error-handling/retry-loop.js";
+export { canForkAtDepth, buildForkedMessages, buildForkPlaceholderResults, FORK_PLACEHOLDER_RESULT, FORK_SENTINEL_TAG, generateForkChildAgentId, isInForkChild, MAX_FORK_DEPTH, resolveForkChildTools, type ForkChildConfig, type ForkChildMessage, type ForkContext, type ForkResult, } from "./subagent/fork-subagent.js";
+export { getBuiltInAgent, getBuiltInAgents, isBuiltInAgent, resolveAgentToolSet, type AgentDefinition, } from "./subagent/agent-registry.js";
+export { createTaskState, filterToolsByRole, type IsolationMode, type PermissionRole, type TaskType, type TaskLifecycle, type TaskState, type TaskStateBase, type LocalBashTaskState, type LocalAgentTaskState, type RemoteAgentTaskState, type InProcessTeammateTaskState, type DreamTaskState, type DreamTurn, type DreamPhase, } from "./subagent/task-types.js";
+export { calculateTokenWarningState, createTurnLoopGuardState, resolveApiErrorRecovery, resolveOutputTokenEscalation, shouldAbortTurn, type ApiErrorRecovery, type TokenWarningState, type TurnLoopGuardConfig, type TurnLoopGuardState, } from "./context/turn-loop-guard.js";
+export { buildPostCompactRestorationMessage, createReactiveCompactState, shouldAttemptReactiveCompact, type ReactiveCompactConfig, type ReactiveCompactState, } from "./context/reactive-compact.js";

package/dist/types/orchestration/skill-improvement.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Skill self-learning: decides whether a completed turn should
+ * trigger skill creation or improvement instructions.
+ */
+export interface SkillTurnResult {
+    ok: boolean;
+    /** Number of tool invocations in this turn */
+    toolCallCount: number;
+    /** Number of distinct tool names used */
+    distinctToolCount: number;
+    /** Was a multi-step orchestration (≥2 rounds) used? */
+    multiStep: boolean;
+    /** Did the turn involve a sub-agent fork? */
+    hasSubAgent: boolean;
+    /** Optional user feedback signal (positive/negative/none) */
+    feedback?: "positive" | "negative" | null;
+    /** Skill name if an existing skill was used */
+    existingSkillName?: string | null;
+}
+export interface SkillCreateInstruction {
+    type: "skill.create";
+    /** Suggested skill name derived from tool usage pattern */
+    suggestedName: string;
+    /** Short description of what the skill does */
+    description: string;
+    /** Tool names involved */
+    tools: string[];
+    /** Number of orchestration steps */
+    stepCount: number;
+}
+export interface SkillImproveInstruction {
+    type: "skill.improve";
+    /** Existing skill to improve */
+    skillName: string;
+    /** Reason for improvement */
+    reason: string;
+}
+export type SkillInstruction = SkillCreateInstruction | SkillImproveInstruction;
+/**
+ * Determine whether a completed turn should produce a skill instruction.
+ *
+ * A new skill is suggested when:
+ * - The turn succeeded
+ * - It involved multi-step orchestration
+ * - It used ≥3 tool calls across ≥2 distinct tools
+ * - No existing skill was already applied
+ *
+ * An improvement is suggested when:
+ * - The turn used an existing skill but got negative feedback
+ */
+export declare function shouldCreateSkill(result: SkillTurnResult): boolean;
+export declare function shouldImproveSkill(result: SkillTurnResult): boolean;
+/**
+ * Build a skill instruction from a turn result, or null if none is warranted.
+ */
+export declare function buildSkillInstruction(result: SkillTurnResult, context: {
+    tools: string[];
+    suggestedName?: string;
+}): SkillInstruction | null;

package/dist/types/orchestration/subagent/agent-registry.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Built-in Agent Registry — CC-aligned agent definitions for fork/subagent.
+ *
+ * Each built-in agent defines a role with constrained tools, system prompt,
+ * and execution budget. The LLM can invoke these via the AgentTool.
+ */
+import type { PermissionRole, IsolationMode } from "./task-types.js";
+export interface AgentDefinition {
+    /** Unique identifier for the agent (kebab-case). */
+    name: string;
+    /** Human-readable label. */
+    label: string;
+    /** Short description (appears in tool_search / LLM prompt). */
+    description: string;
+    /** Maximum turns this agent can execute before forced stop. */
+    maxTurns: number;
+    /** Tool access mode. */
+    toolAccessMode: "full" | "read-only" | "none";
+    /** Explicit allowed tool names (if empty, uses toolAccessMode filter). */
+    allowedTools?: string[];
+    /** Whether this agent can fork sub-agents itself. */
+    canFork: boolean;
+    /** System prompt override for this agent. */
+    systemPromptSuffix?: string;
+    /** Permission role context (CC: interactive/coordinator/worker). Default: "worker". */
+    permissionRole?: PermissionRole;
+    /** Isolation mode (CC: shared/worktree/container). Default: "shared". */
+    isolation?: IsolationMode;
+}
+/**
+ * Get the full list of built-in agent definitions.
+ */
+export declare function getBuiltInAgents(): AgentDefinition[];
+/**
+ * Look up a built-in agent by name.
+ */
+export declare function getBuiltInAgent(name: string): AgentDefinition | undefined;
+/**
+ * Check if a given agent name is a built-in agent.
+ */
+export declare function isBuiltInAgent(name: string): boolean;
+/**
+ * Resolve tool access for an agent definition.
+ * Returns the set of tool names the agent is allowed to use.
+ */
+export declare function resolveAgentToolSet(agent: AgentDefinition, availableTools: string[]): string[];

package/dist/types/orchestration/subagent/fork-subagent.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Fork Sub-Agent — CC-aligned fork mechanism for spawning child agents.
+ *
+ * Core design principles (aligned with Claude Code):
+ * 1. Child agent shares parent's message prefix (prompt cache hit)
+ * 2. Fork uses placeholder results to ensure byte-identical prefix across children
+ * 3. Child has independent tool context (doesn't pollute parent state)
+ * 4. Results flow back via AsyncGenerator (streaming backflow)
+ * 5. Depth control via in-memory counter (not DB-based)
+ */
+import type { AgentDefinition } from "./agent-registry.js";
+/** Sentinel tag injected into fork children to prevent recursive forking. */
+export declare const FORK_SENTINEL_TAG = "<fork-child-context>";
+/** Placeholder text used for all tool_results in shared prefix (ensures byte-identical prefix). */
+export declare const FORK_PLACEHOLDER_RESULT = "Fork started \u2014 processing in background";
+/** Maximum fork depth for in-memory agents (CC: MAX_FORK_DEPTH). */
+export declare const MAX_FORK_DEPTH = 4;
+export interface ForkContext {
+    /** Parent's full message history (becomes shared prefix for cache). */
+    parentMessages: unknown[];
+    /** Parent's rendered system prompt (byte-exact for cache hit). */
+    systemPrompt: string;
+    /** Parent's full tool pool (useExactTools=true pattern). */
+    parentTools: string[];
+    /** Current fork depth (0 = root). */
+    depth: number;
+    /** Abort signal from parent. */
+    abortSignal?: AbortSignal;
+    /** Parent's agent ID for lineage tracking. */
+    parentAgentId: string;
+}
+export interface ForkChildConfig {
+    /** The agent definition to run. */
+    agent: AgentDefinition;
+    /** Task-specific prompt for this child (the unique part after shared prefix). */
+    taskPrompt: string;
+    /** Optional override for max turns. */
+    maxTurns?: number;
+    /** Whether to run in background (async). */
+    isAsync?: boolean;
+}
+export interface ForkChildMessage {
+    role: "assistant" | "user" | "system";
+    content: unknown;
+    toolCalls?: unknown[];
+}
+export interface ForkResult {
+    /** Whether the fork completed successfully. */
+    ok: boolean;
+    /** Child's final output text (summary). */
+    output: string;
+    /** Messages produced by the child (for result backflow). */
+    messages: ForkChildMessage[];
+    /** Total tokens consumed by the child. */
+    tokensUsed: number;
+    /** Whether the child hit its turn limit. */
+    maxTurnsReached: boolean;
+    /** Child's agent ID. */
+    childAgentId: string;
+}
+/**
+ * Check if current context is inside a fork child (prevents recursive forking).
+ */
+export declare function isInForkChild(messages: unknown[]): boolean;
+/**
+ * Check if fork depth allows spawning another child.
+ */
+export declare function canForkAtDepth(currentDepth: number): boolean;
+/**
+ * Build forked messages that ensure byte-identical prefix across all fork children.
+ *
+ * Strategy (aligned with CC's buildForkedMessages):
+ * 1. Keep full parent message history (all tool_use blocks, thinking, text)
+ * 2. Replace all pending tool_results with FORK_PLACEHOLDER_RESULT
+ * 3. Append a single user message with the child-specific directive
+ * → All children share the same prefix up to the directive → maximum cache hits.
+ */
+export declare function buildForkedMessages(context: ForkContext, childConfig: ForkChildConfig): unknown[];
+/**
+ * Build placeholder tool results for the shared prefix.
+ * When parent has pending tool_calls, replace them all with identical placeholder text
+ * so all fork children produce byte-identical API request prefix.
+ */
+export declare function buildForkPlaceholderResults(pendingToolCallIds: string[]): Array<{
+    role: "tool";
+    tool_call_id: string;
+    content: string;
+}>;
+/**
+ * Resolve the effective tool set for a fork child.
+ * CC pattern: useExactTools=true → child gets parent's full tool pool,
+ * then filtered by agent definition.
+ */
+export declare function resolveForkChildTools(parentTools: string[], agent: AgentDefinition): string[];
+/**
+ * Generate a unique agent ID for a fork child.
+ */
+export declare function generateForkChildAgentId(parentAgentId: string, agentName: string, depth: number): string;

package/dist/types/orchestration/subagent/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/tool-loop/conversation-repair.d.ts

@@ -0,0 +1,61 @@
+export interface OpenAiToolCall {
+    id: string;
+    type: "function";
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+export interface OpenAiChatToolCallRef {
+    id?: string;
+    function?: {
+        name?: string;
+        arguments?: string;
+    };
+    name?: string;
+    [key: string]: unknown;
+}
+export interface OpenAiChatMessageLike {
+    role: string;
+    content?: unknown;
+    tool_calls?: OpenAiChatToolCallRef[];
+    tool_call_id?: string;
+    [key: string]: unknown;
+}
+export interface OpenAiResponsesItemLike {
+    type: string;
+    id?: string;
+    call_id?: string;
+    role?: string;
+    content?: unknown;
+    status?: string;
+    [key: string]: unknown;
+}
+export interface ConversationRepairOptions {
+    stopReason?: string;
+    placeholderToolResult?: string;
+    placeholderFunctionCallOutput?: string;
+    forcedStopReasons?: readonly string[];
+}
+type ContentPart = {
+    type: string;
+    text?: string;
+    [key: string]: unknown;
+};
+export type { ContentPart };
+export declare function sanitizeOpenAiChatMessages<T extends OpenAiChatMessageLike>(messages: readonly T[]): T[];
+export declare function ensureAssistantReasoningContent<T extends Record<string, unknown>>(messages: readonly T[], defaultValue?: string): T[];
+export declare function stripForcedStopAssistantToolMetadata<T extends OpenAiChatMessageLike>(messages: readonly T[], options?: ConversationRepairOptions): T[];
+export declare function injectDanglingToolCallPlaceholders<T extends OpenAiChatMessageLike>(messages: readonly T[], options?: ConversationRepairOptions): T[];
+export declare function repairOpenAiChatConversation<T extends OpenAiChatMessageLike>(messages: readonly T[], options?: ConversationRepairOptions): T[];
+export declare function downgradeOpenAiFunctionCallReasoningPairs<T extends {
+    role?: unknown;
+    content?: unknown;
+    toolCallId?: unknown;
+    toolUseId?: unknown;
+}>(messages: readonly T[]): T[];
+export declare function downgradeOpenAiReasoningBlocks<T extends {
+    role?: unknown;
+    content?: unknown;
+}>(messages: readonly T[]): T[];
+export declare function repairOpenAiResponsesItems<T extends OpenAiResponsesItemLike>(items: readonly T[], options?: ConversationRepairOptions): T[];