@aexol/spectral 0.9.231 → 0.9.240

package/dist/server/agent-bridge.js

@@ -70,7 +70,7 @@ import { humanizeProviderError } from "./error-humanizer.js";
 import { readStudioBinding, getBindingFilePath } from "../studio-binding.js";
 // Facade imports: cohesive helpers extracted verbatim to `./agent-bridge/` modules.
 import { calculateCredits, getModelCost, resolveCreditRatesForModel, } from "./agent-bridge/pricing.js";
-import { computeTpsMetrics } from "./agent-bridge/tps-metrics.js";
+import { buildTpsUsageFields, computeTpsMetrics, } from "./agent-bridge/tps-metrics.js";
 import { SPECTRAL_PROXY_OPENAI, SPECTRAL_PROXY_USER_MODEL, inferSyntheticContextWindow, inferSyntheticOpenAICompat, inferSyntheticThinkingLevelMap, } from "./agent-bridge/synthetic-model.js";
 import { parseWireToolEvents, sanitizeRehydratedBlock, toRestoredMemorySnapshot, } from "./agent-bridge/rehydrate.js";
 import { createHeadlessUIContext } from "./agent-bridge/headless-ui.js";
@@ -280,6 +280,15 @@ export class AgentBridge {
      * timer flushes it once the minimum interval has elapsed.
      */
     subagentProgressThrottle = new Map();
+    /**
+     * Latest LIVE TPS snapshot per parent subagent tool call id, folded from
+     * the internal `subagent_tps` events the runner emits after each LLM round
+     * with tokens. Consumed when building throttled `subagent_progress` frames
+     * so they carry durationMs/tokensPerSecond/ttftMs/lastRoundTps; cleared at
+     * subagent completion (see flushSubagentProgress) so state never leaks into
+     * a later invocation.
+     */
+    subagentTpsSnapshot = new Map();
     /**
      * toolCallId → startedAt captured at `tool_execution_start` so the
      * terminal `tool_result` can carry the real start time (durations
@@ -748,6 +757,12 @@ export class AgentBridge {
         });
         this.allowedModels = allowedModels;
         this.registerSyntheticProviders(allowedModels);
+        const visionDefaults = allowedModels.filter((m) => m.isVisionDefault);
+        if (visionDefaults.length > 1) {
+            console.warn(`[AgentBridge] Multiple vision-default models reported by backend (${visionDefaults
+                .map((m) => m.modelId)
+                .join(", ")}); using the first one: ${visionDefaults[0].modelId}`);
+        }
         return allowedModels;
     }
     /**
@@ -908,6 +923,22 @@ export class AgentBridge {
     isBusy() {
         return this.isStreaming() || this.isRetrying();
     }
+    /**
+     * Stop a single in-flight tool call (user-initiated per-call stop).
+     * Delegates to the SDK session; returns false for unknown/finished
+     * toolCallIds or when the session has not started.
+     */
+    async stopToolCall(toolCallId, reason) {
+        if (!this.session)
+            return false;
+        try {
+            return await this.session.stopToolCall(toolCallId, reason);
+        }
+        catch {
+            // best-effort: a per-call stop must never surface as a bridge error
+            return false;
+        }
+    }
     getSessionBranch() {
         return (this.sessionManager?.getBranch() ?? []);
     }
@@ -1013,10 +1044,10 @@ export class AgentBridge {
     /**
      * Map a frontend reasoning-effort string to spectral's ThinkingLevel.
      * Frontend sends: xhigh | high | medium | low | minimal | none | undefined
-     * spectral expects:   "high" | "medium" | "low" | "minimal" | "off"
+     * spectral accepts:   "off" | "minimal" | "low" | "medium" | "high" | "xhigh"
      *
      * Mapping:
-     *   xhigh   → high    (spectral doesn't have xhigh, default to max)
+     *   xhigh   → xhigh (passed through as-is)
      *   high    → high
      *   medium  → medium
      *   low     → low
@@ -1376,6 +1407,21 @@ export class AgentBridge {
             this.memoryPhase = "compacting";
         if (event.type === "compaction_end")
             this.memoryPhase = "idle";
+        // LIVE TPS snapshots (`subagent_tps`) are internal transport between the
+        // subagent extension and this bridge. Fold them into the per-toolCallId
+        // progress state and keep them off the wire + out of the persisted JSONL —
+        // subscribers receive the values on throttled `subagent_progress` frames
+        // instead (subagent_progress contract: live, token-weighted, omitted
+        // until the first round with tokens).
+        if (event.type === "subagent_tps") {
+            this.subagentTpsSnapshot.set(event.toolCallId, {
+                durationMs: event.durationMs,
+                tokensPerSecond: event.tokensPerSecond,
+                ttftMs: event.ttftMs,
+                lastRoundTps: event.lastRoundTps,
+            });
+            return;
+        }
         // Subagent progress events flow through emitAndBuffer (not handleEvent),
         // so they must bump the inactivity watchdog here — otherwise a working
         // subagent that streams progress for >PROMPT_INACTIVITY_TIMEOUT_MS would
@@ -1437,6 +1483,10 @@ export class AgentBridge {
      * then drop the throttle state for that tool call.
      */
     flushSubagentProgress(toolCallId) {
+        // The live TPS snapshot is torn down together with the throttle: the
+        // final pending frame already carries the values it needs (attached at
+        // build time), so a later invocation of the same tool call starts clean.
+        this.subagentTpsSnapshot.delete(toolCallId);
         const slot = this.subagentProgressThrottle.get(toolCallId);
         if (!slot)
             return;
@@ -1712,6 +1762,11 @@ export class AgentBridge {
                         const thinkingText = typeof runningResult?.thinkingText === "string"
                             ? runningResult.thinkingText
                             : undefined;
+                        // LIVE TPS snapshot folded from the runner's `subagent_tps`
+                        // events (subagent_progress contract). Absent until the subagent
+                        // completes its first LLM round with tokens; cleared at
+                        // subagent_end so a later invocation starts clean.
+                        const liveTps = this.subagentTpsSnapshot.get(ev.toolCallId);
                         const se = {
                             type: "subagent_progress",
                             toolCallId: ev.toolCallId,
@@ -1746,6 +1801,7 @@ export class AgentBridge {
                                     firstMessage: typeof r.firstMessage === "string" ? r.firstMessage : undefined,
                                 }))
                                 : undefined,
+                            ...(liveTps ?? {}),
                         };
                         // Progress snapshots carry full accumulated streaming/thinking text.
                         // Keep them live-only so per-message events_jsonl does not grow by
@@ -1822,9 +1878,47 @@ export class AgentBridge {
                                 systemPrompt: r.systemPrompt,
                                 firstMessage: r.firstMessage,
                                 attempts: r.attempts,
-                                usage: { ...usage, creditsUsed },
+                                usage: {
+                                    ...usage,
+                                    creditsUsed,
+                                    // Per-LLM-round timing (TPS contract): stamped in the
+                                    // subagent runner per assistant round and token-weighted
+                                    // across its rounds. Optional/unreliable indicators.
+                                    ...(r.tps
+                                        ? {
+                                            durationMs: r.tps.durationMs,
+                                            tokensPerSecond: r.tps.tokensPerSecond,
+                                            ttftMs: r.tps.ttftMs,
+                                            lastRoundTps: r.tps.lastRoundTps,
+                                        }
+                                        : {}),
+                                },
                             };
                         });
