dsh-continual-evolve 0.15.11 → 0.15.13

package/lib/extraction.js

@@ -1,26 +1,30 @@
-import { boundaryCursorOf, evaluateSlice, eventsAfterCursor, isInternalAgent, seqOfCursor, serializeIncrement } from "./extraction-surface.js";
-import { CHEAP_INCREMENT_MAX, EXTRACTION_CHEAP_SYSTEM_PROMPT, EXTRACTION_SYSTEM_PROMPT, cheapPrompt, extractionPrompt, manifestLineOf, parseCheapAnswer, parseExtractionAnswer } from "./extraction-prompt.js";
+/**
+ * The extraction pipeline (the v0.15 proposal-based write path B): one
+ * bounded increment of one session, one LLM call, one gated transactional
+ * application, one ledger row, one cursor.
+ *
+ * Trigger economics follow ZCode's memory-extraction scheduler: turn-level
+ * (every `agent/turn-stopping` schedules that session's boundary), no idle
+ * timer, and state per session — a session with a run in flight keeps only
+ * its newest boundary, which the run drains when it finishes (coalescing,
+ * not queueing); `compaction/start` and session close drain immediately.
+ * Per-session slots mean one workspace's turns can never delay or displace
+ * another's extraction. Everything the pipeline decides mechanically
+ * (internal agent, empty increment, no real user prose, an explicit
+ * `memory_write` this turn) is skipped AND ledgered — the extraction_log is
+ * the account the economics are audited against. Consecutive repeats of one
+ * session's quiet-turn skip share a single row there, counted in
+ * `occurrences` (see `store.ts`), so the account stays readable at volume.
+ *
+ * This module owns the entry, the failure net, and the scheduler; the pass
+ * itself is a responsibility chain (`extraction-ring.ts`) the entry assembles.
+ * The model proposes; the store disposes. A failed or rejected run never
+ * advances the cursor, so the increment is retried on the next trigger.
+ */
+import { ERROR_REASON_MAX, errorText, runExtractionInner } from "./extraction-ring.js";
+import { isInternalAgent } from "./extraction-surface.js";
 import { cwdOf } from "./memory-section.js";
