langflower 0.0.7 → 0.0.9

package/vendor/common-nodes/dist/ai/features/llm-loop/llm-loop-types.d.ts

@@ -0,0 +1,125 @@
+import type { ChatCompletionMessage, ChatCompletionToolCall } from '../chat-completion-stream.js';
+type LlmFailureKind = 'authentication' | 'configuration' | 'context-overflow' | 'output-truncated' | 'rate-limit' | 'provider-unavailable' | 'stream-idle' | 'network' | 'tool-timeout' | 'subagent-timeout' | 'protocol' | 'unknown';
+export type LlmFailure = {
+    readonly kind: LlmFailureKind;
+    readonly message: string;
+    readonly recoverable: boolean;
+    readonly status?: number;
+    readonly retryAfterMs?: number;
+    readonly rawContentType?: string;
+};
+type LlmSuspendReason = {
+    readonly kind: 'user-pause';
+} | {
+    readonly kind: 'stream-idle';
+    readonly idleMs: number;
+} | {
+    readonly kind: 'dead-loop';
+    readonly channel: 'reasoning' | 'draft';
+    readonly reason: 'consecutive' | 'cyclic';
+} | {
+    readonly kind: 'provider-failure';
+    readonly failure: LlmFailure;
+};
+type LlmLoopPhase = 'prepare' | 'streaming' | 'tools' | 'waiting-subagent' | 'suspended' | 'complete' | 'failed' | 'cancelled';
+export type LlmLoopState = {
+    readonly phase: LlmLoopPhase;
+    readonly committedMessages: readonly ChatCompletionMessage[];
+    readonly roundCheckpoint: readonly ChatCompletionMessage[];
+    readonly iteration: number;
+    readonly transientAttempts: number;
+    readonly partial: {
+        readonly reasoning: string;
+        readonly draft: string;
+        readonly toolCalls?: readonly ChatCompletionToolCall[];
+    };
+    readonly pendingToolCalls: readonly ChatCompletionToolCall[];
+    readonly autokickAttempts: number;
+    /** Kick-mode autokicks only; HTTP join does not bump penalties. */
+    readonly autokickKickAttempts: number;
+    readonly lastAutokickAt?: number | undefined;
+    readonly openSpawnCallId?: string | undefined;
+    readonly suspendedBy?: LlmSuspendReason | undefined;
+    readonly failure?: LlmFailure | undefined;
+};
+export type LlmLoopAction = {
+    readonly type: 'round.prepared';
+    readonly messages: readonly ChatCompletionMessage[];
+} | {
+    readonly type: 'stream.reasoning';
+    readonly text: string;
+} | {
+    readonly type: 'stream.draft';
+    readonly text: string;
+} | {
+    readonly type: 'stream.done';
+    readonly text: string;
+    readonly toolCalls?: readonly ChatCompletionToolCall[];
+} | {
+    readonly type: 'stream.paused';
+} | {
+    readonly type: 'stream.idle';
+    readonly idleMs: number;
+} | {
+    readonly type: 'stream.dead-loop';
+    readonly channel: 'reasoning' | 'draft';
+    readonly reason: 'consecutive' | 'cyclic';
+} | {
+    readonly type: 'provider.failed';
+    readonly failure: LlmFailure;
+} | {
+    readonly type: 'tool.completed';
+    readonly call: ChatCompletionToolCall;
+    readonly result: string;
+} | {
+    readonly type: 'subagent.waiting';
+    readonly callId: string;
+} | {
+    readonly type: 'subagent.completed';
+} | {
+    readonly type: 'retry.scheduled';
+} | {
+    readonly type: 'autokick.scheduled';
+    /** Omit for HTTP replay-only (no kick user turn). */
+    readonly kickUserMessage?: string;
+    readonly atMs: number;
+} | {
+    readonly type: 'steer.received';
+    readonly text?: string;
+} | {
+    readonly type: 'round.completed';
+} | {
+    readonly type: 'failure.fatal';
+    readonly failure: LlmFailure;
+} | {
+    readonly type: 'cancel.requested';
+};
+type LlmDeadLoopPolicy = {
+    readonly maxWindowTokens: number;
+    readonly consecutiveThreshold: number;
+    readonly minRepetitions: number;
+    readonly minPatternTokens: number;
+};
+export type LlmRecoveryPolicy = {
+    readonly streamIdleTimeoutMs: number;
+    readonly toolTimeoutMs: number;
+    readonly subagentTimeoutMs: number;
+    readonly maxTransientRetries: number;
+    readonly retryBaseDelayMs: number;
+    readonly maxToolResultChars: number;
+    readonly autokickOnIdle: boolean;
+    readonly deadLoopEnabled: boolean;
+    readonly maxAutokickAttempts: number;
+    readonly autokickBackoffMs: number;
+    readonly autokickMaxBackoffMs: number;
+    readonly autokickUserMessage: string;
+    readonly autokickPenaltyDelta: {
+        readonly frequency: number;
+        readonly presence: number;
+    };
+    readonly deadLoop: LlmDeadLoopPolicy;
+};
+export declare const DEFAULT_AUTOKICK_USER_MESSAGE = "I notice you are repeating yourself. Please stop and provide a concise answer.";
+export declare const DEFAULT_LLM_RECOVERY_POLICY: LlmRecoveryPolicy;
+export declare const initialLlmLoopState: (messages: readonly ChatCompletionMessage[]) => LlmLoopState;
+export {};

