qlogicagent 0.5.0 → 0.5.3

package/dist/types/orchestration/context-compression.d.ts

@@ -0,0 +1,301 @@
+export interface CompressibleMessage {
+    role: string;
+    content?: string | unknown;
+    tool_call_id?: string;
+    tool_calls?: unknown;
+    name?: string;
+}
+export interface CompressionResult {
+    messages: CompressibleMessage[];
+    droppedCount: number;
+    strategy: string;
+    /** Phase 4: optional metrics from the compression pass */
+    metrics?: CompressionMetrics;
+}
+export interface CompressionMetrics {
+    tokensBefore: number;
+    tokensAfter: number;
+    compressionRatio: number;
+    /** ms elapsed for this strategy pass */
+    latencyMs: number;
+    /** Whether an LLM call was made during this pass */
+    usedLlm: boolean;
+    /** Whether prompt cache was invalidated by compression */
+    cacheInvalidated?: boolean;
+}
+export interface CompressionStrategy {
+    compress(messages: CompressibleMessage[], budget: number): CompressionResult;
+}
+/**
+ * Async compression strategy — required for LLM-based summarization.
+ * Falls back to sync `compress` when the caller doesn't support async.
+ */
+export interface AsyncCompressionStrategy extends CompressionStrategy {
+    compressAsync(messages: CompressibleMessage[], budget: number): Promise<CompressionResult>;
+}
+export declare function isAsyncCompressionStrategy(s: CompressionStrategy): s is AsyncCompressionStrategy;
+/** Caller-provided LLM summarization function (wired by Hub). */
+export type SummarizeFn = (messages: CompressibleMessage[], instruction: string) => Promise<string>;
+export declare class SlidingWindowStrategy implements CompressionStrategy {
+    private estimateTokens;
+    constructor(estimateTokens: (msg: CompressibleMessage) => number);
+    compress(messages: CompressibleMessage[], budget: number): CompressionResult;
+}
+export declare class SummarizeOldStrategy implements CompressionStrategy {
+    private recentCount;
+    private summarize;
+    constructor(recentCount: number, summarize: (messages: CompressibleMessage[]) => string);
+    compress(messages: CompressibleMessage[], _budget: number): CompressionResult;
+}
+export declare class ToolResultTrimStrategy implements CompressionStrategy {
+    private maxToolResultChars;
+    constructor(maxToolResultChars?: number);
+    compress(messages: CompressibleMessage[], _budget: number): CompressionResult;
+}
+export declare function composeStrategies(...strategies: CompressionStrategy[]): CompressionStrategy;
+/**
+ * Compose strategies with async support — if any strategy is async,
+ * the pipeline becomes async.
+ */
+export declare function composeAsyncStrategies(...strategies: CompressionStrategy[]): AsyncCompressionStrategy;
+/**
+ * Build the structured 9-section summary instruction for the LLM.
+ * Based on Claude Code's Full Compact mode, adapted for Hub.
+ */
+export declare function buildStructuredSummaryPrompt(messagesToSummarize: CompressibleMessage[], opts?: {
+    taskContext?: string;
+}): string;
+export interface HeadTailProtectionConfig {
+    /** Number of initial user-assistant exchanges to protect (default: 1) */
+    protectedHeadExchanges: number;
+    /** Number of recent messages to always keep (default: 8 = ~4 exchanges) */
+    protectedTailMessages: number;
+    /** The summarization callback */
+    summarize: SummarizeFn;
+    /** Optional token estimator */
+    estimateTokens?: (msg: CompressibleMessage) => number;
+    /** Optional extra context for the summary prompt */
+    taskContext?: string;
+}
+/**
+ * Phase 2.2: Head/Tail protected summarization.
+ *
+ * Protects: system messages + first exchange + last N messages.
+ * Compresses: middle section via LLM summarization.
+ */
+export declare class HeadTailProtectedStrategy implements AsyncCompressionStrategy {
+    private config;
+    constructor(config: HeadTailProtectionConfig);
+    compress(messages: CompressibleMessage[], _budget: number): CompressionResult;
+    compressAsync(messages: CompressibleMessage[], budget: number): Promise<CompressionResult>;
+}
+export interface IncrementalCompactConfig {
+    /** Messages newer than this count are never summarized (default: 12) */
+    preserveRecentCount: number;
+    /** Summarization callback */
+    summarize: SummarizeFn;
+    /** Token estimator */
+    estimateTokens?: (msg: CompressibleMessage) => number;
+}
+/**
+ * Phase 2.3: Incremental (partial) compaction.
+ *
+ * Only summarizes the oldest messages beyond the preserve window.
+ * Avoids repeatedly re-summarizing already-compressed content.
+ * If a previous summary marker exists, only new old messages are compressed.
+ */
+export declare class IncrementalCompactStrategy implements AsyncCompressionStrategy {
+    private config;
+    constructor(config: IncrementalCompactConfig);
+    compress(messages: CompressibleMessage[], _budget: number): CompressionResult;
+    compressAsync(messages: CompressibleMessage[], budget: number): Promise<CompressionResult>;
+}
+export interface CacheAwareCompressionConfig {
+    /** The inner strategy to delegate to */
+    inner: CompressionStrategy;
+    /** Token estimator */
+    estimateTokens?: (msg: CompressibleMessage) => number;
+    /**
+     * Callback: notify when prompt cache was invalidated by compression.
+     * Hub uses this to set pendingPostCompaction and track cache miss rate.
+     */
+    onCacheInvalidated?: (info: {
+        droppedCount: number;
+        strategy: string;
+    }) => void;
+}
+/**
+ * Phase 3: Cache-aware wrapper.
+ *
+ * Wraps any strategy and tracks whether compression invalidated the
+ * provider prompt cache. System prompt prefix stability is preserved
+ * by never modifying system[0] (the original system prompt).
+ */
+export declare class CacheAwareCompressionStrategy implements AsyncCompressionStrategy {
+    private config;
+    constructor(config: CacheAwareCompressionConfig);
+    compress(messages: CompressibleMessage[], budget: number): CompressionResult;
+    compressAsync(messages: CompressibleMessage[], budget: number): Promise<CompressionResult>;
+}
+export interface AdaptiveBudgetConfig {
+    /** Model context window size in tokens */
+    modelContextWindow: number;
+    /** Target usage ratio (0.0–1.0, default 0.75) — trigger compaction at this fraction */
+    targetUsageRatio: number;
+    /** Minimum guaranteed budget in tokens */
+    minBudget: number;
+    /** Maximum budget (usually = modelContextWindow) */
+    maxBudget: number;
+}
+export declare const DEFAULT_ADAPTIVE_BUDGET_CONFIG: AdaptiveBudgetConfig;
+/**
+ * Compute the adaptive token budget for a given model + message history.
+ *
+ * Adjusts based on model context window, and uses the target ratio
+ * so compression triggers before hitting the hard limit.
+ */
+export declare function computeAdaptiveBudget(config?: Partial<AdaptiveBudgetConfig>): number;
+/**
+ * Decide which compression tier to use based on current token count vs budget.
+ */
+export type CompressionTier = "none" | "trim-only" | "sliding-window" | "llm-summarize";
+export declare function selectCompressionTier(currentTokens: number, budget: number): CompressionTier;
+export interface CompressionEvent {
+    timestamp: number;
+    strategy: string;
+    tokensBefore: number;
+    tokensAfter: number;
+    droppedCount: number;
+    latencyMs: number;
+    usedLlm: boolean;
+    cacheInvalidated: boolean;
+    tier: CompressionTier;
+}
+export interface CompressionMetricsSnapshot {
+    totalCompressions: number;
+    totalLlmCalls: number;
+    totalCacheInvalidations: number;
+    averageCompressionRatio: number;
+    averageLatencyMs: number;
+    totalTokensSaved: number;
+    recentEvents: CompressionEvent[];
+}
+export declare class CompressionMetricsCollector {
+    private events;
+    private maxEvents;
+    constructor(maxEvents?: number);
+    record(event: CompressionEvent): void;
+    snapshot(): CompressionMetricsSnapshot;
+    reset(): void;
+}
+/**
+ * A pluggable context engine. Only one can be active at a time.
+ * The default engine uses the 4-layer compression funnel.
+ */
+export interface ContextEngine {
+    /** Unique engine identifier */
+    readonly id: string;
+    /** Human-readable label */
+    readonly label: string;
+    /** Compress messages for a turn */
+    compressAsync(messages: CompressibleMessage[], budget: number, context?: {
+        model?: string;
+        sessionId?: string;
+    }): Promise<CompressionResult>;
+}
+/**
+ * Registry for context engines. Enforces single-active constraint.
+ */
+export declare class ContextEngineRegistry {
+    private engines;
+    private activeId;
+    register(engine: ContextEngine): void;
+    activate(id: string): boolean;
+    getActive(): ContextEngine | undefined;
+    listEngines(): Array<{
+        id: string;
+        label: string;
+        active: boolean;
+    }>;
+}
+/**
+ * MicroCompact — selective clearing of old compactable tool results.
+ *
+ * CC parity: microCompact.ts
+ *
+ * For tool result messages from COMPACTABLE_TOOLS, if the message is
+ * "old enough" (not in the most recent N messages), replace its content
+ * with a compact "[result cleared]" marker. This preserves the tool call
+ * structure (so the LLM knows what was called) but reclaims token budget.
+ *
+ * This is a lighter alternative to full summarization — it runs BEFORE
+ * LLM summarization as a first-pass reduction.
+ */
+export declare class MicroCompactStrategy implements CompressionStrategy {
+    /** Number of recent messages to preserve (don't clear) */
+    private preserveRecentCount;
+    /** Token estimator */
+    private estimateTokens;
+    constructor(
+    /** Number of recent messages to preserve (don't clear) */
+    preserveRecentCount?: number, 
+    /** Token estimator */
+    estimateTokens?: (msg: CompressibleMessage) => number);
+    compress(messages: CompressibleMessage[], _budget: number): CompressionResult;
+}
+/**
+ * After compaction, the most recently read/edited files may have been
+ * dropped from the conversation. CC re-injects up to N file contents
+ * to ensure the agent doesn't lose awareness of files it was working with.
+ *
+ * CC parity: compact.ts postCompactFileStateRecovery
+ */
+export interface PostCompactRecoveryConfig {
+    /** Maximum number of files to re-inject (default 5) */
+    maxFiles: number;
+    /** Maximum total tokens for re-injected files (default 50000) */
+    maxTokenBudget: number;
+    /** Function to read a file from disk (injected by caller) */
+    readFile: (path: string) => Promise<string | null>;
+    /** Token estimator */
+    estimateTokens?: (text: string) => number;
+}
+/**
+ * Extract file paths that were recently read/edited from the conversation.
+ * Looks at tool calls and results for file path arguments.
+ */
+export declare function extractRecentFilePaths(messages: CompressibleMessage[]): string[];
+/**
+ * Re-inject recently-used file contents after compaction.
+ *
+ * Call this AFTER compression but BEFORE sending to the LLM.
+ * Appends file content as system messages at the end of the
+ * system message block.
+ */
+export declare function postCompactFileRecovery(compressedMessages: CompressibleMessage[], originalMessages: CompressibleMessage[], config: PostCompactRecoveryConfig): Promise<CompressibleMessage[]>;
+/**
+ * Snip Compact — permanently remove specific messages by identifier.
+ *
+ * CC parity: services/compact/snipCompact.ts
+ *
+ * Unlike sliding window or summarization, snip removes messages by
+ * their unique id (tool_call_id, or index-based). This is used for:
+ * - Removing old tool results that are known to be stale
+ * - Dropping large image/media messages after they've been processed
+ * - Clearing tombstoned messages from the transcript
+ *
+ * Snip runs BEFORE microcompact and autocompact — both may fire
+ * after snip if the result is still over threshold.
+ */
+export interface SnipResult {
+    messages: CompressibleMessage[];
+    tokensFreed: number;
+    removedCount: number;
+    /** Optional boundary message to yield (marks snip point in transcript). */
+    boundaryMessage?: CompressibleMessage;
+}
+/**
+ * Remove messages whose tool_call_id or name matches the removedIds set.
+ * If no removedIds are pending, this is a no-op.
+ */
+export declare function snipCompactIfNeeded(messages: CompressibleMessage[], removedIds: Set<string>, estimateTokens?: (msg: CompressibleMessage) => number): SnipResult;

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

