@itookit/dsht 0.3.7 → 0.5.1

package/dist/controller/loop-protocols.d.ts

@@ -0,0 +1,39 @@
+import { type LoopProtocol } from './loop.ts';
+import type { LoopRecord } from '../contracts.ts';
+/** Names `/loop` may run, in file order. */
+export declare function loopProtocolNames(): string[];
+/** Every record `/loop` may run, in file order, with the defaults a run would start from.
+ *
+ * The list and the run read the same records, so a chooser can show exactly the name, round count,
+ * artifact and defaults the runner would use — never a second table that could drift.
+ * @returns One summary per record.
+ */
+export declare function loopRecords(): LoopRecord[];
+/** One record's declared variables, so a caller can offer or validate them before a run starts.
+ * @param name - Record key in loop.yaml.
+ * @returns The record's `vars`, or undefined when no record has that name.
+ */
+export declare function loopRecordVars(name: string): Readonly<Record<string, string>> | undefined;
+/** Rubric the verifier scores against: the round's own checklist plus the record's standard.
+ *
+ * The standard is part of the record, so it travels with the run instead of living in session
+ * state; a record without one scores on its checklist alone.
+ * @param checks - This round's checklist.
+ * @param standard - The record's extra requirements, when it declares any.
+ * @returns The rubric text.
+ */
+export declare function roundStandard(checks: string, standard?: string): string;
+/** Build one record, or undefined when no record has that name.
+ *
+ * The record's data is read once here, so a run keeps the rubric, standard and vars it started
+ * with even if `loop.yaml` is edited (or reloaded) while it is in flight.
+ * @param name - Record key in loop.yaml.
+ * @param forked - Delegate each round's verdict to an independent verifier process.
+ * @param vars - Values that replace the record's own `vars` for this run, e.g. another document.
+ * @param selfScoring - Whether this client's own reply may decide an attempt. Without a forked
+ *   verifier it always does; with one, only when the operator allowed the verifier's fallback to it.
+ *   When it does not, the brief stops asking for a verdict block: nothing reads it, and a visible
+ *   score that moves nothing is exactly what a reader mistakes for the real one.
+ * @returns The protocol the scored loop runs, or undefined for an unknown name.
+ */
+export declare function loopProtocolFor(name: string, forked?: boolean, vars?: Readonly<Record<string, string>>, selfScoring?: boolean): LoopProtocol | undefined;

package/dist/controller/loop-protocols.js