+                        // Token-weighted TPS aggregation across results (subagent_end
+                        // contract): Σ outputTokens / Σ durationMs over TPS-eligible
+                        // rounds, arithmetic-mean TTFT across rounds, and the last
+                        // round's TPS in results order.
+                        const tpsTotal = details.results.reduce((acc, r) => {
+                            if (!r.tps)
+                                return acc;
+                            acc.durationMsSum += r.tps.durationMs ?? 0;
+                            acc.outputTokens += r.tps.outputTokens;
+                            acc.outputDurationMs += r.tps.outputDurationMs;
+                            acc.ttftMsSum += r.tps.ttftMsSum;
+                            acc.ttftRounds += r.tps.ttftRounds;
+                            if (r.tps.lastRoundTps != null) {
+                                acc.lastRoundTps = r.tps.lastRoundTps;
+                            }
+                            return acc;
+                        }, {
+                            durationMsSum: 0,
+                            outputTokens: 0,
+                            outputDurationMs: 0,
+                            ttftMsSum: 0,
+                            ttftRounds: 0,
+                            lastRoundTps: null,
+                        });
                         const totalUsage = results.reduce((acc, r) => ({
                             inputTokens: acc.inputTokens + r.usage.inputTokens,
                             outputTokens: acc.outputTokens + r.usage.outputTokens,
@@ -1842,6 +1936,14 @@ export class AgentBridge {
                             turns: 0,
                             creditsUsed: 0,
                         });
+                        const totalTps = buildTpsUsageFields({
+                            durationMsSum: tpsTotal.durationMsSum,
+                            outputTokens: tpsTotal.outputTokens,
+                            outputDurationMs: tpsTotal.outputDurationMs,
+                            ttftMsSum: tpsTotal.ttftMsSum,
+                            ttftRounds: tpsTotal.ttftRounds,
+                            lastRoundTps: tpsTotal.lastRoundTps,
+                        });
                         const se = {
                             type: "subagent_end",
                             toolCallId: ev.toolCallId,
@@ -1849,7 +1951,7 @@ export class AgentBridge {
                             finishedAt: Date.now(),
                             mode,
                             results,
-                            totalUsage,
+                            totalUsage: { ...totalUsage, ...totalTps },
                         };
                         this.emitAndBuffer(se);
                     }
@@ -1860,6 +1962,7 @@ export class AgentBridge {
                     id: ev.toolCallId,
                     result: ev.result,
                     isError: ev.isError,
+                    ...(ev.stoppedByUser ? { stoppedByUser: true } : {}),
                     startedAt: this.toolStartedAt.get(ev.toolCallId) ?? Date.now(),
                     finishedAt: Date.now(),
                 });

package/dist/server/handlers/paths-list.d.ts

@@ -1,7 +1,7 @@
 /**
  * List the contents of an absolute directory path.
  *
- * Used by the inline directory picker fallback in the browser/Electron
+ * Used by the inline directory picker fallback in the browser/desktop wrapper
  * when a native OS dialog cannot be opened. Returns a sorted list of
  * entries with enough metadata to render a navigable directory tree.
  */

package/dist/server/handlers/paths-list.js

@@ -1,7 +1,7 @@
 /**
  * List the contents of an absolute directory path.
  *
- * Used by the inline directory picker fallback in the browser/Electron
+ * Used by the inline directory picker fallback in the browser/desktop wrapper
  * when a native OS dialog cannot be opened. Returns a sorted list of
  * entries with enough metadata to render a navigable directory tree.
  */

package/dist/server/inter-agent-broker.d.ts

@@ -38,6 +38,13 @@ export interface InterAgentMessage {
     createdAt: number;
     /** Timestamp (ms) when the recipient first polled it, if ever. */
     deliveredAt?: number;
+    /**
+     * Session ids this message has been delivered to (per-recipient
+     * bookkeeping). Absent/empty means the message has not been delivered to
+     * anyone yet. `deliveredAt` stays the FIRST-delivery timestamp for
+     * TTL/debug purposes.
+     */
+    deliveredTo?: string[];
     /** Timestamp (ms) after which the message may be garbage collected. */
     expiresAt?: number;
 }
@@ -59,6 +66,11 @@ export interface InterAgentPollInput {
     channel?: string;
     /** Poll only messages addressed to this session (or broadcast). Omit to poll all. */
     recipientSessionId?: string;
+    /**
+     * Exclude messages sent by this session id (self-filtering). Omit to
+     * include the poller's own messages (legacy behavior).
+     */
+    excludeSenderSessionId?: string;
     /** Only return messages created after this timestamp (exclusive). */
     since?: number;
     /** Maximum messages to return. Default 100. */

package/dist/server/inter-agent-broker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"inter-agent-broker.d.ts","sourceRoot":"","sources":["../../src/server/inter-agent-broker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAGjD,MAAM,WAAW,iBAAiB;IAChC,gCAAgC;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,sBAAsB;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,0EAA0E;IAC1E,OAAO,EAAE,MAAM,CAAC;IAChB,qCAAqC;IACrC,eAAe,EAAE,MAAM,CAAC;IACxB,2CAA2C;IAC3C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8EAA8E;IAC9E,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,sEAAsE;IACtE,IAAI,EAAE,MAAM,CAAC;IACb,2BAA2B;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,+DAA+D;IAC/D,SAAS,EAAE,MAAM,CAAC;IAClB,kEAAkE;IAClE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0BAA0B;IAC1B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,qDAAqD;IACrD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,mEAAmE;IACnE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qFAAqF;IACrF,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,qEAAqE;IACrE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+CAA+C;IAC/C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yDAAyD;IACzD,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,wBAAwB;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,CAAC,GAAG,EAAE,iBAAiB,KAAK,IAAI,CAAC;CAC3C;AAED,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,YAAY,CAAC;IACpB,iFAAiF;IACjF,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;GAKG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;IACrC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAE3C;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA4D;gBAE9E,IAAI,EAAE,uBAAuB;IAKzC;;;OAGG;IACH,IAAI,CAAC,KAAK,EAAE,mBAAmB,GAAG,iBAAiB;IAyBnD;;;OAGG;IACH,IAAI,CAAC,KAAK,EAAE,mBAAmB,GAAG,iBAAiB,EAAE;IAWrD;;;OAGG;IACH,SAAS,CAAC,KAAK,EAAE,wBAAwB,GAAG,MAAM,IAAI;IA4BtD;;OAEG;IACH,OAAO,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI;IAQrC,OAAO,CAAC,iBAAiB;CAqB1B"}
+{"version":3,"file":"inter-agent-broker.d.ts","sourceRoot":"","sources":["../../src/server/inter-agent-broker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAGjD,MAAM,WAAW,iBAAiB;IAChC,gCAAgC;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,sBAAsB;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,0EAA0E;IAC1E,OAAO,EAAE,MAAM,CAAC;IAChB,qCAAqC;IACrC,eAAe,EAAE,MAAM,CAAC;IACxB,2CAA2C;IAC3C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8EAA8E;IAC9E,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,sEAAsE;IACtE,IAAI,EAAE,MAAM,CAAC;IACb,2BAA2B;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,+DAA+D;IAC/D,SAAS,EAAE,MAAM,CAAC;IAClB,kEAAkE;IAClE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0BAA0B;IAC1B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,qDAAqD;IACrD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,mEAAmE;IACnE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qFAAqF;IACrF,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;;OAGG;IACH,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,qEAAqE;IACrE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+CAA+C;IAC/C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yDAAyD;IACzD,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,wBAAwB;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,CAAC,GAAG,EAAE,iBAAiB,KAAK,IAAI,CAAC;CAC3C;AAED,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,YAAY,CAAC;IACpB,iFAAiF;IACjF,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;GAKG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;IACrC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAE3C;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA4D;gBAE9E,IAAI,EAAE,uBAAuB;IAKzC;;;OAGG;IACH,IAAI,CAAC,KAAK,EAAE,mBAAmB,GAAG,iBAAiB;IAyBnD;;;OAGG;IACH,IAAI,CAAC,KAAK,EAAE,mBAAmB,GAAG,iBAAiB,EAAE;IAYrD;;;OAGG;IACH,SAAS,CAAC,KAAK,EAAE,wBAAwB,GAAG,MAAM,IAAI;IA4BtD;;OAEG;IACH,OAAO,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI;IAQrC,OAAO,CAAC,iBAAiB;CAqB1B"}

package/dist/server/inter-agent-broker.js

@@ -69,6 +69,7 @@ export class InterAgentBroker {
             projectId: input.projectId,
             channel: input.channel,
             recipientSessionId: input.recipientSessionId,
+            excludeSenderSessionId: input.excludeSenderSessionId,
             since: input.since,
             limit: input.limit ?? 100,
             markDelivered: input.markDelivered ?? true,

package/dist/server/preset-chain.d.ts

@@ -0,0 +1,151 @@
+/**
+ * "@preset:<name>" chain expansion.
+ *
+ * A queued prompt whose content starts with `@preset:<name>` references a
+ * backend preset. When such an item is dequeued, it expands into:
+ *   1. the preset's QUEUE follow-up messages, enqueued (in order, trimmed)
+ *      BEFORE the turn starts, and
+ *   2. the preset's main prompt with its INJECT follow-up messages (and any
+ *      remainder text from the reference) appended as paragraphs, which runs
+ *      as the turn — the same composition the frontend apply-preset flow
+ *      produces for the composer text.
+ *
+ * Because follow-ups are enqueued verbatim and each dequeued item is itself
+ * checked for a reference, a follow-up that is `@preset:<other>` expands at
+ * its own dequeue — chained presets therefore behave like programs.
+ *
+ * Safety valves:
+ *   - `PRESET_CHAIN_BUDGET` caps expansions between non-reference prompts so
+ *     a preset that (indirectly) references itself terminates instead of
+ *     looping forever. Budget resets whenever a non-reference item is seen.
+ *   - Every failure mode (resolver down, unknown preset, blank prompt)
+ *     falls back to running the raw reference text — a queued item is never
+ *     silently dropped.
+ *
+ * Everything here is pure/injectable so it is unit-testable without a
+ * backend; the only I/O helper is `resolvePresetByName`.
+ */
+/** Expansions allowed before a raw-run fallback (reset on non-references). */
+export declare const PRESET_CHAIN_BUDGET = 25;
+/** Maximum follow-up messages enqueued per expansion. Mirrors the backend
+ * resolver cap (`MAX_FOLLOW_UP_MESSAGES`). */
+export declare const MAX_PRESET_FOLLOW_UPS = 20;
+/** A preset row as returned by `GET /v1/presets/resolve`. */
+export interface ResolvedPreset {
+    id: string;
+    name: string;
+    prompt: string;
+    followUpMessages: unknown;
+    scope?: "TEAM" | "PROJECT" | null;
+    projectId?: string | null;
+    loopEnabled?: boolean | null;
+    maxIterations?: number | null;
+    goal?: string | null;
+    intervalMinutes?: number | null;
+}
+/** Why an expansion did not happen. */
+export type PresetSkipReason = "not-reference" | "budget" | "unresolved";
+/** Result of {@link parsePresetReference}. */
+export interface PresetReference {
+    name: string;
+    remainder: string;
+}
+/**
+ * Parse a queued prompt into a preset reference, or `null` when the content
+ * is not a reference. `@preset:` without a name does NOT match.
+ */
+export declare function parsePresetReference(content: string): PresetReference | null;
+/**
+ * Resolve a preset by name through the backend machine-JWT REST route.
+ * Never throws: any failure (network, timeout, non-2xx, malformed body)
+ * resolves to `null` so callers fall back to the raw reference text.
+ */
+export declare function resolvePresetByName(backendUrl: string, machineJwt: string, teamId: string | undefined, name: string): Promise<ResolvedPreset | null>;
+/**
+ * A follow-up message extracted from the stored `followUpMessages` JSON,
+ * with its delivery mode preserved.
+ */
+export interface PresetFollowUp {
+    content: string;
+    mode: "INJECT" | "QUEUE";
+}
+/**
+ * Extract follow-up messages from the stored `followUpMessages` JSON,
+ * preserving each entry's mode. Canonical entries are `{ content, mode }`
+ * objects; plain strings are tolerated for robustness and default to INJECT
+ * (matching the backend resolver and the frontend apply-preset flow, which
+ * only special-case QUEUE). Empty/blank entries are skipped, output is
+ * capped at {@link MAX_PRESET_FOLLOW_UPS}, and non-arrays yield `[]`.
+ */
+export declare function extractFollowUpContents(raw: unknown): PresetFollowUp[];
+/**
+ * Compose the turn prompt for an expansion: the preset prompt with the
+ * reference remainder appended as a separate paragraph (when non-empty).
+ */
+export declare function composeExpandedPrompt(presetPrompt: string, remainder: string): string;
+/**
+ * Compose the full running prompt for a preset expansion: the preset prompt,
+ * then its INJECT follow-up contents, then the reference remainder — all
+ * joined as paragraphs (identical shape to the frontend apply-preset flow's
+ * composer text). Blank parts are dropped.
+ */
+export declare function composePresetRunPrompt(presetPrompt: string, injectContents: readonly string[], remainder: string): string;
+/** Injectable collaborators for {@link expandIfPresetReference}. */
+export interface PresetChainDeps {
+    parse: (content: string) => PresetReference | null;
+    resolve: (name: string) => Promise<ResolvedPreset | null>;
+    enqueue: (content: string) => void;
+    run: (content: string) => void;
+    onSkip: (reason: PresetSkipReason) => void;
+}
+export interface ExpandPresetReferenceInput extends PresetChainDeps {
+    /** The dequeued prompt content. */
+    content: string;
+    /** Expansions still allowed; defaults to {@link PRESET_CHAIN_BUDGET}. */
+    chainBudget?: number;
+}
+export interface PresetExpansionOutcome {
+    /** True when a preset resolved and its follow-ups were enqueued. */
+    expanded: boolean;
+    /** True when `run` was invoked (all paths except `not-reference`). */
+    ran: boolean;
+    /** Content passed to `run` (null when nothing ran). */
+    ranContent: string | null;
+    /** QUEUE follow-up contents enqueued, in order (INJECT follow-ups are
+     * folded into `ranContent` instead). */
+    enqueuedFollowUps: string[];
+    /** Why expansion did not happen (null on success). */
+    skipReason: PresetSkipReason | null;
+    /** Budget left after this call (unchanged on skip paths). */
+    budgetRemaining: number;
+    /** True when the caller should reset its stored budget to the default. */
+    budgetReset: boolean;
+}
+/**
+ * Orchestrate one dequeued item:
+ *   - not a reference          → skip signal + budget reset; nothing runs
+ *                                (the caller keeps its plain dequeue path).
+ *   - reference, budget spent  → run the raw content, skip "budget".
+ *   - reference, resolve fails → run the raw content, skip "unresolved".
+ *   - otherwise                → enqueue each QUEUE follow-up (capped, in
+ *                                order), THEN run the composed prompt
+ *                                (`preset prompt + INJECT follow-ups +
+ *                                remainder`, paragraph-separated); spend one
+ *                                unit of budget. A preset whose follow-ups
+ *                                are all INJECT enqueues nothing.
+ *
+ * `resolve` never throws (see {@link resolvePresetByName}); errors thrown by
+ * the injected `enqueue`/`run` deps propagate to the caller.
+ */
+export declare function expandIfPresetReference(input: ExpandPresetReferenceInput): Promise<PresetExpansionOutcome>;
+/**
+ * Expand a prompt that is about to be REPLAYED (autonomous loop arming).
+ * Returns the input unchanged when it is not a reference or the resolver
+ * fails, so loop arming never blocks on or loses the original prompt. Does
+ * NOT touch the chain budget: expansion happens once at arming time, not on
+ * every iteration. INJECT follow-ups are folded into the replayed prompt
+ * (same composition as the queue-expansion path); QUEUE follow-ups are not
+ * enqueued here — loop arming only rewrites the replayed prompt.
+ */
+export declare function expandPresetPrompt(prompt: string, resolve: (name: string) => Promise<ResolvedPreset | null>): Promise<string>;
+//# sourceMappingURL=preset-chain.d.ts.map

package/dist/server/preset-chain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preset-chain.d.ts","sourceRoot":"","sources":["../../src/server/preset-chain.ts"],"names":[],"mappings":"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"}