package/vendor/common-nodes/dist/ai/features/llm-loop/llm-loop-types.js

@@ -0,0 +1,39 @@
+export const DEFAULT_AUTOKICK_USER_MESSAGE = 'I notice you are repeating yourself. Please stop and provide a concise answer.';
+export const DEFAULT_LLM_RECOVERY_POLICY = {
+    streamIdleTimeoutMs: 90_000,
+    toolTimeoutMs: 60_000,
+    subagentTimeoutMs: 300_000,
+    maxTransientRetries: 2,
+    retryBaseDelayMs: 1_000,
+    maxToolResultChars: 40_000,
+    autokickOnIdle: true,
+    deadLoopEnabled: true,
+    maxAutokickAttempts: 0,
+    autokickBackoffMs: 60_000,
+    autokickMaxBackoffMs: 960_000,
+    autokickUserMessage: DEFAULT_AUTOKICK_USER_MESSAGE,
+    autokickPenaltyDelta: {
+        frequency: 0.3,
+        presence: 0.3,
+    },
+    deadLoop: {
+        maxWindowTokens: 1_000,
+        consecutiveThreshold: 5,
+        minRepetitions: 3,
+        minPatternTokens: 2,
+    },
+};
+export const initialLlmLoopState = (messages) => ({
+    phase: 'prepare',
+    committedMessages: [...messages],
+    roundCheckpoint: [...messages],
+    iteration: 0,
+    transientAttempts: 0,
+    partial: {
+        reasoning: '',
+        draft: '',
+    },
+    pendingToolCalls: [],
+    autokickAttempts: 0,
+    autokickKickAttempts: 0,
+});

package/vendor/common-nodes/dist/ai/features/llm-loop/normalize-llm-recovery-policy.d.ts

@@ -0,0 +1,2 @@
+import { type LlmRecoveryPolicy } from './llm-loop-types.js';
+export declare const normalizeLlmRecoveryPolicy: (params: Readonly<Record<string, unknown>>) => LlmRecoveryPolicy;

package/vendor/common-nodes/dist/ai/features/llm-loop/normalize-llm-recovery-policy.js

