@moxxy/sdk 0.26.0 → 0.28.0

package/dist/mode/checkpoint.d.ts

@@ -0,0 +1,107 @@
+import type { ModeContext } from '../mode.js';
+import type { StopReason } from '../provider-utils.js';
+/**
+ * Turn-end checkpoints — the extension point that lets a mode gate the moment
+ * the model stops calling tools and (apparently) finishes its turn. The shared
+ * ReAct loop ({@link runReactLoop}) invokes each checkpoint in declared order
+ * at that instant; a checkpoint can approve the completion (`pass`), feed a
+ * correction back into the conversation and keep the turn alive (`inject`),
+ * re-ask the model without new input (`retry`), or end the turn on its own
+ * terms (`stop`).
+ *
+ * A checkpoint's `run` may do anything async — run a fixed shell command via
+ * `ctx.tools.execute`, or spawn and await a full child agent turn via
+ * `ctx.subagents.spawn` (a lint gate, a completion reviewer). Two rules keep
+ * that power safe:
+ *
+ *   1. Honor `check.signal` in every await. It aborts on user cancel AND on
+ *      this checkpoint's `timeoutMs` — an await that ignores it outlives the
+ *      turn.
+ *   2. Never spawn a child running a checkpoint-bearing mode (pass
+ *      `mode: 'default'`). The loop core also disarms checkpoints inside
+ *      subagent sessions ({@link ModeContext.isSubagent}) as a backstop, so a
+ *      mistake here degrades to an ungated child instead of unbounded
+ *      recursion.
+ */
+export type CheckpointResult = {
+    readonly action: 'pass';
+} | {
+    readonly action: 'inject';
+    /**
+     * Feedback fed back to the model. Persistent by default: appended to the
+     * event log as a checkpoint-origin `user_prompt`, so it survives
+     * resume/replay and projects into every subsequent provider call.
+     * Clamped to the loop's `maxInjectBytes`.
+     */
+    readonly text: string;
+    /**
+     * When true the text is NOT logged — it rides the next provider call as
+     * a volatile trailing user message (goal mode's nudge mechanism) and
+     * vanishes afterwards. Use for steering ("keep going"), not for
+     * substantive feedback the model must act on across several tool
+     * batches. The loop forwards `volatileTailCount` to the cache strategy
+     * so the rolling tail breakpoint stays ahead of it.
+     */
+    readonly volatile?: boolean;
+}
+/**
+ * Loop again with no new input (idle-tolerant modes count idle rounds
+ * before giving up). Counts against the injection budget like `inject`.
+ */
+ | {
+    readonly action: 'retry';
+}
+/**
+ * End the turn NOW, skipping any remaining checkpoints. The checkpoint is
+ * expected to have already emitted its own wrap-up events via `ctx.emit`
+ * (a stall notice, a completion summary) — the loop adds nothing.
+ */
+ | {
+    readonly action: 'stop';
+};
+export interface CheckpointContext {
+    /** The final text the model produced for this turn-end candidate. */
+    readonly candidateText: string;
+    /**
+     * How the provider ended the candidate call. Checkpoints that verify
+     * completion claims should treat only `'end_turn'` as a claim — a
+     * `'max_tokens'` candidate is a truncation, not a claim.
+     */
+    readonly stopReason: StopReason;
+    readonly iteration: number;
+    /**
+     * Consecutive turn-end candidates without an intervening tool batch,
+     * 1-based (this candidate included). Resets when the model does real work.
+     * Idle-tolerant modes use this as their stall counter.
+     */
+    readonly consecutiveIdle: number;
+    /** `inject`/`retry` rounds already spent this turn. */
+    readonly injectionsUsed: number;
+    /** The loop's `maxInjections` — lets a checkpoint soften its bar on the last round. */
+    readonly injectionBudget: number;
+    /**
+     * Aborts on user cancel OR this checkpoint's timeout. Thread it into every
+     * await (`ctx.tools.execute(..., signal)`, subagent spawns, fetches).
+     */
+    readonly signal: AbortSignal;
+}
+export interface TurnCheckpoint {
+    /** Stable name — stamped on checkpoint plugin events and injected-prompt origins. */
+    readonly name: string;
+    /**
+     * Wall-clock budget for one evaluation (default 120_000 ms, floored at
+     * 1_000). On timeout the checkpoint fails OPEN: the loop logs a visible
+     * warning and proceeds as if it passed — a stuck checker must never wedge
+     * the turn.
+     */
+    readonly timeoutMs?: number;
+    /**
+     * Which turn-end candidates this checkpoint sees. `'end_turn'` (default)
+     * gates only natural completions — truncated/errored candidates bypass it.
+     * `'idle'` gates every no-tool completion regardless of stop reason
+     * (goal/collab-style stall handling wants these too).
+     */
+    readonly gateOn?: 'end_turn' | 'idle';
+    run(check: CheckpointContext, ctx: ModeContext): Promise<CheckpointResult>;
+}
+//# sourceMappingURL=checkpoint.d.ts.map