-/** Head length of a failed run's raw answer kept in the ledger `files` column. */
-const FAILURE_RAW_MAX = 2048;
-/** Head length of an unexpected error's message/stack trace kept in the ledger `files` column. */
-const UNEXPECTED_ERROR_RAW_MAX = 2048;
-/** Head length of an error message embedded in a ledger `skip_reason`. */
-const ERROR_REASON_MAX = 300;
-/** Head length of a failed pre-gate call's error kept in the ledger `cheap_error` column. */
-const GATE_ERROR_MAX = 200;
-/** Output budget for one cheap-gate call (see review.ts's `GATE_MAX_TOKENS`). */
-const GATE_MAX_TOKENS = 1024;
-/** Split an unexpected throw into a ledger-sized reason head and file body. */
-function errorText(error) {
-    const message = error instanceof Error && error.message.length > 0 ? error.message : String(error);
-    const stack = error instanceof Error && typeof error.stack === "string" ? error.stack : message;
-    return { message, detail: `${message}\n${stack}`.slice(0, UNEXPECTED_ERROR_RAW_MAX) };
-}
-/** One-line head of a thrown pre-gate error (flat, so the column stays greppable). */
-function errorHead(error) {
-    return errorText(error).message.replace(/\s+/g, " ").trim().slice(0, GATE_ERROR_MAX);
-}
+import { resolveCallRoute } from "./llm-call.js";
 /**
  * Run one extraction pass for a target. Never throws unless the ledger
  * itself is unwritable: every terminal path is either a landed application,
@@ -57,237 +61,6 @@ export async function runExtraction(deps, target, opts) {
         return { status: "failed", skipReason: reason };
     }
 }
-/**
- * The pipeline body: one bounded increment of one session, one LLM call, one
- * gated transactional application, one ledger row, one cursor.
- */
-async function runExtractionInner(deps, target, opts) {
-    const { store } = deps;
-    const ledgerBase = {
-        sessionId: target.sessionId,
-        workspaceId: target.workspaceId,
-        trigger: opts.trigger,
-    };
-    if (target.internalAgent) {
-        store.logSkipped({ ...ledgerBase, skipReason: "internal-agent", status: "skipped" });
-        return { status: "skipped", skipReason: "internal-agent" };
-    }
-    if (target.workspaceId === undefined) {
-        store.logSkipped({ ...ledgerBase, skipReason: "no-workspace", status: "skipped" });
-        return { status: "skipped", skipReason: "no-workspace" };
-    }
-    if (deps.surface === undefined) {
-        store.logSkipped({ ...ledgerBase, skipReason: "no-surface", status: "skipped" });
-        return { status: "skipped", skipReason: "no-surface" };
-    }
-    if (target.provider === undefined || target.model === undefined || deps.llm === undefined) {
-        store.logSkipped({ ...ledgerBase, skipReason: "no-route", status: "skipped" });
-        return { status: "skipped", skipReason: "no-route" };
-    }
-    const cursor = store.cursor(target.workspaceId, target.sessionId);
-    let all;
-    try {
-        const snapshot = await deps.surface.readSurface(target.sessionId);
-        all = Array.isArray(snapshot.events) ? snapshot.events : [];
-    }
-    catch (error) {
-        const { message, detail } = errorText(error);
-        try {
-            store.logSkipped({ ...ledgerBase, skipReason: "surface-read-failed", status: "failed", files: detail });
-        }
-        catch (ledgerError) {
-            throw new Error(`surface read failed (${message}); failure ledger write also failed (${errorText(ledgerError).message})`);
-        }
-        return { status: "failed", skipReason: `surface read failed: ${message}` };
-    }
-    const events = eventsAfterCursor(all, cursor === undefined ? undefined : `seq:${cursor}`);
-    const slice = evaluateSlice({ events, internalAgent: false });
-    if (!slice.eligible) {
-        store.logSkipped({ ...ledgerBase, skipReason: slice.skipReason, status: "skipped" });
-        return { status: "skipped", skipReason: slice.skipReason };
-    }
-    const boundary = boundaryCursorOf(all);
-    const boundarySeq = seqOfCursor(boundary);
-    const workspaceId = target.workspaceId;
-    const advanceCursor = () => {
-        if (boundarySeq !== undefined) {
-            store.setCursor(workspaceId, target.sessionId, boundarySeq);
-        }
-    };
-    const increment = serializeIncrement(slice.events, opts.incrementMaxChars);
-    // ── Cheap pre-gate: a small verdict before the expensive full call
-    // (manifest + full-body candidates + full increment). A "not worth it"
-    // consumes the increment exactly like a model skip; an unclear gate
-    // (unparseable/failed) fails OPEN to the full call — worst case degrades
-    // to the old single-call behavior, never to a stall. A gate that dies
-    // still rides the run's own ledger row as `cheap_error`: without it a
-    // failed gate is indistinguishable from a gate that never existed, which
-    // is how a 512-token budget truncating every call on a reasoning model
-    // stayed invisible.
-    let cheapUsage;
-    let cheapError;
-    {
-        const gateStarted = Date.now();
-        try {
-            const gate = await streamOnce(deps.llm, target, cheapPrompt({ incrementHead: increment.slice(0, CHEAP_INCREMENT_MAX), userSeqs: slice.userSeqs }), EXTRACTION_CHEAP_SYSTEM_PROMPT, GATE_MAX_TOKENS);
-            cheapUsage = gate.usage;
-            const verdict = parseCheapAnswer(gate.text);
-            // A gate cut at its budget that still answered is a usable verdict;
-            // only a cut with nothing parseable rides the run's row as a gate
-            // error. Parse before blaming the finish reason.
-            if (verdict === null && gate.finish !== undefined && gate.finish !== "stop") {
-                throw new Error(`stream finished with ${gate.finish}`);
-            }
-            if (verdict !== null && !verdict.worth) {
-                advanceCursor();
-                store.logSkipped({
-                    ...ledgerBase,
-                    skipReason: `model-skip (cheap-gate): ${verdict.reason}`,
-                    status: "skipped",
-                    model: target.model,
-                    cheapUsage,
-                    durationMs: Date.now() - gateStarted,
-                });
-                return { status: "skipped", skipReason: verdict.reason, cursor: boundarySeq };
-            }
-        }
-        catch (error) {
-            // Fail open: the full call below is the old behavior. The error
-            // head is kept for the run's own row (never a row of its own, so
-            // one run stays one ledger row).
-            cheapError = errorHead(error);
-        }
-    }
-    const manifest = store.list(target.workspaceId).slice(0, 50).map(manifestLineOf);
-    const candidates = candidateRecords(store, target.workspaceId, slice.userText);
-    const prompt = extractionPrompt({
-        increment,
-        manifest,
-        candidates: candidates.map(formatCandidate),
-        userSeqs: slice.userSeqs,
-    });
-    const started = Date.now();
-    let text;
-    let usage;
-    try {
-        const answer = await streamOnce(deps.llm, target, prompt);
-        // The full call carries the proposal payload: a cut stream is a failure.
-        if (answer.finish !== undefined && answer.finish !== "stop") {
-            throw new Error(`stream finished with ${answer.finish}`);
-        }
-        text = answer.text;
-        usage = answer.usage;
-    }
-    catch (error) {
-        const { message, detail } = errorText(error);
-        try {
-            store.logSkipped({ ...ledgerBase, skipReason: "llm-failed", status: "failed", durationMs: Date.now() - started, cheapUsage, cheapError, files: detail });
-        }
-        catch (ledgerError) {
-            throw new Error(`llm call failed (${message}); failure ledger write also failed (${errorText(ledgerError).message})`);
-        }
-        return { status: "failed", skipReason: `llm call failed: ${message}` };
-    }
-    const parsed = parseExtractionAnswer(text);
-    if (parsed.decision === "error") {
-        // A malformed answer is a failed run: the increment stays unconsumed
-        // and the next trigger retries it. The answer's head rides in the
-        // ledger row — the stream is gone after this, so without it the
-        // failure is undiagnosable after the fact.
-        store.logSkipped({
-            ...ledgerBase,
-            skipReason: parsed.reason,
-            status: "failed",
-            model: target.model,
-            usage,
-            cheapUsage,
-            cheapError,
-            durationMs: Date.now() - started,
-            files: text.slice(0, FAILURE_RAW_MAX),
-        });
-        return { status: "failed", skipReason: parsed.reason };
-    }
-    if (parsed.decision === "skip") {
-        // A real model decision (even "nothing worth keeping") consumed the
-        // increment — advancing the cursor here is what keeps retries honest.
-        advanceCursor();
-        store.logSkipped({
-            ...ledgerBase,
-            skipReason: `model-skip: ${parsed.reason}`,
-            status: "skipped",
-            model: target.model,
-            usage,
-            cheapUsage,
-            cheapError,
-            durationMs: Date.now() - started,
-        });
-        return { status: "skipped", skipReason: parsed.reason, cursor: boundarySeq };
-    }
-    const outcomes = store.applyProposals({
-        workspaceId: target.workspaceId,
-        trigger: opts.trigger,
-        sessionId: target.sessionId,
-        runId: `extract:${target.sessionId}:${boundarySeq ?? "tail"}`,
-        model: target.model,
-        usage,
-        cheapUsage,
-        cheapError,
-        decision: parsed.reason,
-    }, parsed.proposals);
-    if (!outcomes.every((outcome) => outcome.ok)) {
-        return { status: "rejected", skipReason: outcomes.find((outcome) => !outcome.ok)?.reason };
-    }
-    advanceCursor();
-    // Hygiene rides on every applied run: orphan FTS rows dropped, secret
-    // leakage quarantined — never a separate scheduler.
-    const patrol = store.patrol();
-    void patrol;
-    return { status: "applied", applied: outcomes.filter((outcome) => outcome.ok).length, cursor: boundarySeq };
-}
-/** Similar existing memories (full bodies) for the model to update against. */
-function candidateRecords(store, workspaceId, userText) {
-    const query = userText.split("\n")[0]?.slice(0, 100).trim() ?? "";
-    const hits = query.length >= 3 ? store.search(workspaceId, query, 8) : [];
-    return hits.length > 0 ? hits : store.list(workspaceId).slice(0, 8);
-}
-function formatCandidate(record) {
-    return [`# 候选 id=${record.id}（type=${record.type}）`, `title=${record.title}`, `钩子=${record.description}`, "全文：", record.body].join("\n");
-}
-/** One streaming text call with the host session identity forwarded. */
-async function streamOnce(llm, target, prompt, system = EXTRACTION_SYSTEM_PROMPT, maxTokens = 4096) {
-    let text = "";
-    let usage;
-    let finish;
-    const options = {
-        provider: target.provider,
-        model: target.model,
-        messages: [{ role: "user", content: [{ type: "text", text: prompt }] }],
-        system,
-        maxTokens,
-        // MissingSessionID pitfall: direct calls must carry the host session.
-        sessionId: target.sessionId,
-    };
-    for await (const chunk of llm.stream(options)) {
-        const piece = chunk;
-        if (piece?.type === "text-delta" && typeof piece.text === "string") {
-            text += piece.text;
-        }
-        else if (piece?.type === "usage") {
-            usage = piece.usage;
-        }
-        else if (piece?.type === "finish") {
-            finish = piece.reason;
-        }
-    }
-    const finishKind = finish?.kind;
-    if (text.trim().length === 0) {
-        // Nothing usable arrived: the finish reason is the only diagnosis.
-        throw new Error(finishKind !== undefined && finishKind !== "stop" ? `stream finished with ${finishKind}` : "empty model output");
-    }
-    // The caller owns the truncation verdict: a gate answer often completes
-    // before its budget does, a proposal body never does.
-    return { text, usage, finish: finishKind };
-}
 /**
  * Wire the extraction triggers onto the host context. Returns a disposer
  * that removes the listeners. The scheduler is the only background
@@ -310,12 +83,14 @@ export function createExtractionScheduler(host, deps) {
         if (typeof id !== "string" || id.length === 0) {
             return null;
         }
-        const route = agent?.options;
+        // Absent resolver (older host, tests) still reads the agent's explicit
+        // selection: the fallback is the legacy behavior, never "no route".
+        const route = deps.resolveRoute?.(agent) ?? resolveCallRoute(agent, undefined);
         return {
             agent,
             sessionId: id,
-            provider: typeof route?.provider === "string" ? route.provider : undefined,
-            model: typeof route?.model === "string" ? route.model : undefined,
+            provider: route?.provider,
+            model: route?.model,
         };
     };
     const drain = (sessionId, trigger) => {

package/lib/index.js

@@ -31,6 +31,7 @@
 import z from "@deepseek-ai/schemastery";
 import { mountCardRoutes } from "./card-routes.js";
 import { createExtractionScheduler } from "./extraction.js";
+import { resolveCallRoute } from "./llm-call.js";
 import { createReviewScheduler, REVIEW_DEFAULT_BATCH_SIZE, REVIEW_DEFAULT_DAILY_BUDGET, REVIEW_DEFAULT_DRY_RUN, REVIEW_DEFAULT_STALE_DAYS, } from "./review.js";
 import { createFrozenMemorySection, cwdOf, DEFAULT_MAX_CHARS, DEFAULT_MEMORY_SECTION_ORDER, MEMORY_SECTION_NAME, memorySectionText, } from "./memory-section.js";
 import { registerMemoryTools } from "./memory-tools.js";
@@ -87,6 +88,34 @@ export const Config = z.object({
         enabled: z.boolean(),
     }),
 });
+/**
+ * Build the route resolver a scheduler uses for its direct calls: the agent's
+ * explicit selection first, the host's default-model service second.
+ *
+ * The default-model service is read through `ctx.get` on every call and never
+ * joins an inject list — a host without it (or an older one) must keep working,
+ * and its absence only means a session with no explicit selection has no route.
+ */
+function routeResolverOf(scoped, get) {
+    if (typeof get !== "function") {
+        return undefined;
+    }
+    const read = get.bind(scoped);
+    return (agent) => resolveCallRoute(agent, read);
+}
+/**
+ * Keep one scheduler's disposer on the owning fiber.
+ *
+ * Without this a remount (HMR, a live config edit) leaves the previous
+ * listeners attached: two schedulers then drain the same boundary, and the
+ * older one holds an LLM service the remount already replaced.
+ */
+function registerSchedulerDisposer(scoped, dispose) {
+    const effect = scoped.effect;
+    if (typeof effect === "function") {
+        effect.call(scoped, () => dispose);
+    }
+}
 /** Register the memory tools through a nested inject (see memory-tools.ts). */
 function mountToolsWhenAvailable(host, store, state) {
     const nested = host;
@@ -134,7 +163,11 @@ function mountExtractionWhenAvailable(host, store, config) {
             log.warn("sessionQuery service present but empty — extraction not armed (injection and tools unaffected)");
             return;
         }
-        createExtractionScheduler(events, { store, surface, llm });
+        const resolveRoute = routeResolverOf(scoped, context.get);
+        registerSchedulerDisposer(scoped, createExtractionScheduler(events, {
+            store, surface, llm,
+            ...(resolveRoute === undefined ? {} : { resolveRoute }),
+        }));
     });
 }
 /**
@@ -158,7 +191,11 @@ function mountReviewWhenAvailable(host, store, config) {
     nested.inject(["llm"], (scoped) => {
         const context = scoped;
         const llm = (context.llm ?? context.get?.("llm"));
-        createReviewScheduler(events, { store, llm }, {
+        const resolveRoute = routeResolverOf(scoped, context.get);
+        registerSchedulerDisposer(scoped, createReviewScheduler(events, {
+            store, llm,
+            ...(resolveRoute === undefined ? {} : { resolveRoute }),
+        }, {
             enabled: true,
             read: () => ({
                 dryRun: config.review?.dryRun?.get() ?? REVIEW_DEFAULT_DRY_RUN,
@@ -167,7 +204,7 @@ function mountReviewWhenAvailable(host, store, config) {
                 staleDays: config.review?.staleDays?.get() ?? REVIEW_DEFAULT_STALE_DAYS,
             }),
             minIntervalMs: 5 * 60 * 1000,
-        });
+        }));
     });
 }
 /**

package/lib/llm-call.d.ts

@@ -0,0 +1,168 @@
+/**
+ * The transport for the plugin's own LLM calls. Every subagent call
+ * (`subagentDefs.ts` definitions loaded through `subagent.ts`) ends here.
+ *
+ * Four disciplines live in one place because all four were learned the hard
+ * way, and none of them is visible at a call site:
+ *
+ * - **The route.** `agent.options` carries an *explicit* selection only. A
+ *   session running on the host's default model carries nothing there, so the
+ *   route falls back to the host's `agentDefaultModel` service — the same
+ *   value the host Agent loop itself runs on. A caller that still has no
+ *   route refuses to send instead of streaming into a provider rejection.
+ * - **The reasoning effort.** An exact provider/model advertises the effort
+ *   ids it accepts, and a request naming one it does not accept is rejected
+ *   by capability validation before any provider I/O. The lowest *enabled*
+ *   effort the model advertises is used; a model with no reasoning metadata
+ *   gets no caller-supplied effort at all. This is the pre-teardown
+ *   `llm-text.ts` discipline (see the 2026-09-24 capability note), restored
+ *   after the direct calls that replaced that boundary shipped without it.
+ * - **The output budget.** A fixed budget is a guess about how much a model
+ *   spends before it answers, and a wrong guess cuts the answer off as
+ *   `max-tokens` — which reads in the ledger as a route fault (2026-10-13).
+ *   The exact model's own advertised per-request cap wins; the definition's
+ *   declared budget is only the fallback for adapters that advertise none.
+ * - **The failure.** A terminal `error`/`aborted` finish carries the host's
+ *   own failure object, and the stream has usually reported its usage by
+ *   then. Both now ride the thrown error: keeping only the `kind` produced a
+ *   ledger full of "stream finished with error", and discarding the usage
+ *   left failed calls with no model and no token account at all.
+ */
+/** The minimal LLM face a direct call needs (duck-typed host service). */
+export interface LlmStream {
+    stream(options: Record<string, unknown>): AsyncIterable<unknown>;
+}
+/** Exact-model capability metadata, narrowed to the fields this plugin reads. */
+export interface ModelInfo {
+    reasoning?: {
+        efforts?: unknown;
+    } | undefined;
+    /** Adapter-configured per-request output cap; the host materializes it when callers omit `maxTokens`. */
+    defaultMaxTokens?: unknown;
+}
+/** The LLM service plus the optional exact-model capability query. */
+export interface LlmRuntime extends LlmStream {
+    /** Resolve one exact provider/model's capabilities; absent on older hosts and test fakes. */
+    resolveModelInfo?(provider: string, model: string): Promise<ModelInfo | undefined> | ModelInfo | undefined;
+}
+/** One concrete provider/model route for a direct call. */
+export interface ModelSelection {
+    provider: string;
+    model: string;
+    reasoningEffort?: string | undefined;
+}
+/** The host's default-model service, reached as `ctx.get("agentDefaultModel")`. */
+export interface DefaultModelService {
+    currentSelection(): unknown;
+}
+/** Read one sibling service off the host context (`ctx.get`). */
+export type ServiceGetter = (name: string) => unknown;
+/** Resolve one direct call's route from the agent plus the host default model. */
+export type RouteResolver = (agent: unknown) => ModelSelection | undefined;
+/** Effort ids that mean "reasoning off"; a model may advertise only these. */
+export declare const CLOSED_REASONING_EFFORTS: ReadonlySet<string>;
+/**
+ * Select the lowest reasoning effort an exact model advertises.
+ *
+ * An enabled effort wins over a declared closing effort: the adapter's first
+ * enabled effort is the lowest enabled level it exposes, and a closing effort
+ * is only a fallback when the model publishes no enabled level at all. No
+ * capability list means no caller-supplied effort.
+ *
+ * @param modelInfo - Exact resolved-model metadata, when the provider exposes it.
+ * @returns The provider-owned effort id to send, or `undefined` to omit the field.
+ * @throws When the host reports reasoning metadata in a shape this plugin cannot trust.
+ */
+export declare function selectLowestReasoningEffort(modelInfo: ModelInfo | undefined): string | undefined;
+/**
+ * The output budget to send for one exact route: the model's own advertised
+ * per-request cap when it has one, the caller's fallback otherwise.
+ *
+ * A budget below what the model needs is not a cost saving — it is a
+ * truncation. Deriving it from the model's capability (the same source the
+ * reasoning effort comes from) is what keeps one model's answer from being
+ * cut off at a number chosen for another model's habits.
+ *
+ * @param modelInfo - Exact resolved-model metadata, when the provider exposes it.
+ * @param fallbackMaxTokens - The definition's declared budget.
+ * @returns The budget to send.
+ * @throws When the host reports a max-tokens capability this plugin cannot trust.
+ */
+export declare function selectMaxTokens(modelInfo: ModelInfo | undefined, fallbackMaxTokens: number): number;
+/**
+ * One failed call, carrying what the stream observed before it failed.
+ *
+ * The model and the tokens of a *failed* call are exactly what the ledger
+ * could not answer for (2026-10-13): the route and usage existed in memory
+ * and were dropped on the way out. They ride the error now, so every failure
+ * path can account for itself the same way a success does.
+ */
+export declare class SubagentCallError extends Error {
+    /** Usage payload observed before the failure, `undefined` when the stream never reported one. */
+    readonly usage: unknown;
+    /** The terminal finish kind, `undefined` when the stream failed before reporting one. */
+    readonly finish: string | undefined;
+    /** The route the failed call ran on. */
+    readonly route: ModelSelection;
+    constructor(message: string, observed: {
+        usage: unknown;
+        finish: string | undefined;
+        route: ModelSelection;
+        cause?: unknown;
+    });
+}
+/**
+ * The usage a failed call had already observed, for the ledger.
+ *
+ * @param error - Whatever a call threw.
+ * @returns The observed usage payload, or `undefined` when the failure carries none.
+ */
+export declare function observedUsageOf(error: unknown): unknown;
+/**
+ * The host's default model selection, when the host exposes that service.
+ *
+ * The service is read through `ctx.get` and never joins an inject list: a host
+ * without it (or an older one) must keep working, and a failed read is simply
+ * "no default", never a mount failure.
+ *
+ * @param get - The host context's sibling-service reader, when available.
+ * @returns The default provider/model (plus effort), or `undefined` when unknown.
+ */
+export declare function defaultRouteOf(get: ServiceGetter | undefined): ModelSelection | undefined;
+/**
+ * Resolve the route one direct call runs on: the agent's explicit selection
+ * first, the host default second.
+ *
+ * @param agent - The host Agent the call belongs to (its `options` may be empty).
+ * @param get - The host context's sibling-service reader, when available.
+ * @returns The route to call with, or `undefined` when there is none to use.
+ */
+export declare function resolveCallRoute(agent: unknown, get: ServiceGetter | undefined): ModelSelection | undefined;
+/** One completed direct call: its text, usage, terminal finish kind, and chosen effort. */
+export interface StreamOnceResult {
+    text: string;
+    usage: unknown;
+    /** The host's finish kind (`stop`, `max-tokens`, …); `undefined` when the stream omitted it. */
+    finish: string | undefined;
+    /** The capability-derived effort actually sent, for diagnostics. */
+    reasoningEffort: string | undefined;
+}
+/**
+ * Stream one single-turn text call on one route.
+ *
+ * A terminal `error` or `aborted` finish always throws, carrying the host's own
+ * failure text — partial text never rescues a failed call. A `max-tokens` cut
+ * is *not* thrown here: a gate answer often completes before its budget does,
+ * so the caller owns that verdict and reads `finish`.
+ *
+ * @param llm - The LLM service; `undefined` means the host exposed no route at all.
+ * @param route - The exact provider/model to call.
+ * @param sessionId - The host Agent identity providers use for request routing.
+ * @param system - The system prompt for this call.
+ * @param prompt - The user prompt for this call.
+ * @param fallbackMaxTokens - Output budget to use when the model advertises no cap of its own.
+ * @returns The assembled text, usage, finish kind, and chosen effort.
+ * @throws On a missing LLM service, capability lookup failure, terminal provider error or abort, and empty output.
+ */
+export declare function streamOnce(llm: LlmRuntime | undefined, route: ModelSelection, sessionId: string | undefined, system: string, prompt: string, fallbackMaxTokens: number): Promise<StreamOnceResult>;
+//# sourceMappingURL=llm-call.d.ts.map