@@ -0,0 +1,59 @@
+import { DEFAULT_AUTOKICK_USER_MESSAGE, DEFAULT_LLM_RECOVERY_POLICY, } from './llm-loop-types.js';
+const normalizePositiveInteger = (value, fallback, max) => {
+    const number = typeof value === 'number' ? value : Number(value);
+    if (!Number.isFinite(number) || number < 0) {
+        return fallback;
+    }
+    return Math.min(max, Math.floor(number));
+};
+const normalizeBoolean = (value, fallback) => typeof value === 'boolean' ? value : fallback;
+const normalizePenalty = (value, fallback) => {
+    const number = typeof value === 'number' ? value : Number(value);
+    if (!Number.isFinite(number)) {
+        return fallback;
+    }
+    return Math.min(2, Math.max(-2, number));
+};
+const readRecord = (value) => value !== null && typeof value === 'object' && !Array.isArray(value)
+    ? value
+    : undefined;
+const nestedDeadLoop = (params) => readRecord(params['deadLoop']) ?? {};
+const nestedPenalty = (params) => readRecord(params['autokickPenaltyDelta']) ?? {};
+export const normalizeLlmRecoveryPolicy = (params) => {
+    const deadLoop = nestedDeadLoop(params);
+    const penalty = nestedPenalty(params);
+    const autokickBackoffMs = Math.max(1_000, normalizePositiveInteger(params['autokickBackoffMs'], DEFAULT_LLM_RECOVERY_POLICY.autokickBackoffMs, 3_600_000));
+    const autokickMaxBackoffMs = Math.max(autokickBackoffMs, normalizePositiveInteger(params['autokickMaxBackoffMs'], DEFAULT_LLM_RECOVERY_POLICY.autokickMaxBackoffMs, 3_600_000));
+    const kick = typeof params['autokickUserMessage'] === 'string' &&
+        params['autokickUserMessage'].trim().length > 0
+        ? params['autokickUserMessage'].trim()
+        : DEFAULT_AUTOKICK_USER_MESSAGE;
+    return {
+        streamIdleTimeoutMs: normalizePositiveInteger(params['streamIdleTimeoutMs'], DEFAULT_LLM_RECOVERY_POLICY.streamIdleTimeoutMs, 3_600_000),
+        toolTimeoutMs: normalizePositiveInteger(params['toolTimeoutMs'], DEFAULT_LLM_RECOVERY_POLICY.toolTimeoutMs, 3_600_000),
+        subagentTimeoutMs: normalizePositiveInteger(params['subagentTimeoutMs'], DEFAULT_LLM_RECOVERY_POLICY.subagentTimeoutMs, 86_400_000),
+        maxTransientRetries: normalizePositiveInteger(params['maxTransientRetries'], DEFAULT_LLM_RECOVERY_POLICY.maxTransientRetries, 10),
+        retryBaseDelayMs: normalizePositiveInteger(params['retryBaseDelayMs'], DEFAULT_LLM_RECOVERY_POLICY.retryBaseDelayMs, 60_000),
+        maxToolResultChars: normalizePositiveInteger(params['maxToolResultChars'], DEFAULT_LLM_RECOVERY_POLICY.maxToolResultChars, 1_000_000),
+        autokickOnIdle: normalizeBoolean(params['autokickOnIdle'], DEFAULT_LLM_RECOVERY_POLICY.autokickOnIdle),
+        deadLoopEnabled: normalizeBoolean(params['deadLoopEnabled'], DEFAULT_LLM_RECOVERY_POLICY.deadLoopEnabled),
+        maxAutokickAttempts: normalizePositiveInteger(params['maxAutokickAttempts'], DEFAULT_LLM_RECOVERY_POLICY.maxAutokickAttempts, 1_000),
+        autokickBackoffMs,
+        autokickMaxBackoffMs,
+        autokickUserMessage: kick,
+        autokickPenaltyDelta: {
+            frequency: normalizePenalty(penalty['frequency'] ?? params['autokickPenaltyFrequency'], DEFAULT_LLM_RECOVERY_POLICY.autokickPenaltyDelta.frequency),
+            presence: normalizePenalty(penalty['presence'] ?? params['autokickPenaltyPresence'], DEFAULT_LLM_RECOVERY_POLICY.autokickPenaltyDelta.presence),
+        },
+        deadLoop: {
+            maxWindowTokens: Math.min(8_000, Math.max(10, normalizePositiveInteger(deadLoop['maxWindowTokens'] ??
+                params['deadLoopMaxWindowTokens'], DEFAULT_LLM_RECOVERY_POLICY.deadLoop.maxWindowTokens, 8_000))),
+            consecutiveThreshold: Math.max(1, normalizePositiveInteger(deadLoop['consecutiveThreshold'] ??
+                params['deadLoopConsecutiveThreshold'], DEFAULT_LLM_RECOVERY_POLICY.deadLoop.consecutiveThreshold, 100)),
+            minRepetitions: Math.max(1, normalizePositiveInteger(deadLoop['minRepetitions'] ??
+                params['deadLoopMinRepetitions'], DEFAULT_LLM_RECOVERY_POLICY.deadLoop.minRepetitions, 20)),
+            minPatternTokens: Math.max(1, normalizePositiveInteger(deadLoop['minPatternTokens'] ??
+                params['deadLoopMinPatternTokens'], DEFAULT_LLM_RECOVERY_POLICY.deadLoop.minPatternTokens, 100)),
+        },
+    };
+};