package/dist/mode/checkpoint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint.d.ts","sourceRoot":"","sources":["../../src/mode/checkpoint.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAEvD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,MAAM,gBAAgB,GACxB;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC3B;IACE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAC1B;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC7B;AACH;;;GAGG;GACD;IAAE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;CAAE;AAC9B;;;;GAIG;GACD;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEhC,MAAM,WAAW,iBAAiB;IAChC,qEAAqE;IACrE,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,uDAAuD;IACvD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,uFAAuF;IACvF,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;CAC9B;AAED,MAAM,WAAW,cAAc;IAC7B,qFAAqF;IACrF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,UAAU,GAAG,MAAM,CAAC;IACtC,GAAG,CAAC,KAAK,EAAE,iBAAiB,EAAE,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;CAC5E"}

package/dist/mode/checkpoint.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=checkpoint.js.map

package/dist/mode/checkpoint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint.js","sourceRoot":"","sources":["../../src/mode/checkpoint.ts"],"names":[],"mappings":""}

package/dist/mode/react-loop.d.ts

@@ -0,0 +1,129 @@
+import type { MoxxyEvent } from '../events.js';
+import type { ModeContext } from '../mode.js';
+import type { TokenUsage } from '../provider.js';
+import type { StopReason } from '../provider-utils.js';
+import { type StuckLoopReport, type StuckTripInfo } from '../tool-dispatch.js';
+import type { TurnCheckpoint } from './checkpoint.js';
+import { type CollectedToolUse } from './collect-stream.js';
+/**
+ * The shared ReAct loop core every tool-calling mode runs on. One hardened
+ * copy of the plumbing that used to be duplicated per mode (default / goal /
+ * collab-agent): provider retry with bounded exponential back-off, reactive
+ * compaction on context overflow, turn-boundary elision, stuck-loop
+ * detection, abort handling on every await — plus the turn-end checkpoint
+ * gate ({@link TurnCheckpoint}) that lets a mode verify a completion claim
+ * (run lints, spawn a reviewer agent) before the turn is allowed to end.
+ *
+ * Modes express their POLICY through {@link ReactLoopOptions}: hooks fire at
+ * fixed points (iteration start, provider success, tool batch end, iteration
+ * cap) and checkpoints fire at the turn-end candidate. Hooks emit their own
+ * events via `ctx.emit` — the live event channel is the log subscription
+ * (`runTurn` discards the yielded stream), so emit order is what channels
+ * and tests observe.
+ */
+/** Bounded back-off for retryable provider errors — see the field docs. */
+export declare const MAX_CONSECUTIVE_RETRIES = 6;
+/**
+ * Override the retry back-off sleep (test seam). Returns a restore fn that
+ * callers MUST invoke (in a `finally`) — `sleepImpl` is a module-scoped
+ * singleton shared process-wide, so a leaked override bleeds the fake sleep
+ * into every other turn/test running in the same worker (parallel subagent
+ * fan-out, multiple Sessions in one host). Test-only; never call from prod.
+ */
+export declare function __setRetrySleepForTests(fn: (ms: number, signal: AbortSignal) => Promise<void>): () => void;
+/** What a clean provider call produced — input to {@link ReactLoopOptions.onProviderSuccess}. */
+export interface ProviderSuccessInfo {
+    readonly text: string;
+    readonly stopReason: StopReason;
+    readonly toolUses: ReadonlyArray<CollectedToolUse>;
+    readonly usage?: TokenUsage;
+    readonly iteration: number;
+}
+/** A completed tool batch — input to {@link ReactLoopOptions.onToolBatchEnd}. */
+export interface ToolBatchInfo {
+    readonly toolUses: ReadonlyArray<CollectedToolUse>;
+    readonly iteration: number;
+}
+/** Hooks return this to end the turn; the hook emits its own wrap-up events first. */
+export interface StopDirective {
+    readonly action: 'stop';
+}
+export interface ReactLoopOptions {
+    /** Name stamped on `mode_iteration` events (e.g. `'default'`, `'goal'`). */
+    readonly strategyName: string;
+    /**
+     * Iteration cap when the context doesn't supply one. Default 500. May be
+     * `Number.POSITIVE_INFINITY` for an uncapped loop (goal mode): the run then
+     * ends only via a terminal signal (checkpoint/hook stop, abort, fatal
+     * error) — an explicit `ctx.maxIterations` still takes precedence.
+     */
+    readonly defaultMaxIterations?: number;
+    /** Prefix for provider-error messages (goal mode uses `'goal: '`). */
+    readonly errorPrefix?: string;
+    /**
+     * When set, an already-aborted signal is reported (with this reason) BEFORE
+     * the first iteration — goal/collab preflight. When omitted the first
+     * iteration's own abort check covers it with the generic reason.
+     */
+    readonly preflightAbortReason?: string;
+    /** Turn-end gates, run in declared order. Omit/empty → plain ReAct loop. */
+    readonly checkpoints?: ReadonlyArray<TurnCheckpoint>;
+    /**
+     * Hard cap on checkpoint `inject`/`retry` rounds per idle EPISODE — i.e.
+     * consecutive gate rounds with no tool work between them; the count resets
+     * whenever a tool batch executes (default 3). When exhausted the turn ends
+     * with the model's answer as-is plus a visible warning — a
+     * permanently-failing gate degrades loudly instead of looping forever.
+     */
+    readonly maxInjections?: number;
+    /** Clamp on injected feedback length in characters (default 16_384). */
+    readonly maxInjectChars?: number;
+    /**
+     * Stuck-loop policy + wording overrides; sensible defaults from
+     * `strategyName`. `action` picks what a detector trip does:
+     *
+     *   - `'abort'` (default): fail the batch and end the turn with a fatal
+     *     error — the historical behavior, right for attended modes where the
+     *     user is present to redirect.
+     *   - `'nudge'`: never stop. The batch still executes (repeated calls are
+     *     usually legitimate work — re-running a failing build between edits),
+     *     a visible warning + `extraOnStuck` events are emitted, the detector
+     *     resets, and `nudgeText` (or a default) rides the next provider call
+     *     as a volatile steer. For unattended modes (goal) where a heuristic
+     *     must never kill the run.
+     */
+    readonly stuck?: Partial<StuckLoopReport> & {
+        readonly action?: 'abort' | 'nudge';
+        /** Volatile steer for `'nudge'` trips; default wording when omitted. */
+        readonly nudgeText?: (info: StuckTripInfo) => string;
+    };
+    /**
+     * Runs after compaction/elision, before the provider call. May return a
+     * volatile user message to ride ONLY the next call (collab's inbox/pause
+     * awareness) — never appended to the log; the cache strategy is told via
+     * `volatileTailCount` so its tail breakpoint stays ahead of it.
+     */
+    readonly onIterationStart?: (ctx: ModeContext, iteration: number) => Promise<{
+        readonly volatileUserText?: string;
+    } | undefined>;
+    /**
+     * Runs after every clean provider call (reasoning already logged, tools not
+     * yet executed). Return `{action: 'stop'}` to end the turn — the hook emits
+     * its own wrap-up events first (goal mode's token-budget backstop).
+     */
+    readonly onProviderSuccess?: (ctx: ModeContext, info: ProviderSuccessInfo) => Promise<StopDirective | undefined>;
+    /**
+     * Runs after a tool batch executes cleanly. Return `{action: 'stop'}` to
+     * end the turn (goal/collab terminal-tool detection: `goal_complete`,
+     * `collab_done`); the hook emits its own completion events first.
+     */
+    readonly onToolBatchEnd?: (ctx: ModeContext, info: ToolBatchInfo) => Promise<StopDirective | undefined>;
+    /**
+     * Replaces the default "exceeded maxIterations" fatal error — the hook
+     * emits its own cap-reached events (goal mode adds a plugin event and its
+     * own wording). The loop returns right after.
+     */
+    readonly onMaxIterations?: (ctx: ModeContext, maxIterations: number) => Promise<void>;
+}
+export declare function runReactLoop(ctx: ModeContext, opts: ReactLoopOptions): AsyncIterable<MoxxyEvent>;
+//# sourceMappingURL=react-loop.d.ts.map

package/dist/mode/react-loop.d.ts.map

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