package/dist/types/orchestration/curator-scheduler.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Curator scheduler — pure strategy for autonomous skill library
+ * maintenance. Decides WHEN to run the curator review cycle and
+ * computes automatic lifecycle transitions (active → stale → archived).
+ *
+ * No I/O — all functions are pure; the caller supplies timestamps and
+ * skill records, and receives transition instructions back.
+ */
+/** Policy knobs for the curator scheduler. */
+export interface CuratorSchedulePolicy {
+    /** Minimum idle seconds before curator may trigger (default: 7200 = 2 h). */
+    minIdleSeconds: number;
+    /** Minimum interval between curator runs in seconds (default: 604800 = 7 days). */
+    intervalSeconds: number;
+    /** Days without activity before marking a skill stale (default: 30). */
+    staleAfterDays: number;
+    /** Days without activity before archiving a stale skill (default: 90). */
+    archiveAfterDays: number;
+    /** Maximum skills to process in one LLM review pass (default: 50). */
+    maxReviewBatchSize: number;
+}
+export declare const DEFAULT_CURATOR_SCHEDULE_POLICY: CuratorSchedulePolicy;
+/** Persistent curator state (stored by the host runtime). */
+export interface CuratorState {
+    /** ISO-8601 timestamp of last curator run. */
+    lastRunAt: string | null;
+    /** Duration of last run in seconds. */
+    lastRunDurationSeconds: number;
+    /** Human-readable summary of last run. */
+    lastRunSummary: string;
+    /** Whether curator is paused by the user. */
+    paused: boolean;
+    /** Cumulative run count. */
+    runCount: number;
+}
+export declare const INITIAL_CURATOR_STATE: CuratorState;
+/** Lifecycle state of an agent-created skill. */
+export type CuratorSkillLifecycleState = "active" | "stale" | "archived";
+/** Minimal skill activity record consumed by the scheduler. */
+export interface CuratorSkillRecord {
+    /** Skill name / identifier. */
+    name: string;
+    /** Whether this skill was agent-created (only these are curated). */
+    agentCreated: boolean;
+    /** Current lifecycle state. */
+    state: CuratorSkillLifecycleState;
+    /** Whether the user pinned this skill (immune to auto-transitions). */
+    pinned: boolean;
+    /** ISO-8601 timestamp of last activity. */
+    lastActivityAt: string | null;
+    /** Cumulative use count. */
+    useCount: number;
+    /** ISO-8601 timestamp of creation. */
+    createdAt: string;
+}
+/** Input for the gate check. */
+export interface CuratorGateInput {
+    /** Current ISO-8601 timestamp. */
+    now: string;
+    /** Seconds the session has been idle. */
+    idleSeconds: number;
+    /** Current curator state. */
+    state: CuratorState;
+    /** Whether the feature is enabled at all. */
+    enabled: boolean;
+    /** Policy overrides. */
+    policy?: Partial<CuratorSchedulePolicy>;
+}
+/** Result of the gate check: should the curator run? */
+export interface CuratorGateResult {
+    shouldRun: boolean;
+    reason: string;
+}
+/**
+ * Determine whether the curator should run now.
+ *
+ * All gates must pass:
+ * 1. Feature enabled
+ * 2. Not paused
+ * 3. Session idle ≥ minIdleSeconds
+ * 4. Time since last run ≥ intervalSeconds
+ */
+export declare function shouldRunCurator(input: CuratorGateInput): CuratorGateResult;
+/** A single lifecycle transition computed by the scheduler. */
+export interface CuratorLifecycleTransition {
+    skillName: string;
+    from: CuratorSkillLifecycleState;
+    to: CuratorSkillLifecycleState;
+    reason: string;
+}
+/** Summary of all auto-transitions in one pass. */
+export interface CuratorAutoTransitionResult {
+    checked: number;
+    transitions: CuratorLifecycleTransition[];
+    markedStale: number;
+    archived: number;
+    reactivated: number;
+}
+/**
+ * Compute automatic lifecycle transitions for agent-created skills.
+ *
+ * Pure function — no I/O, no mutations. The caller applies the
+ * returned transitions to its skill storage.
+ *
+ * Rules:
+ * - Pinned skills are never transitioned.
+ * - Non-agent-created skills are skipped.
+ * - active → stale: no activity for staleAfterDays.
+ * - stale → archived: no activity for archiveAfterDays.
+ * - stale/archived → active: if useCount increased (reactivation).
+ */
+export declare function computeLifecycleTransitions(skills: readonly CuratorSkillRecord[], now: string, policy?: Partial<CuratorSchedulePolicy>): CuratorAutoTransitionResult;
+/**
+ * Select skills that should be reviewed by the LLM curator.
+ *
+ * Only non-pinned, agent-created skills in active or stale state
+ * are eligible for review. Returns at most maxReviewBatchSize names.
+ */
+export declare function selectReviewCandidates(skills: readonly CuratorSkillRecord[], policy?: Partial<CuratorSchedulePolicy>): string[];

package/dist/types/orchestration/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/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/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/fork-subagent.d.ts

@@ -0,0 +1,100 @@
+/**
+ * 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 (more permissive than DB sidechain). */
+export declare const MAX_FORK_DEPTH = 4;
+/** Maximum fork depth for DB-backed sidechains (more conservative). */
+export declare const MAX_SIDECHAIN_DB_DEPTH = 2;
+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, mode?: "in-memory" | "db-sidechain"): 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;