package/vendor/common-nodes/dist/ai/features/llm-loop/operators/normalize-tool-result.d.ts

@@ -0,0 +1 @@
+export declare const normalizeToolResult: (text: string, maxChars: number) => string;

package/vendor/common-nodes/dist/ai/features/llm-loop/operators/normalize-tool-result.js

@@ -0,0 +1,7 @@
+export const normalizeToolResult = (text, maxChars) => {
+    if (maxChars <= 0 || text.length <= maxChars) {
+        return text;
+    }
+    const omitted = text.length - maxChars;
+    return `${text.slice(0, maxChars)}\n\n[tool result truncated: ${omitted} characters omitted]`;
+};

package/vendor/common-nodes/dist/ai/features/llm-loop/operators/observe-provider-stream.d.ts

@@ -0,0 +1,43 @@
+import type { SteerControlPayload } from '@langflower/node-sdk/llm';
+import { type Observable } from 'rxjs';
+import type { ChatCompletionFinishReason, ChatCompletionStreamChunk, ChatCompletionToolCall } from '../../chat-completion-stream.js';
+import { type DeadLoopChannel, type DeadLoopDetectorOptions } from '../dead-loop-detector.js';
+import type { LlmFailure } from '../llm-loop-types.js';
+export type ProviderStreamFact = {
+    readonly kind: 'provider.reasoning';
+    readonly text: string;
+} | {
+    readonly kind: 'provider.draft';
+    readonly text: string;
+} | {
+    readonly kind: 'provider.done';
+    readonly text: string;
+    readonly toolCalls?: readonly ChatCompletionToolCall[];
+    readonly finishReason?: ChatCompletionFinishReason;
+} | {
+    readonly kind: 'provider.paused';
+} | {
+    readonly kind: 'provider.idle';
+    readonly idleMs: number;
+} | {
+    readonly kind: 'provider.dead-loop';
+    readonly channel: DeadLoopChannel;
+    readonly reason: 'consecutive' | 'cyclic';
+} | {
+    readonly kind: 'provider.failed';
+    readonly failure: LlmFailure;
+};
+export type ObserveProviderStreamOptions = {
+    readonly createStream: (signal: AbortSignal) => Promise<AsyncIterable<ChatCompletionStreamChunk>>;
+    readonly pause$: Observable<SteerControlPayload>;
+    readonly cancel$: Observable<void>;
+    readonly idleTimeoutMs: number;
+    readonly onAbort?: () => void;
+    readonly deadLoop?: DeadLoopDetectorOptions | false;
+};
+/**
+ * Convert the provider AsyncIterable into typed, cancellable RxJS facts.
+ * Pause, idle, and dead-loop are terminal for one provider attempt, not
+ * terminal for the surrounding LLM loop.
+ */
+export declare const observeProviderStream: (options: ObserveProviderStreamOptions) => Observable<ProviderStreamFact>;

package/vendor/common-nodes/dist/ai/features/llm-loop/operators/observe-provider-stream.js

