@basein/runner 0.2.8 → 0.2.11

package/dist/bin/investigate.js

@@ -183,7 +183,7 @@ export const DECLINES = {
     },
     nondeterministic_first_step: {
         cause: "the chain's first step needs a judgement the calculation could not write code for, so the plan cannot start.",
-        fix: "the agent does this task itself; a model step for such judgements is planned (plan-services.md W3.1).",
+        fix: "if its code only has a slip, fix the step yourself: read it with `bir scenario show <scnId> --step 0`, write the input logic to a file, and run `bir scenario edit <scnId> --step 0 --input-logic <file>`; the service checks it against the recording before it saves it. A real judgement — a choice with no fixed rule — stays with the agent until a model step exists (plan-services.md W3.1).",
     },
     unusable_first_step: {
         cause: "the first step calls a sub-task that is gone, switched off or stale.",

package/dist/bin/scenario-edit.d.ts

@@ -0,0 +1,173 @@
+/**
+ * scenario-edit — read, check, change and undo one step of a calculated
+ * scenario (editSteps.md in the BaseIn repository; docs/calculatedReplayGuide.md §9.2).
+ *
+ *   bir scenario show  <runId|scnId> [--step <n>]
+ *   bir scenario check <runId|scnId> --step <n> [--input-logic <file|->] [--output-logic <file|->] [--unfreeze]
+ *   bir scenario edit  <runId|scnId> --step <n> [--input-logic <file|->] [--output-logic <file|->]
+ *                      [--freeze | --unfreeze] [--note "why"] [--force --note "why"] [--revision <n>]
+ *   bir scenario edits <runId|scnId>
+ *   bir scenario undo  <runId|scnId> [--edit <sedit_id>]
+ *   bir scenario calc  <runId> [--force [--discard-edits]]
+ *   bir scenario editing on|off|status
+ *
+ * WHY THIS IS A CLIENT AND NOTHING MORE. Whether a change may be saved is
+ * decided on the service, against the recording, by the calculation's own
+ * check (D3) — and `check` and `edit` are the same function there (D11). A
+ * runner-side pre-check would be a second opinion that can disagree with the
+ * one that counts, so this module reads logic from files, sends it, and says
+ * in words what the service answered. `--json` prints the answer unchanged,
+ * which is what the `bir` MCP server hands the model.
+ *
+ * Logic never comes from the command line itself. A JavaScript body is full
+ * of quotes, braces and `$`, and every shell mangles a different subset of
+ * them; a file, or stdin with `-`, arrives byte for byte.
+ *
+ * Everything the commands touch is injected ({@link ScenarioEditDeps}), as in
+ * `investigate.ts`, so all of it is tested in-process against a fake service.
+ * The exception is `editing`, which writes the install sidecar — tests point
+ * `BIR_HOME` at a temporary directory for that.
+ */
+export type InputStatus = "reproduces" | "differs" | "throws" | "copy" | "not_checked";
+export interface EditReport {
+    ok: boolean;
+    stepIndex: number;
+    toolName: string | null;
+    /** The recording the change was checked against. */
+    sourceRunId: string;
+    verifiable: boolean;
+    input: {
+        changed: boolean;
+        before: InputStatus;
+        after: InputStatus;
+        computed?: unknown;
+        recorded?: unknown;
+        firstDifference?: {
+            at: number;
+            computed: string;
+            recorded: string;
+        };
+        error?: string;
+    };
+    output: {
+        changed: boolean;
+        status: "runs" | "throws" | "not_object" | "unchanged";
+        emittedKeys?: string[];
+        error?: string;
+    };
+    later: Array<{
+        stepIndex: number;
+        toolName: string | null;
+        before: InputStatus;
+        after: InputStatus;
+        regressed: boolean;
+    }>;
+    answer: {
+        informativeBefore: boolean;
+        informativeAfter: boolean;
+    } | null;
+    mark: {
+        before: MarkState;
+        after: MarkState;
+    };
+    problems: string[];
+}
+interface MarkState {
+    marked: boolean;
+    why: string | null;
+}
+export interface StepState {
+    toolInputLogic: string | null;
+    toolOutputLogic: string | null;
+    nondeterministic: boolean;
+    nondeterministicWhy: string | null;
+    editedAt: string | null;
+    editForced: boolean;
+}
+export interface EditEntry {
+    id: string;
+    scenarioId: string;
+    stepIndex: number;
+    kind: "edit" | "freeze" | "revert";
+    revertsEditId: string | null;
+    note: string | null;
+    forced: boolean;
+    chainRevisionBefore: number;
+    chainRevisionAfter: number;
+    before: StepState;
+    after: StepState;
+    report: EditReport | null;
+    createdAt: string;
+    /** A later undo put this one back. */
+    revertedAt: string | null;
+    /** A recalculation replaced the chain; the entry is history now. */
+    replacedAt: string | null;
+}
+export type ServiceReply = {
+    status: number;
+    body: unknown;
+} | {
+    error: string;
+};
+export interface ScenarioEditDeps {
+    cwd: string;
+    out: (line?: string) => void;
+    /** An authenticated call to the service; a failure to reach it is `{ error }`, never a throw. */
+    service: (method: string, path: string, body?: unknown) => Promise<ServiceReply>;
+    /** A logic file's bytes. Relative paths are the caller's to resolve. */
+    readFile: (path: string) => Buffer;
+    /** All of stdin, for `--input-logic -` / `--output-logic -`. */
+    readStdin: () => Promise<Buffer>;
+}
+export interface ScenarioEditArgs {
+    /** The words after `bir scenario`: `[sub, target | on|off|status, …]`. */
+    positionals: string[];
+    json: boolean;
+    force: boolean;
+    step?: number;
+    /** A path, or `-` for stdin. */
+    inputLogic?: string;
+    outputLogic?: string;
+    freeze: boolean;
+    unfreeze: boolean;
+    note?: string;
+    /** `undo --edit`: the `sedit_` id to put back. */
+    edit?: string;
+    /** `--revision`: save only if the plan is still at this `chainRevision`. */
+    revision?: number;
+    discardEdits: boolean;
+}
+/** The `bir scenario` words this module answers; `list` and `replay` stay in bir.ts. */
+export declare const SCENARIO_EDIT_SUBCOMMANDS: ReadonlySet<string>;
+/** The `bir` MCP server's tools that only read: always offered (D2). */
+export declare const READ_TOOLS: readonly ["scenario_show", "scenario_edits", "investigate"];
+/** The ones that change a scenario: offered only after `bir scenario editing on` (D2). */
+export declare const EDIT_TOOLS: readonly ["scenario_check", "scenario_edit", "scenario_undo"];
+export declare function scenarioEditCommand(args: ScenarioEditArgs, deps: ScenarioEditDeps): Promise<number>;
+/**
+ * A logic file's text. UTF-8, with a byte-order mark dropped — and UTF-16 with
+ * its mark decoded, because that is what `"…" > step.js` writes in Windows
+ * PowerShell 5.1, and a service answering "SyntaxError" to a file that looks
+ * fine in every editor is a riddle nobody should have to solve.
+ */
+export declare function decodeLogic(bytes: Buffer): string;
+/**
+ * The report in the lines editSteps.md "What a person sees" shows:
+ * `input`, `output` (when the output logic changed), `later`, `answer` (when
+ * the final answer read anything before) and `mark`.
+ */
+export declare function renderReport(out: (line?: string) => void, r: EditReport): void;
+/**
+ * About {@link CONTEXT} characters either side of `at`. A text already that
+ * short — a window the service cut itself, or a small call — is printed whole.
+ */
+export declare function around(text: string, at: number): string;
+/**
+ * Undo puts one step back as it was before its newest edit (D9). Without
+ * `--edit`, that is the newest entry nothing has put back and no
+ * recalculation replaced — which is by construction the newest of its step.
+ * An undo is itself such an entry, so a second `undo` redoes.
+ */
+export declare function newestUndoable(edits: EditEntry[]): EditEntry | undefined;
+export {};
+//# sourceMappingURL=scenario-edit.d.ts.map