@@ -0,0 +1,115 @@
+/** Turn one loop.yaml record into the protocol the scored loop runs.
+ *
+ * The record is the whole protocol: title, steps, rubric, brief, follow-up, artifact and the extra
+ * standard. This module only wires that data to the mechanical contract in `loop-contract.ts`, so a
+ * new review protocol is a YAML edit — not a new TypeScript file — and `/loop <name>` can run any
+ * record without code knowing which one it is.
+ */
+import { LOOP_MARKER, followUpContract, resultContract, verdictBrief } from "./loop-contract.js";
+import { loopPrompts } from "./loop-prompts.js";
+import { coversWholeProtocol } from "./loop.js";
+/** Names `/loop` may run, in file order. */
+export function loopProtocolNames() {
+    return [...loopPrompts().names];
+}
+/** Every record `/loop` may run, in file order, with the defaults a run would start from.
+ *
+ * The list and the run read the same records, so a chooser can show exactly the name, round count,
+ * artifact and defaults the runner would use — never a second table that could drift.
+ * @returns One summary per record.
+ */
+export function loopRecords() {
+    return loopPrompts().names.flatMap(name => {
+        const text = loopPrompts().find(name);
+        if (text === undefined)
+            return [];
+        return [{ name, title: text.title, steps: text.steps,
+                ...(text.artifact === undefined ? {} : { artifact: text.artifact }),
+                defaultScore: text.defaultScore, defaultTries: text.defaultTries,
+                vars: loopPrompts().vars(name) }];
+    });
+}
+/** One record's declared variables, so a caller can offer or validate them before a run starts.
+ * @param name - Record key in loop.yaml.
+ * @returns The record's `vars`, or undefined when no record has that name.
+ */
+export function loopRecordVars(name) {
+    return loopPrompts().find(name) === undefined ? undefined : loopPrompts().vars(name);
+}
+/** Rubric the verifier scores against: the round's own checklist plus the record's standard.
+ *
+ * The standard is part of the record, so it travels with the run instead of living in session
+ * state; a record without one scores on its checklist alone.
+ * @param checks - This round's checklist.
+ * @param standard - The record's extra requirements, when it declares any.
+ * @returns The rubric text.
+ */
+export function roundStandard(checks, standard) {
+    return standard === undefined ? checks : `${checks}\n\n附加要求（记录自带）：\n${standard}`;
+}
+/** Build one record, or undefined when no record has that name.
+ *
+ * The record's data is read once here, so a run keeps the rubric, standard and vars it started
+ * with even if `loop.yaml` is edited (or reloaded) while it is in flight.
+ * @param name - Record key in loop.yaml.
+ * @param forked - Delegate each round's verdict to an independent verifier process.
+ * @param vars - Values that replace the record's own `vars` for this run, e.g. another document.
+ * @param selfScoring - Whether this client's own reply may decide an attempt. Without a forked
+ *   verifier it always does; with one, only when the operator allowed the verifier's fallback to it.
+ *   When it does not, the brief stops asking for a verdict block: nothing reads it, and a visible
+ *   score that moves nothing is exactly what a reader mistakes for the real one.
+ * @returns The protocol the scored loop runs, or undefined for an unknown name.
+ */
+export function loopProtocolFor(name, forked = false, vars, selfScoring = !forked) {
+    const text = loopPrompts().find(name, vars);
+    if (text === undefined)
+        return undefined;
+    const standard = (step) => roundStandard(text.checks(step), text.standard);
+    const artifact = text.artifact;
+    // A run over the whole record ends on its consolidation round, and that round is the only place
+    // where "passed" may mean the whole artifact: the verifier is handed every earlier round to
+    // re-check, so a later round that broke an earlier requirement cannot pass unnoticed.
+    const consolidates = (limits, step) => coversWholeProtocol(limits.from, limits.to, text.steps) && step === text.steps;
+    const coverage = (step) => Array.from({ length: Math.max(0, step - 1) }, (_, index) => ({ title: `第 ${index + 1} 轮 · ${text.roundTitle(index + 1)}`, checks: text.checks(index + 1) }));
+    return {
+        marker: LOOP_MARKER,
+        kind: name,
+        title: text.title,
+        steps: text.steps,
+        ...(artifact === undefined ? {} : { artifact }),
+        defaultScore: text.defaultScore,
+        defaultTries: text.defaultTries,
+        ...(text.starts === undefined ? {} : { starts: text.starts }),
+        stepLabel: step => text.roundTitle(step),
+        artifactMarker: step => text.artifactMarker(step),
+        brief: (limits, step, attempt) => [
+            ...text.brief({ ...limits, step, attempt }),
+            '',
+            ...resultContract(name, limits, step, attempt, {
+                standard: standard(step),
+                ...(artifact === undefined ? {} : { artifact }),
+                ...(text.focus(step) === undefined ? {} : { focus: text.focus(step) }),
+                ...(consolidates(limits, step) ? { final: true } : {}),
+            }, forked ? 'forked' : 'subagent', selfScoring),
+        ].join('\n'),
+        // The verifier's only input is this prompt and the artifact, so the run's own variables travel
+        // with it: without `path` it cannot tell which document this run reviews and can only follow the
+        // artifact left by an earlier run against a different one.
+        ...(forked ? { verify: (limits, step, attempt, target, previous) => {
+                // The verifier is told the same heading the client will check, so "which section is this round's"
+                // is one fact on both sides instead of two readings of the same file.
+                const marker = text.artifactMarker(step);
+                return verdictBrief({
+                    ...target, kind: name, step, attempt, previous, standard: standard(step), vars: text.vars,
+                    ...(artifact === undefined ? {} : { artifact }),
+                    ...(marker === undefined ? {} : { marker }),
+                    ...(text.focus(step) === undefined ? {} : { focus: text.focus(step) }),
+                    ...(consolidates(limits, step) ? { coverage: coverage(step) } : {}),
+                });
+            } } : {}),
+        followUp: (limits, step, attempt) => [
+            ...text.followUp({ ...limits, step, attempt }),
+            followUpContract(name, step, attempt, selfScoring),
+        ].join('\n'),
+    };
+}

package/dist/controller/loop.d.ts