@@ -0,0 +1,96 @@
+import { isSteerControlPause } from '@langflower/node-sdk/llm';
+import { catchError, concatMap, defer, endWith, filter, finalize, from, map, merge, of, switchMap, take, takeUntil, takeWhile, tap, timeout, } from 'rxjs';
+import { classifyLlmFailure } from '../classify-llm-failure.js';
+import { createDeadLoopDetector, } from '../dead-loop-detector.js';
+const toProviderStreamFact = (chunk) => {
+    switch (chunk.kind) {
+        case 'reasoning':
+            return { kind: 'provider.reasoning', text: chunk.text };
+        case 'draft':
+            return { kind: 'provider.draft', text: chunk.text };
+        case 'done':
+            return {
+                kind: 'provider.done',
+                text: chunk.text,
+                ...(chunk.tool_calls !== undefined
+                    ? { toolCalls: chunk.tool_calls }
+                    : {}),
+                ...(chunk.finishReason !== undefined
+                    ? { finishReason: chunk.finishReason }
+                    : {}),
+            };
+    }
+};
+const isTerminalProviderFact = (fact) => fact.kind === 'provider.done' ||
+    fact.kind === 'provider.paused' ||
+    fact.kind === 'provider.idle' ||
+    fact.kind === 'provider.dead-loop' ||
+    fact.kind === 'provider.failed';
+const withIdleTimeout = (source$, idleTimeoutMs, onIdle) => {
+    if (idleTimeoutMs <= 0) {
+        return source$;
+    }
+    return source$.pipe(timeout({
+        first: idleTimeoutMs,
+        each: idleTimeoutMs,
+        with: () => {
+            onIdle();
+            return of({
+                kind: 'provider.idle',
+                idleMs: idleTimeoutMs,
+            });
+        },
+    }));
+};
+const guardDeadLoop = (fact, detectors, abort) => {
+    if (detectors === undefined ||
+        (fact.kind !== 'provider.reasoning' && fact.kind !== 'provider.draft')) {
+        return of(fact);
+    }
+    const channel = fact.kind === 'provider.reasoning' ? 'reasoning' : 'draft';
+    const detected = detectors[channel].push(fact.text);
+    if (detected.ok) {
+        return of(fact);
+    }
+    abort();
+    return of(fact, {
+        kind: 'provider.dead-loop',
+        channel: detected.error.channel,
+        reason: detected.error.reason,
+    });
+};
+/**
+ * Convert the provider AsyncIterable into typed, cancellable RxJS facts.
+ * Pause, idle, and dead-loop are terminal for one provider attempt, not
+ * terminal for the surrounding LLM loop.
+ */
+export const observeProviderStream = (options) => defer(() => {
+    const abort = new AbortController();
+    const stopProvider = () => {
+        abort.abort();
+        options.onAbort?.();
+    };
+    const detectors = options.deadLoop === false
+        ? undefined
+        : {
+            reasoning: createDeadLoopDetector('reasoning', options.deadLoop ?? {}),
+            draft: createDeadLoopDetector('draft', options.deadLoop ?? {}),
+        };
+    const pause$ = options.pause$.pipe(filter(isSteerControlPause), take(1), tap(() => {
+        stopProvider();
+    }), map(() => ({ kind: 'provider.paused' })));
+    const chunks$ = withIdleTimeout(from(options.createStream(abort.signal)).pipe(switchMap((stream) => from(stream)), concatMap((chunk) => guardDeadLoop(toProviderStreamFact(chunk), detectors, stopProvider)), catchError((error) => of({
+        kind: 'provider.failed',
+        failure: classifyLlmFailure(error),
+    })), endWith({
+        kind: 'provider.failed',
+        failure: {
+            kind: 'protocol',
+            message: 'Provider stream completed without a done chunk.',
+            recoverable: true,
+        },
+    })), options.idleTimeoutMs, stopProvider);
+    return merge(chunks$, pause$).pipe(takeWhile((fact) => !isTerminalProviderFact(fact), true), takeUntil(options.cancel$), finalize(() => {
+        stopProvider();
+    }));
+});

package/vendor/common-nodes/dist/ai/features/llm-loop/run-agent-loop.d.ts

