@vincemakes/kiso-core 0.1.0

package/dist/kernel/loop.d.ts

@@ -0,0 +1,97 @@
+/**
+ * L2 — the ReAct loop. The kernel's only loop; everything else is harness.
+ *
+ * An async generator that yields every event as it happens (never buffers a
+ * turn into a list — the agno failure), and converges on exactly one
+ * `terminal` event per run (ADR-0004).
+ *
+ * SINGLE TRUTH (Phase B): the loop holds ONE EventLog. Messages are never
+ * stored alongside it — every adapter call derives them via
+ * `projectMessages(log.all)` (kernel/project.ts). A fresh log encodes the
+ * seed `messages` into events first, so even a one-shot call replays
+ * exactly. Compaction is recorded as a `compacted` event and re-applied by
+ * the projection, keeping the replay identical to the live run.
+ *
+ * Per iteration:
+ *   assemble (onUserMessage / onPreLlm)
+ *     → adapter.stream(): events yielded straight through, tool calls collected
+ *     → execute: validation → permission (onPreTool) → handler → rewrite
+ *       (onPostTool), concurrency-safe calls batched parallel, the rest serial
+ *     → tool_result events appended
+ *   no tool calls / maxTurns / abort / max_tokens → terminal event, return
+ *
+ * Retry lives HERE and only here (ADR-0005): a retryable StructuredError
+ * from the adapter is retried with backoff inside the generator frame — and
+ * ONLY before anything streamed (Phase B): once a text delta or tool call
+ * left the adapter, a failure is an `error` terminal, never a silent
+ * re-stream that duplicates output or tool calls.
+ */
+import { type Adapter, type AbortSignalLike } from "../protocol/adapter.js";
+import type { Event, StructuredError } from "../protocol/events.js";
+import { EventLog } from "./event-log.js";
+import type { EventInput } from "./event-log.js";
+import type { AssistantBlock, AssistantMessage, Message, ToolResultMessage } from "../protocol/messages.js";
+import { ToolRegistry } from "../tools/registry.js";
+import type { HookHost } from "./hooks.js";
+import type { ModeProfile } from "./mode.js";
+import { type PermissionDecision } from "./permission.js";
+export interface LoopConfig {
+    readonly adapter: Adapter;
+    readonly model: string;
+    readonly systemPrompt?: string;
+    readonly registry: ToolRegistry;
+    readonly hooks?: HookHost;
+    readonly modes?: readonly ModeProfile[];
+    /** Active mode name; applies visibleToolNames structurally. */
+    readonly mode?: string;
+    readonly maxTurns?: number;
+    readonly maxRetries?: number;
+    /**
+     * Seed history. When a `log` is provided, the log IS the truth and this
+     * is only used if the log is empty. See ADR-0002 / kernel/project.ts.
+     */
+    readonly messages?: readonly Message[];
+    /** The run's event log. Pass the session's log to make this run durable. */
+    readonly log?: EventLog;
+    /** Auto-compaction: when the estimated context exceeds the threshold,
+     *  microcompact old tool results before the next model call. */
+    readonly compaction?: {
+        readonly thresholdTokens: number;
+    };
+    readonly signal?: AbortSignalLike;
+    readonly temperature?: number;
+    readonly maxTokens?: number;
+    /**
+     * Phase D: the channel that resolves a `defer` permission. When the
+     * onPreTool hook defers, the loop persists a `permission_requested`
+     * event, yields it, and AWAITS this promise — the same run resumes when
+     * a human decides. Absent, a defer degrades to an honest denial.
+     */
+    readonly resolveApproval?: (decisionId: string) => Promise<PermissionDecision>;
+    /**
+     * 第四轮(对抗): a verdict the human ALREADY gave before an abort landed.
+     * The abort path consults this BEFORE yielding the aborted terminal: a
+     * consumed verdict must be recorded (exactly once), never lost — the
+     * human's decision outranks the abort.
+     */
+    readonly approvalVerdict?: (decisionId: string) => boolean | undefined;
+    /**
+     * C 组: the channel that resolves a failed NON-idempotent execution.
+     * The loop persists `uncertain_pending`, yields it, and AWAITS the
+     * human verdict — no next model turn, no sibling tool, no auto-retry.
+     * Absent, the failure is recorded `abandoned` (never retried).
+     */
+    readonly resolveUncertainty?: (executionId: string) => Promise<"rerun" | "abandoned">;
+    /** 第四轮(对抗): the uncertainty twin of `approvalVerdict`. */
+    readonly uncertaintyVerdict?: (executionId: string) => "rerun" | "abandoned" | undefined;
+}
+export declare const DEFAULT_MAX_TURNS = 10;
+export declare const DEFAULT_MAX_RETRIES = 2;
+export declare function loop(config: LoopConfig): AsyncGenerator<Event>;
+/**
+ * Adapter exceptions → StructuredError. Anything already shaped like one
+ * passes through; everything else is `unknown` — never a regex over error
+ * text (ADR-0005).
+ */
+export declare function toStructuredError(err: unknown): StructuredError;
+export type { EventInput, AssistantBlock, AssistantMessage, Message, ToolResultMessage };