@@ -0,0 +1,275 @@
+/** The generic scored agent loop: what any "run steps until they pass" command reuses.
+ *
+ * A protocol supplies the prompt text and the step count; this module supplies everything else —
+ * the step/attempt state machine, the passing-score decision, and the reply parser. The controller
+ * adds the I/O around it (sending, watching for the turn to end, cancellation), so a second review
+ * command only writes a `LoopProtocol`.
+ */
+import type { LoopActivity, LoopLimits, LoopProgress, LoopTerminalReason } from '../contracts.ts';
+import type { LoopOptions } from '../slash/index.ts';
+import type { Message } from '../session/transcript.ts';
+/** One protocol's fully resolved limits, shared with the form that confirms them. */
+export type { LoopLimits };
+/** What one loop run is: its label, its step count, and the prompts it sends. */
+export interface LoopProtocol {
+    /** Fence marker of the reply's result block, without the backticks, e.g. `dsht-loop`. */
+    marker: string;
+    /** `kind` the result block must declare, so one marker can serve several protocols. */
+    kind: string;
+    /** Label shown in the progress line, e.g. `Design review`. */
+    title: string;
+    /** Steps the protocol defines; `--to` defaults to this. */
+    steps: number;
+    /** Workspace file the rounds maintain, when there is one; verified for tampering when readable. */
+    artifact?: string;
+    /** Line that file must contain once one step is done, when the protocol requires one.
+     *
+     * The score is the verifier's judgement; whether the round's conclusion actually reached the
+     * artifact is a fact this client checks, and a hard condition no score may override.
+     */
+    artifactMarker?(step: number): string | undefined;
+    /** Optional name of one step, shown in the progress line. */
+    stepLabel?(step: number): string;
+    /** Passing score used when the command omits `--score`; default 8. */
+    defaultScore?: number;
+    /** Attempts per step used when the command omits `--tries`; default 10. */
+    defaultTries?: number;
+    /** Which phase a step starts in: verifying the existing artifact, or working on it.
+     *
+     * A review of something that already exists starts by verifying it, so a step that passes costs
+     * no work turn; anything else starts by asking for the work. Defaults to `work`.
+     */
+    starts?: 'verify' | 'work';
+    /** Opening prompt for one step and attempt. */
+    brief(limits: LoopLimits, step: number, attempt: number): string;
+    /** Prompt for a later attempt, once the protocol is already in context. */
+    followUp(limits: LoopLimits, step: number, attempt: number): string;
+    /** Prompt a forked verifier session receives for one finished round.
+     *
+     * A protocol that defines this delegates the verdict to an independent process and names the file
+     * that process must write. Independent verification is the only scorer: a reply block is never
+     * used to override its absence, so an outage stops the run instead of passing it.
+     * @param limits - Resolved run limits.
+     * @param step - Step in flight.
+     * @param attempt - Attempt in flight.
+     * @param target - Where the verdict goes and the identity it must declare.
+     * @param previous - What the previous attempt on this step concluded, when there was one.
+     * @returns The verifier's prompt.
+     */
+    verify?(limits: LoopLimits, step: number, attempt: number, target: VerifyTarget, previous?: PriorVerdict): string;
+}
+/** What one reply's result block reported. */
+export interface LoopResult {
+    /** Completion score in 0–10; absent when the block omitted or malformed it. */
+    score?: number;
+    /** What the verifier called it; advisory only — the loop decides from `score`, `blocked` and `abstained`. */
+    status?: 'done' | 'retry' | 'blocked' | 'abstained';
+    /** The verifier proved the task impossible at any score; the one field that overrides `score`. */
+    blocked?: boolean;
+    /** The verifier cannot judge and needs a person; ends the run without a score. */
+    abstained?: boolean;
+    /** Why it stopped, when it stopped before the budget: `cannot-fix` or `needs-human`. */
+    exitReason?: 'cannot-fix' | 'needs-human';
+    /** That reason in one line a reader can act on; required by an `exitReason`. */
+    reason?: string;
+    /** One line a person must supply, when the verifier asked for one. */
+    needs?: string;
+    /** Advisory note that never changes control: "nothing to change here", "already covered", … */
+    explanation?: string;
+    /** What the verifier still objects to, so the next attempt can answer it. */
+    findings?: readonly string[];
+    /** The basis it gave for the score, so a retry does not have to guess. */
+    evidence?: string;
+}
+/** Where one round's verdict goes, and the identity that file must declare. */
+export interface VerifyTarget {
+    /** Absolute path the verdict must be written to. */
+    file: string;
+    /** Identity embedded in the verdict, checked before the round. */
+    verificationId: string;
+}
+/** What the previous attempt on this step concluded, when there was one. */
+export interface PriorVerdict {
+    /** Step that attempt belonged to. */
+    step: number;
+    /** Attempt number it was. */
+    attempt: number;
+    /** Its verdict. */
+    result: LoopResult;
+}
+/** What one consumed attempt decided. */
+export type LoopStepResult = {
+    kind: 'continue';
+    prompt: string;
+} | {
+    kind: 'passed';
+} | {
+    kind: 'exhausted';
+} | {
+    kind: 'stalled';
+} | {
+    kind: 'blocked';
+} | {
+    kind: 'needs-human';
+};
+/** Apply a protocol's defaults and reject a range that cannot run.
+ * @param protocol - Protocol being started.
+ * @param options - Flags exactly as parsed, absent when the operator omitted them.
+ * @returns The resolved limits, or undefined when `to < from`.
+ */
+export declare function resolveLoop(protocol: LoopProtocol, options: LoopOptions): LoopLimits | undefined;
+/** Whether a run's rounds cover the whole record rather than a selected range.
+ *
+ * Only this case may report more than "the rounds that ran passed": the last round is then the
+ * record's consolidation round, and the verifier is handed every earlier round to re-check.
+ * @param from - First step of the run.
+ * @param to - Last step of the run.
+ * @param steps - Steps the protocol defines.
+ * @returns True when the run starts at the first round and ends at the last one.
+ */
+export declare function coversWholeProtocol(from: number, to: number, steps: number): boolean;
+/** Read the result out of the last block of one reply.
+ *
+ * The block must be in the assistant's text, not reasoning, and this takes the last one so a reply
+ * that quotes its verifier still reports its own verdict. A missing, malformed or foreign block is
+ * undefined; a valid block with no usable field is an empty result, which counts as a failed attempt.
+ * @param text - One turn's assistant text.
+ * @param protocol - Protocol whose marker and kind identify the block.
+ * @returns The reported score and verdict, or undefined when the reply carries no valid block.
+ */
+export declare function parseLoopResult(text: string, protocol: Pick<LoopProtocol, 'marker' | 'kind'>): LoopResult | undefined;
+/** Validate the score and verdict of one decoded result object.
+ *
+ * Shared with the forked verifier's verdict file, so a score means the same thing however it
+ * travelled: an out-of-range or unknown field is absent rather than a value the loop would trust.
+ * @param parsed - Decoded object expected to carry `score` and `status`.
+ * @returns The usable fields; an empty result when the object carried none, and `undefined` when it
+ *   claimed an early stop that breaks the rules — such a claim is not a verdict at all, so the
+ *   caller reports verification as unusable instead of guessing what was meant.
+ */
+export declare function readResultFields(parsed: object): LoopResult | undefined;
+/** Assistant text of the turn that just finished: from the last user/context row to the end.
+ * @param messages - Projected conversation messages.
+ * @returns The assistant text, empty when the turn produced none.
+ */
+export declare function latestAssistantText(messages: readonly Message[]): string;
+/** One run of the loop: which step and attempt is in flight, and what happens next.
+ *
+ * No I/O: the controller sends the prompt this returns and feeds back the parsed score, which keeps
+ * the state machine trivially testable and identical for every protocol.
+ */
+export declare class ScoredLoop {
+    readonly runId: string;
+    readonly sessionId: string;
+    readonly protocol: LoopProtocol;
+    private readonly limits;
+    private step;
+    private attempt;
+    private best;
+    private noProgress;
+    private phase;
+    private awaiting;
+    /** What the live run is waiting on; only the controller's own sends and verdicts set it. */
+    private activity?;
+    /** Why the run stopped; set once, together with a terminal phase. */
+    private terminalReason?;
+    private noteText?;
+    private interaction?;
+    private exit?;
+    /** When this run began, so a reader can clock it even while no host turn is running. */
+    private readonly startedAt;
+    constructor(runId: string, sessionId: string, protocol: LoopProtocol, limits: LoopLimits);
+    /** Snapshot the UI renders; the loop keeps the authoritative numbers. */
+    get progress(): LoopProgress;
+    /** Attach one line about the attempt just decided, shown until the next verdict replaces it.
+     * @param text - Note to show, or an empty string to clear it.
+     */
+    note(text: string): void;
+    /** Whether the run still owns its session: it may send, settle — or be answered.
+     *
+     * A paused run counts: it is not finished, so a new run must not silently replace it (§8.3.1). What
+     * it is *not* doing is working; `activity` is absent while it waits.
+     */
+    get active(): boolean;
+    /** Whether this run has sent any prompt yet, so `intro` knows the opening one is still owed. */
+    private briefed;
+    /** Whether a prompt was sent and its reply is still outstanding. */
+    get settled(): boolean;
+    /** The opening prompt; the caller sends it and then calls `sent()`. */
+    start(): string;
+    /** The opening prompt, when this run has not sent one yet; undefined once it has.
+     *
+     * A record that verifies first never sends its brief at the start — it checks the artifact instead —
+     * so the first work message after a failed check has to be the brief. A follow-up would open with
+     * "read the results and opinions above" and refer to a previous version, and neither exists on the
+     * first work turn; the round's own checklist only reaches the agent through this prompt.
+     */
+    intro(): string | undefined;
+    /** The prompt that asks for work on the step in flight: the owed brief, else the follow-up. */
+    workPrompt(): string;
+    /** Record that the outstanding prompt reached the host. */
+    sent(): void;
+    /** Record that this attempt is judged by a forked verifier instead of the session's own turn. */
+    verifying(): void;
+    /** Record that the turn ended and its result is being read, which is neither work nor a verdict. */
+    settling(): void;
+    /** Consume one finished attempt.
+     * @param result - Parsed result, or undefined when the reply carried no usable block.
+     * @returns What the loop does next.
+     */
+    settle(result: LoopResult | undefined): LoopStepResult;
+    /** Stop the run; a cancelled run never sends again.
+     * @param reason - Who ended it, so a cancellation is not confused with a verdict.
+     */
+    cancel(reason?: LoopTerminalReason): void;
+    /** End the run because independent verification was impossible.
+     *
+     * Deliberately not a verdict: no attempt is consumed, so the run stops on an infrastructure
+     * failure instead of pretending the reviewer produced nothing.
+     * @param reason - Which verification failure ended it.
+     */
+    unavailable(reason?: LoopTerminalReason): void;
+    /** End the run because the whole-run deadline expired.
+     *
+     * A budget stop, not a verdict: it bounds the sum of all steps, attempts and verifier retries, so
+     * no attempt is consumed and `best` is untouched.
+     */
+    deadline(): void;
+    /** Pause the run because a judgment asked for a person.
+     *
+     * Deliberately not terminal: no `terminalReason` is written, so the run still owns its session and
+     * the progress line can offer `/loop answer` or `/loop abort` instead of a summary.
+     * @param request - What is being asked, and what the answer has to supply.
+     */
+    pause(request: {
+        kind: string;
+        text: string;
+        needs?: string;
+    }): void;
+    /** Resume a paused run after the operator supplied what the judgment was missing.
+     *
+     * No attempt is consumed: the answer only adds a condition, and the current artifact is judged again
+     * under a new verification identity. The attempt counts as outstanding, so that verdict may decide it.
+     */
+    resume(activity?: LoopActivity): void;
+    /** The prompt that asks again with the operator's addition.
+     *
+     * Used when no forked verifier judges this run: the answer becomes the next attempt's instruction
+     * instead of a condition for a judgment, and asking again costs no attempt by itself.
+     * @param answer - What the operator supplied.
+     * @returns The prompt to send.
+     */
+    answerPrompt(answer: string): string;
+    /** End the run because the request cannot be answered from here.
+     *
+     * Used for the cases the operator cannot unblock through this client — a verifier child whose own
+     * session asked a question, or a prompt the host refused to accept — as opposed to `pause`, where
+     * `/loop answer` supplies what the judgment was missing. No attempt is consumed in either case.
+     * @param request - The approval or question the host is waiting for, or a verdict's request.
+     * @param reason - Which kind of human request this is.
+     */
+    human(request: {
+        kind: string;
+        text: string;
+    }, reason?: LoopTerminalReason): void;
+}