@@ -0,0 +1,32 @@
+import type { ToolHandle } from '@langflower/node-sdk';
+import type { SteerControlPayload } from '@langflower/node-sdk/llm';
+import type { Harness } from '@langflower/tools/create-project-harness';
+import type { ToolHandlerContext } from '@langflower/tools/domain-tool-configs';
+import type { PermissionAskRequest } from '@langflower/tools/permission';
+import type { Observable } from 'rxjs';
+import type { ChatCompletionMessage, CreateChatCompletionStream } from '../chat-completion-stream.js';
+import type { SubAgentRegistration } from '../sub-agent-protocol.js';
+import type { LlmCompactionConfig } from '../openai/normalize-compaction-params.js';
+import { type LlmRecoveryPolicy } from './llm-loop-types.js';
+import { type SharedLlmLoopChunk } from './run-llm-loop.js';
+export type ToolLoopChunk = SharedLlmLoopChunk | {
+    readonly kind: 'response';
+    readonly text: string;
+};
+export declare const runAgentLoop: (args: {
+    readonly factory: CreateChatCompletionStream;
+    readonly providerId: string;
+    readonly model: string;
+    readonly messages: readonly ChatCompletionMessage[];
+    readonly tools: readonly ToolHandle[];
+    readonly getTools?: () => readonly ToolHandle[];
+    readonly harness?: Harness;
+    readonly toolCtx?: ToolHandlerContext;
+    readonly maxIterations: number;
+    readonly subagentRegistrations?: readonly SubAgentRegistration[];
+    readonly compaction?: LlmCompactionConfig;
+    readonly recovery?: LlmRecoveryPolicy;
+    readonly requestPermission?: (request: PermissionAskRequest) => Promise<"allow" | "deny">;
+    readonly waitForSubagentResult?: (callId: string, signal: AbortSignal) => Promise<string>;
+    readonly steerControl$?: Observable<SteerControlPayload>;
+}) => Observable<ToolLoopChunk>;

package/vendor/common-nodes/dist/ai/features/llm-loop/run-agent-loop.js

@@ -0,0 +1,58 @@
+import { buildSpawnSubagentChatTool, toChatToolDefinitions, } from '../../../tools/inventory-tool-round.js';
+import { DISABLED_COMPACTION_CONFIG } from '../openai/normalize-compaction-params.js';
+import { DEFAULT_LLM_RECOVERY_POLICY, } from './llm-loop-types.js';
+import { runLlmLoop, } from './run-llm-loop.js';
+const AGENT_LOOP_POLICY = {
+    decideCompletion: ({ text, toolCalls }) => toolCalls.length > 0
+        ? { kind: 'run-tools', calls: toolCalls }
+        : {
+            kind: 'complete',
+            chunks: [{ kind: 'response', text }],
+        },
+    maxIterationsFailure: (maxIterations) => {
+        const text = `Stopped after ${maxIterations} tool-loop iterations ` +
+            '(maxIterations).';
+        return {
+            kind: 'complete',
+            chunks: [
+                { kind: 'toolLog', text },
+                { kind: 'response', text },
+            ],
+        };
+    },
+};
+export const runAgentLoop = (args) => {
+    const subagentRegistrations = args.subagentRegistrations ?? [];
+    return runLlmLoop({
+        factory: args.factory,
+        providerId: args.providerId,
+        model: args.model,
+        messages: args.messages,
+        chatTools: [
+            ...toChatToolDefinitions(args.tools),
+            ...(subagentRegistrations.length > 0
+                ? [buildSpawnSubagentChatTool(subagentRegistrations)]
+                : []),
+        ],
+        inventoryTools: args.tools,
+        ...(args.getTools !== undefined ? { getTools: args.getTools } : {}),
+        maxIterations: args.maxIterations,
+        compaction: args.compaction ?? DISABLED_COMPACTION_CONFIG,
+        recovery: args.recovery ?? DEFAULT_LLM_RECOVERY_POLICY,
+        policy: AGENT_LOOP_POLICY,
+        subagentRegistrations,
+        ...(args.harness !== undefined ? { harness: args.harness } : {}),
+        ...(args.toolCtx !== undefined ? { toolCtx: args.toolCtx } : {}),
+        ...(args.requestPermission !== undefined
+            ? { requestPermission: args.requestPermission }
+            : {}),
+        ...(args.waitForSubagentResult !== undefined
+            ? {
+                waitForSubagentResult: args.waitForSubagentResult,
+            }
+            : {}),
+        ...(args.steerControl$ !== undefined
+            ? { steerControl$: args.steerControl$ }
+            : {}),
+    });
+};

package/vendor/common-nodes/dist/ai/features/llm-loop/run-llm-loop.d.ts

