@plurnk/plurnk-service 0.44.0 → 0.45.0

package/dist/core/Engine.js

@@ -71,6 +71,7 @@ const readManifestItems = () => {
         return null;
     return normalizeManifestItems(Number.parseInt(raw, 10));
 };
+import { ProviderError } from "@plurnk/plurnk-providers";
 // Resolution timeout — proposed entries auto-cancel if nothing arrives
 // within this window. SPEC.md §engine-rails (proposal lifecycle) + §methods (loop.resolve).
 const PROPOSAL_TIMEOUT_DEFAULT_MS = 300000;
@@ -599,7 +600,7 @@ class Engine {
         // it, not a 404; same plurnk-origin foist as the operator docs.
         if (seq === 1) {
             // #231 — a session's client-chosen manifestItems REPLACES the env default outright.
-            const { manifestItems: sessionMI } = await SessionSettings.read(this.#db, sessionId);
+            const { manifestItems: sessionMI, autoReadAgents } = await SessionSettings.read(this.#db, sessionId);
             const manifestItems = sessionMI !== null ? normalizeManifestItems(sessionMI) : readManifestItems();
             if (manifestItems !== null) {
                 const manifestRead = {
@@ -618,6 +619,30 @@ class Engine {
                 });
                 nextActionIndex++;
             }
+            // #250 — auto-READ the project's AGENTS.md scratchpad into THIS first model turn
+            // when the session opted in AND it's a member. The client picks it (gitignored by
+            // convention → not a git member); the engine READs it here so its body is part of
+            // turn-1's log — a normal file:/// member READ (the model sees only the READ; it
+            // stays read-write, so the model edits the scratchpad back as it evolves).
+            if (autoReadAgents === true) {
+                const agentsMember = await this.#db.crud_get_member_sig.get({ session_id: sessionId, scheme: null, pathname: "/AGENTS.md" });
+                if (agentsMember !== undefined) {
+                    const agentsRead = {
+                        op: "READ", suffix: "", signal: null, lineMarker: null,
+                        target: {
+                            kind: "url", raw: "file:///AGENTS.md", scheme: "file",
+                            username: null, password: null, hostname: null, port: null,
+                            pathname: "/AGENTS.md", params: {}, fragment: null,
+                        },
+                        body: null, position: { line: 1, column: 1 },
+                    };
+                    await this.dispatch({
+                        statement: agentsRead, sessionId, runId, loopId, turnId,
+                        sequence: nextActionIndex, origin: "plurnk", onDispatch,
+                    });
+                    nextActionIndex++;
+                }
+            }
         }
         // §env-delta — pre-seed environment deltas (changes since this run last
         // reconciled) as system EDIT rows, before the packet composes; advance
@@ -661,7 +686,31 @@ class Engine {
         // decode at the free window so a runaway can't reach the context wall.
         const genCeiling = _a.computeCeiling(provider.contextSize, this.#budgetCeiling); // provider.contextSize, the immutable identity, read by the budget — §provider-surface-identity
         const maxTokens = genCeiling === null ? undefined : Math.max(1, genCeiling - requestPacket.tokens);
-        const response = await provider.generate({ messages: modelMessages, runId: String(runId), signal, grammar: await this.#grammarConstraint(), maxTokens }); // §provider-surface-generate §provider-guarantees-single-call §provider-guarantees-signal-wired
+        let response;
+        // #249 — plugin attribution tags onto the per-turn generate() wire. Value is the
+        // active-plugin set (placeholder); real per-turn grounding is deferred.
+        const attributions = [...new Set([...this.#schemes.attributions(), ...(this.#executors?.attributions() ?? [])])].toSorted();
+        try {
+            response = await provider.generate({ messages: modelMessages, runId: String(runId), signal, grammar: await this.#grammarConstraint(), maxTokens, attributions: attributions.length > 0 ? attributions : undefined }); // §provider-surface-generate §provider-guarantees-single-call §provider-guarantees-signal-wired §attribution-plurnk-namespace-reserved
+        }
+        catch (err) {
+            // #256 — grammar_unenforced is the one provider error the MODEL can recover from:
+            // the backend didn't constrain the GBNF, so this turn's output was rejected, but a
+            // conforming emission next turn is accepted. Surface it as telemetry (the model's
+            // next packet shows it) and fall through as an empty no-op turn, so the strike rail
+            // gives it maxStrikes chances before terminating — unlike infra errors (rate_limit,
+            // network_failure, unauthorized), which propagate and end the loop.
+            if (err instanceof ProviderError && err.kind === "grammar_unenforced") {
+                this.#pushTelemetry(sessionId, loopId, { source: "provider", kind: "grammar_unenforced", message: err.message });
+                response = {
+                    assistant: { content: "", reasoning: null, usage: { prompt: requestPacket.tokens, completion: 0, reasoning: 0, cached: 0, total: requestPacket.tokens }, finishReason: null, model: provider.model },
+                    assistantRaw: null,
+                };
+            }
+            else {
+                throw err;
+            }
+        }
         // Engine splits wire-level response: emission (content, reasoning,
         // parsed ops) → packet.assistant per Packet.json §assistant;
         // call-metadata (usage, finishReason, model) → Turn columns per
@@ -691,10 +740,10 @@ class Engine {
             });
         }
         const opsCount = packetAssistant.ops.length;
-        // Informational SEND[103] broadcasts (#free-text-capture) are log rows, not
-        // actions: excluded from the real-op count so a prose-only turn still strikes
+        // PLAN (reasoning) and informational SEND[103] are no-ops, not actions: both are
+        // excluded from the real-op count so a PLAN-only or prose-only turn still strikes
         // as no-ops, and the terminal scan ignores 1xx so they never set turnStatus.
-        const realOpsCount = packetAssistant.ops.filter((op) => !(op.op === "SEND" && op.signal === 103 && op.target === null)).length;
+        const realOpsCount = packetAssistant.ops.filter((op) => op.op !== "PLAN" && !(op.op === "SEND" && op.signal === 103 && op.target === null)).length;
         const sendOp = packetAssistant.ops.findLast((op) => op.op === "SEND" && typeof op.signal === "number" && op.signal >= 200);
         // Rail #41 (revised): the per-turn requirement is "emit at least one
         // op," not "emit a terminal SEND." SEND is purely a signal verb; many
@@ -728,7 +777,14 @@ class Engine {
         // its emission was truncated.
         // #232 — a session's maxCommands is a tighten-only ceiling: min() the env ceiling.
         const maxCommands = Math.min(readMaxCommands(), (await SessionSettings.read(this.#db, sessionId)).maxCommands ?? Number.POSITIVE_INFINITY);
-        const opsToDispatch = packetAssistant.ops.slice(0, maxCommands);
+        // PLAN (reasoning) and a terminal SEND (signal ≥ 200, the conclusion) are not
+        // actions — they always dispatch and never count against the cap. maxCommands
+        // bounds real actions only; maxCommands:0 still admits a plan and a conclusion
+        // (the PLAN/SEND ops, zero actions), which is its only coherent meaning.
+        let realCommands = 0;
+        const opsToDispatch = packetAssistant.ops.filter((op) => op.op === "PLAN"
+            || (op.op === "SEND" && typeof op.signal === "number" && op.signal >= 200)
+            || realCommands++ < maxCommands);
         const droppedCount = opsCount - opsToDispatch.length;
         const statuses = [];
         for (const [i, statement] of opsToDispatch.entries()) {
@@ -772,46 +828,26 @@ class Engine {
         const { assistant } = response;
         const preParsedOps = assistant.ops;
         const ops = [];
-        // #plan-reasoning: PLAN bodies are the model's in-band reasoning — hoisted
-        // out of the op stream into the reasoning field, never dispatched as a log op.
-        // Free text becomes informational SEND[103] log ops (#free-text-capture) below.
-        const planFragments = [];
-        const hoistPlan = (op) => {
-            if (op.op !== "PLAN")
-                return false;
-            const raw = (op.body ?? "").trim();
-            if (raw.length > 0)
-                planFragments.push(raw);
-            return true;
-        };
+        // PLAN is an ordinary op — emitted by the model, dispatched, and passed to the
+        // client as a log entry. No special hoisting into the reasoning field (that
+        // legacy paradigm is abandoned). Interstitial free text is DROPPED — the prior
+        // #free-text-capture synthesis of SEND[103] log ops was retired as tech debt
+        // (grammar 0.70 forbids free text between ops, so a prose-only turn strikes 422).
         // Full PlurnkParseError context (line/column/source) is preserved
         // here so runTurn can build TelemetryEvent envelopes per the
         // grammar 0.17.0 protocol — model needs position info to locate
         // its own offending content on the next turn.
         const parseErrors = [];
         if (preParsedOps !== undefined) {
-            for (const op of preParsedOps)
-                if (!hoistPlan(op))
-                    ops.push(op);
+            ops.push(...preParsedOps);
         }
         else {
             const parsed = PlurnkParser.parse(assistant.content);
             for (const item of parsed.items) {
                 if (item.kind === "statement") {
-                    if (!hoistPlan(item.statement))
-                        ops.push(item.statement);
-                }
-                else if (item.kind === "text") {
-                    // #free-text-capture: interstitial prose → an informational
-                    // SEND[103] broadcast log op, interleaved in emission order.
-                    const trimmed = item.text.trim();
-                    if (trimmed.length > 0)
-                        ops.push({
-                            op: "SEND", suffix: "", signal: 103, target: null,
-                            lineMarker: null, body: { raw: trimmed, json: null },
-                            position: item.position ?? { line: 1, column: 1 },
-                        });
+                    ops.push(item.statement);
                 }
+                // Free text (kind "text") is dropped — #free-text-capture retired (above).
                 else if (item.kind === "error") {
                     const err = item.error;
                     if (err instanceof PlurnkParseError) {
@@ -834,10 +870,7 @@ class Engine {
                 parseErrors.push({ message: tail.reason, line: tail.from.line, column: tail.from.column, source: "grammar" });
             }
         }
-        const wireReasoning = assistant.reasoning ?? "";
-        const planReasoning = planFragments.join("\n\n");
-        const reasoningParts = [wireReasoning, planReasoning].filter((s) => s.length > 0);
-        const reasoning = reasoningParts.length > 0 ? reasoningParts.join("\n\n") : null;
+        const reasoning = assistant.reasoning ?? null;
         return {
             packetAssistant: { content: assistant.content, ops, reasoning },
             callMetadata: { usage: assistant.usage, finishReason: assistant.finishReason, model: assistant.model },
@@ -850,9 +883,10 @@ class Engine {
     // the stored packet and the wire payload share one source of truth.
     async #buildRequestPacket({ initialMessages, requirements, runId, loopId, currentTurnSeq, provider, gitStatus, telemetryErrors: presetTelemetry, }) {
         const byRole = (role) => initialMessages.filter((m) => m.role === role).map((m) => m.content).join("\n\n");
-        // plurnk.md (grammar/dialects only — grammar 0.49+ is scheme-agnostic). The
-        // scheme catalogue is now its OWN section (`schemes`, below tools), so the
-        // definition is just the operator's system prompt — tools sits right below it.
+        // plurnk.md (grammar/dialects) ONLY — the definition is the hot-path grammar.
+        // The scheme catalogue is its own `schemes` section below tools (§schemes-directory),
+        // NOT appended here: grammar 0.49+ is scheme-agnostic, so the service advertises
+        // the scheme set at packet-time (grammar#239 item 7) via SchemeRegistry.teach().
         const system_definition = byRole("system");
         // the prompt section sources from the loop's most recent prompt entry first
         // (plurnk:///prompt/<loop_id>/<N> for the highest N written to date).
@@ -869,11 +903,11 @@ class Engine {
         // requirements). Read Paths.defaultRequirements (PLURNK_REQUIREMENTS env →
         // requirements.md) fresh each build so edits take effect; a non-empty param wins.
         const baseRequirements = requirements.length > 0 ? requirements : await readFile(Paths.defaultRequirements, "utf8");
-        // The op syntax leads the requirements; when PLURNK_PLAN=1 the plan directive joins the
-        // HARD requirements list (dynamically added/removed with the flag) rather than softly
-        // appearing in the optional # Plurnk System Tools sheet. §requirements-plan-gated
-        const planDirective = process.env.PLURNK_PLAN === "1" ? "YOU MUST begin every response with <<PLAN:...:PLAN\n" : "";
-        const requirementsText = `Syntax: <<OPsuffix[signal]?(target)?<Line/Result>?:body?:OPsuffix\n\n${planDirective}${baseRequirements}`;
+        // The op syntax leads the requirements. PLAN is mandated unconditionally by
+        // plurnk.md §Imperatives (grammar 0.70 requires every turn to lead with PLAN),
+        // so the service injects no separate plan directive here — the former PLURNK_PLAN
+        // gating is retired (PLURNK_PLAN is no longer a flag).
+        const requirementsText = `Syntax: <<OPsuffix[signal]?(target)?<Line/Result>?:body?:OPsuffix\n\n${baseRequirements}`;
         const log = await this.#buildLog(runId);
         const telemetryErrors = presetTelemetry ?? await this.#buildTelemetryErrors(loopId, currentTurnSeq);
         const countTokens = (t) => provider.countTokens(t); // §provider-surface-counttokens
@@ -889,8 +923,8 @@ class Engine {
         const budgetReadout = this.#renderBudget(PacketWire.measureLogBudget(log, countTokens), ceiling);
         // The default packet: an ordered list of sections, each addressable state
         // (§packet-construction). `slot` is the prompt-cache boundary; the STATIC
-        // sections (definition, tools, schemes) lead the system slot so they form the
-        // cached prefix, with the dynamic log after. In the user slot, requirements renders
+        // sections (definition, tools) lead the system slot so they form the cached
+        // prefix, with the dynamic log after. In the user slot, requirements renders
         // last (the contract closest to the assistant turn); budget/errors/git are
         // peer sections (unbundled). The budget section carries its {{tokensFree}}
         // placeholders here; they resolve below once the assembled total is known.
@@ -961,9 +995,7 @@ class Engine {
     // The # Plurnk System Tools capability sheet (SPEC §tools). A hook: each enabled
     // capability contributes one line, rendered above Requirements so the model sees what
     // it can do before the rules. Each available executor tag contributes its self-documenting
-    // example (plurnk-execs#7), retiring the blind EXEC. The plan directive is NOT a tool — it
-    // is a hard requirement gated by PLURNK_PLAN (§requirements-plan-gated), so it joins the
-    // rules list, not this optional sheet.
+    // example (plurnk-execs#7), retiring the blind EXEC.
     // The capability sheet — the live tool surface (wired executor tags). §tools-capability-sheet
     #collectTools() {
         const tools = [];
@@ -1269,13 +1301,13 @@ class Engine {
         const logEntryId = await this.#writeLog({ statement, result, runId, loopId, turnId, sequence, origin });
         onDispatch?.(logEntryId);
         // Proposal lifecycle (SPEC.md §engine-rails + §methods loop.resolve; §proposal-202-pauses). When a
-        // scheme returns status 202, the entry is written as state='proposed';
-        // dispatch then PAUSES on a per-entry waiter until resolution
-        // arrives via Engine.resolveProposal (from the loop/resolve RPC,
-        // YOLO listener, or timeout). The post-resolution status replaces
-        // 202 in the result the caller sees, so runTurn never branches on
-        // a pending state.
-        if (result.status === 202) {
+        // side-effecting op returns status 202 (a broadcast SEND[202] park is model
+        // speech, not a proposal — #isProposal, #255), the entry is written
+        // state='proposed'; dispatch then PAUSES on a per-entry waiter until
+        // resolution arrives via Engine.resolveProposal (from the loop/resolve RPC,
+        // YOLO listener, or timeout). The post-resolution status replaces 202 in the
+        // result the caller sees, so runTurn never branches on a pending state.
+        if (_a.#isProposal(statement, result)) {
             // Effect-gated auto-run (read/pure runtimes, plurnk-service#182):
             // no human gate, no loop/proposal notification. Accept + apply
             // in-process; the model sees the outcome directly, never a review.
@@ -1749,12 +1781,9 @@ class Engine {
         const delResult = await handler.deleteEntry(pathnameFromPath(path), ctx);
         return { status: delResult.status };
     }
-    // PLAN — the model's in-band reasoning op (plurnk-grammar 0.30.0, the 11th op).
-    // Production HOISTS PLAN bodies into the turn's reasoning field in #parseAssistant
-    // (#plan-reasoning) before dispatch runs, so PLAN normally never reaches here. This
-    // handler is the op's direct-dispatch semantics (exercised by the dispatch unit
-    // test): a pure no-op (PLAN ∉ MUTATING_OPS) whose body would serialize into the log
-    // row's tx, no runtime effect.
+    // PLAN — the model's reasoning op (the 11th op). An ordinary op: dispatched like any
+    // other, logged, and broadcast to the client as a log entry — but a pure no-op for
+    // state (PLAN ∉ MUTATING_OPS); its body serializes into the log row's tx, no effect.
     #handlePlan(statement) {
         if (statement.op !== "PLAN")
             throw new Error("unreachable");
@@ -1882,18 +1911,26 @@ class Engine {
             return path.scheme === "https" ? "http" : path.scheme;
         return "file"; // local (bare) → file
     }
+    // A status-202 result is a reviewable PROPOSAL (a side-effecting op — EDIT/EXEC/
+    // directed write — paused for client resolution) UNLESS it is a broadcast SEND.
+    // A broadcast SEND[202] is the model PARKING the loop (a terminal disposition,
+    // plurnk.md), never a side-effect — #255: gating the propose/await path on the
+    // bare 202 surfaced model speech as a loop/proposal and froze clients. The 202
+    // is overloaded (proposal-pause vs parked-terminal); the op disambiguates it.
+    static #isProposal(statement, result) {
+        return result.status === 202 && !(statement.op === "SEND" && statement.target === null);
+    }
     async #writeLog({ statement, result, runId, loopId, turnId, sequence, origin, }) {
         const target = this.#extractTarget(statement.target);
         const lineMarkerJson = "lineMarker" in statement && statement.lineMarker !== null
             ? JSON.stringify(statement.lineMarker)
             : null;
-        // Status 202 from a scheme means the action is proposed — written to
-        // the log in state='proposed' until the proposal lifecycle resolves
-        // it. attrs holds the scheme-supplied payload (file diff, exec
-        // command, etc.) that the client renders for review and the scheme
-        // consumes on accept. All other statuses are terminal — state =
-        // 'resolved' for the common case.
-        const isProposed = result.status === 202;
+        // A proposal (status 202 from a side-effecting op) is written to the log in
+        // state='proposed' until the proposal lifecycle resolves it; attrs holds the
+        // scheme-supplied payload (file diff, exec command, etc.) the client renders
+        // for review and the scheme consumes on accept. A broadcast SEND[202] is a
+        // parked-terminal, NOT a proposal (#isProposal / #255) → state='resolved'.
+        const isProposed = _a.#isProposal(statement, result);
         let attrsObj = (result.attrs !== undefined && result.attrs !== null)
             ? { ...result.attrs }
             : {};