@@ -0,0 +1,80 @@
+import type { ToolHandle } from '@langflower/node-sdk';
+import { type LlmRecoveryNotice, type SteerControlPayload } from '@langflower/node-sdk/llm';
+import type { Harness } from '@langflower/tools/create-project-harness';
+import type { ToolHandlerContext } from '@langflower/tools/domain-tool-configs';
+import type { PermissionAskRequest } from '@langflower/tools/permission';
+import { type Observable } from 'rxjs';
+import type { ChatCompletionMessage, ChatCompletionToolCall, ChatCompletionToolDefinition, CreateChatCompletionStream } from '../chat-completion-stream.js';
+import type { SubAgentRegistration, SubAgentSpawnPayload } from '../sub-agent-protocol.js';
+import type { LlmCompactionConfig } from '../openai/normalize-compaction-params.js';
+import { type LlmFailure, type LlmLoopState, type LlmRecoveryPolicy } from './llm-loop-types.js';
+export type SharedLlmLoopChunk = {
+    readonly kind: 'reasoning';
+    readonly text: string;
+} | {
+    readonly kind: 'draftResponse';
+    readonly text: string;
+} | {
+    readonly kind: 'toolLog';
+    readonly text: string;
+} | ({
+    readonly kind: 'recoveryNotice';
+} & LlmRecoveryNotice) | {
+    readonly kind: 'historySync';
+    readonly messages: readonly ChatCompletionMessage[];
+} | {
+    readonly kind: 'subagentSpawn';
+    readonly payload: SubAgentSpawnPayload;
+};
+type LlmCompletionDecision<Chunk> = {
+    readonly kind: 'complete';
+    readonly chunks: readonly Chunk[];
+} | {
+    readonly kind: 'run-tools';
+    readonly calls: readonly ChatCompletionToolCall[];
+} | {
+    readonly kind: 'continue';
+    readonly messages: readonly ChatCompletionMessage[];
+    readonly chunks: readonly Chunk[];
+} | {
+    readonly kind: 'fail';
+    readonly failure: LlmFailure;
+};
+export type LlmLoopPolicy<Chunk> = {
+    readonly decideCompletion: (input: {
+        readonly state: LlmLoopState;
+        readonly text: string;
+        readonly toolCalls: readonly ChatCompletionToolCall[];
+    }) => LlmCompletionDecision<Chunk>;
+    readonly toolNotAllowedText?: (toolName: string) => string;
+    readonly maxIterationsFailure: (maxIterations: number) => LlmCompletionDecision<Chunk>;
+};
+export type RunLlmLoopOptions<Chunk> = {
+    readonly factory: CreateChatCompletionStream;
+    readonly providerId: string;
+    readonly model: string;
+    readonly messages: readonly ChatCompletionMessage[];
+    readonly chatTools: readonly ChatCompletionToolDefinition[];
+    readonly inventoryTools: readonly ToolHandle[];
+    readonly getTools?: () => readonly ToolHandle[];
+    readonly harness?: Harness;
+    readonly toolCtx?: ToolHandlerContext;
+    readonly maxIterations: number;
+    readonly compaction: LlmCompactionConfig;
+    readonly recovery: LlmRecoveryPolicy;
+    readonly policy: LlmLoopPolicy<Chunk>;
+    /**
+     * When set, maxIterations exhaustion asks HITL continue instead of
+     * immediately applying {@link LlmLoopPolicy.maxIterationsFailure}.
+     */
+    readonly requestPermission?: (request: PermissionAskRequest) => Promise<'allow' | 'deny'>;
+    readonly steerControl$?: Observable<SteerControlPayload>;
+    readonly subagentRegistrations?: readonly SubAgentRegistration[];
+    readonly waitForSubagentResult?: (callId: string, signal: AbortSignal) => Promise<string>;
+};
+/**
+ * One reactive state machine for provider, tool, Sub-Agent, retry, and Steer
+ * phases. Policy owns only the semantic completion decision.
+ */
+export declare const runLlmLoop: <Chunk>(options: RunLlmLoopOptions<Chunk>) => Observable<Chunk | SharedLlmLoopChunk>;
+export {};