@plurnk/plurnk-service 0.26.0 → 0.27.0

package/dist/core/Engine.js

@@ -1,5 +1,5 @@
 var _a;
-import { PlurnkParser, PlurnkParseError } from "@plurnk/plurnk-grammar";
+import { PlurnkParser, PlurnkParseError, parsePath } from "@plurnk/plurnk-grammar";
 import { Mimetypes, emptyRegistry } from "@plurnk/plurnk-mimetypes";
 import EntryCrud from "../schemes/_entry-crud.js";
 import EntryManifest from "../schemes/_entry-manifest.js";
@@ -8,6 +8,8 @@ import GitState from "./git-state.js";
 import { DEFAULT_LOOP_FLAGS } from "./scheme-types.js";
 import { LineMarkerOps, MimetypeBinary, editedSpan } from "../content/index.js";
 import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { setTimeout as delay } from "node:timers/promises";
 import Paths from "../Paths.js";
 import SchemeCtxImpl from "./caps/SchemeCtxImpl.js";
 // Shared module imported by both Engine and bin/digest.ts, so wire
@@ -275,9 +277,20 @@ class Engine {
     // attaches it iff the backend supports it and silently drops it otherwise —
     // capability is providers' concern, not ours. Pure plumbing grammar→provider.
     async #grammarConstraint() {
-        if (process.env.PLURNK_PROVIDERS_GBNF !== "1")
+        // PLURNK_PROVIDERS_GBNF SELECTS the GBNF variant to constrain sampling to (#225):
+        // a bare name (`plurnk-strict.gbnf` | `plurnk.gbnf`) is a variant shipped by
+        // @plurnk/plurnk-grammar; an absolute/relative path is a BYO grammar. Empty or "0"
+        // disables — unconstrained generation. (Was a `=== "1"` boolean; the value change
+        // would otherwise read as "off", leaving every turn unconstrained.)
+        const variant = process.env.PLURNK_PROVIDERS_GBNF;
+        if (variant === undefined || variant === "" || variant === "0")
             return undefined;
-        this.#gbnfCache ??= await readFile(Paths.grammarGbnf, "utf8");
+        if (this.#gbnfCache === null) {
+            const path = variant.startsWith("/") || variant.startsWith(".")
+                ? variant
+                : fileURLToPath(import.meta.resolve(`@plurnk/plurnk-grammar/${variant}`));
+            this.#gbnfCache = await readFile(path, "utf8");
+        }
         return this.#gbnfCache;
     }
     // Per-loop usage totals (#197): SUM the loop's turns (usage is stored per
@@ -376,6 +389,16 @@ class Engine {
                 cleanup("forceful", "max_turns");
                 return { turnIds, finalStatus: 499, hitMaxTurns: true, reason: "max_turns" };
             }
+            // PLURNK_EXEC_WAIT_MS — a post-EXEC breath: if a spawn from the prior turn
+            // is still in flight, give it a tunable beat to land in THIS turn's packet
+            // before we assemble it. A fixed grace beat, never a wait-for-completion;
+            // 0/unset = off. Abortable with the loop signal.
+            const execWaitMs = Number(process.env.PLURNK_EXEC_WAIT_MS ?? "0");
+            if (execWaitMs > 0) {
+                const execHandler = this.#schemes.get("exec");
+                if (execHandler?.hasActiveSpawns?.(runId) === true)
+                    await delay(execWaitMs, undefined, { signal });
+            }
             const turn = await this.runTurn({
                 provider, messages, persona, requirements, sessionId, runId, loopId, origin, signal, onDispatch,
                 turnNumber: turnIds.length + 1, maxTurns,
@@ -462,7 +485,7 @@ class Engine {
             throw new Error("Engine.runTurn: turn open returned no row");
         const turnId = openRow.id;
         // Pre-model writes. Each turn opens with a system-origin EDIT
-        // against `plurnk://prompt/<loop_id>/<seq>` IF there's a prompt
+        // against `plurnk:///prompt/<loop_id>/<seq>` IF there's a prompt
         // for THIS turn the model hasn't seen yet:
         //   - Turn 1: loop.prompt is the initial user prompt.
         //   - Turn N>1: only if Engine.inject (or wake-on-completion via
@@ -475,15 +498,15 @@ class Engine {
         let nextActionIndex = 1;
         if (seq === 1) {
             // Operator doc READs (PLURNK_MD_<ALIAS>). The docs were materialized
-            // as plurnk://<entry> entries by the plurnk run (loop_run, via the
+            // as plurnk:///<entry> entries by the plurnk run (loop_run, via the
             // §actor-boundary keystone); foist a READ of each into THIS turn-0 so the model
             // reads them inline. It sees only the READ — the materializing EDIT
             // lives in the plurnk run's log, never the model's.
             for (const doc of Paths.docs()) {
                 const docTarget = {
-                    kind: "url", raw: `plurnk://${doc.entryName}`, scheme: "plurnk",
+                    kind: "url", raw: `plurnk:///${doc.entryName}`, scheme: "plurnk",
                     username: null, password: null, hostname: null, port: null,
-                    pathname: doc.entryName, params: {}, fragment: null,
+                    pathname: `/${doc.entryName}`, params: {}, fragment: null,
                 };
                 const docRead = {
                     op: "READ", suffix: "", signal: null, target: docTarget,
@@ -498,10 +521,10 @@ class Engine {
             const promptRow = await this.#db.engine_get_loop_prompt.get({ loop_id: loopId });
             if (promptRow !== undefined && typeof promptRow.prompt === "string" && promptRow.prompt.length > 0) {
                 const promptPath = {
-                    kind: "url", raw: `plurnk://prompt/${loopId}/${seq}`,
+                    kind: "url", raw: `plurnk:///prompt/${loopId}/${seq}`,
                     scheme: "plurnk", username: null, password: null,
                     hostname: null, port: null,
-                    pathname: `prompt/${loopId}/${seq}`, params: {}, fragment: null,
+                    pathname: `/prompt/${loopId}/${seq}`, params: {}, fragment: null,
                 };
                 const promptStmt = {
                     op: "EDIT", suffix: "", signal: null,
@@ -515,7 +538,7 @@ class Engine {
                 nextActionIndex++;
             }
         }
-        // plurnk://manifest.json — rewritten EVERY turn (a live view of the
+        // plurnk:///manifest.json — rewritten EVERY turn (a live view of the
         // entry set, which changes each turn). A derived view like the index,
         // NOT an action — written directly (Engine.inject's path): no log entry,
         // no sequence slot, not dispatched. The catalog body is built in the
@@ -540,7 +563,7 @@ class Engine {
         // this turn's packet reflects them.
         const fsDivergences = await GitMembership.indexGitMembership(systemCtx);
         await this.#logFsFictions(sessionId, fsDivergences);
-        await EntryCrud.writeEntry("manifest.json", {
+        await EntryCrud.writeEntry("/manifest.json", {
             channels: { body: { content: await EntryManifest.buildManifestBody(systemCtx), mimetype: "application/json" } },
             tags: [],
         }, systemCtx, "plurnk");
@@ -555,9 +578,9 @@ class Engine {
                 const manifestRead = {
                     op: "READ", suffix: "", signal: null, lineMarker: null,
                     target: {
-                        kind: "url", raw: "plurnk://manifest.json", scheme: "plurnk",
+                        kind: "url", raw: "plurnk:///manifest.json", scheme: "plurnk",
                         username: null, password: null, hostname: null, port: null,
-                        pathname: "manifest.json", params: {}, fragment: null,
+                        pathname: "/manifest.json", params: {}, fragment: null,
                     },
                     body: manifestItems < 0 ? null : { dialect: "jsonpath", raw: `$[0:${manifestItems}]` },
                     position: { line: 1, column: 1 },
@@ -641,13 +664,17 @@ class Engine {
             });
         }
         const opsCount = packetAssistant.ops.length;
-        const sendOp = packetAssistant.ops.findLast((op) => op.op === "SEND" && typeof op.signal === "number");
+        // 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
+        // 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 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
         // turns may pass without one. An empty op list is the only strike.
         const turnStatus = sendOp !== undefined
             ? sendOp.signal
-            : opsCount === 0 ? TURN_STATUS_NO_OPS : TURN_STATUS_IMPLICIT_CONTINUE;
+            : realOpsCount === 0 ? TURN_STATUS_NO_OPS : TURN_STATUS_IMPLICIT_CONTINUE;
         // Close the turn with the final packet, status, and usage stats.
         const packet = this.#completePacket(requestPacket, packetAssistant, response.assistantRaw, provider);
         const { usage, finishReason, model } = callMetadata;
@@ -717,24 +744,45 @@ class Engine {
         const { assistant } = response;
         const preParsedOps = assistant.ops;
         const ops = [];
-        const textFragments = [];
+        // #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;
+        };
         // 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) {
-            ops.push(...preParsedOps);
+            for (const op of preParsedOps)
+                if (!hoistPlan(op))
+                    ops.push(op);
         }
         else {
             const parsed = PlurnkParser.parse(assistant.content);
             for (const item of parsed.items) {
-                if (item.kind === "statement")
-                    ops.push(item.statement);
+                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)
-                        textFragments.push(trimmed);
+                        ops.push({
+                            op: "SEND", suffix: "", signal: 103, target: null,
+                            lineMarker: null, body: { raw: trimmed, json: null },
+                            position: item.position ?? { line: 1, column: 1 },
+                        });
                 }
                 else if (item.kind === "error") {
                     const err = item.error;
@@ -759,8 +807,8 @@ class Engine {
             }
         }
         const wireReasoning = assistant.reasoning ?? "";
-        const scrapedReasoning = textFragments.join("\n");
-        const reasoningParts = [wireReasoning, scrapedReasoning].filter((s) => s.length > 0);
+        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;
         return {
             packetAssistant: { content: assistant.content, ops, reasoning },
@@ -776,7 +824,7 @@ class Engine {
         const byRole = (role) => initialMessages.filter((m) => m.role === role).map((m) => m.content).join("\n\n");
         const system_definition = byRole("system");
         // user.prompt sources from the loop's most recent prompt entry first
-        // (plurnk://prompt/<loop_id>/<N> for the highest N written to date).
+        // (plurnk:///prompt/<loop_id>/<N> for the highest N written to date).
         // This is what inject + the turn-1 foist write into. Falls back to
         // the runLoop caller's messages.user for tests that bypass the
         // foist mechanism entirely.
@@ -861,12 +909,26 @@ 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. PLAN is the first
-    // contributor (gated by PLURNK_PLAN); wired executor tags inject their own
-    // lines here later (the ExecutorRegistry surface), retiring the blind EXEC.
+    // contributor (gated by PLURNK_PLAN); each available executor tag then
+    // contributes its self-documenting example (plurnk-execs#7), retiring the
+    // blind EXEC.
     #collectTools() {
         const tools = [];
         if (process.env.PLURNK_PLAN === "1") {
-            tools.push("- `<<PLAN:...:PLAN` — think or plan in-band before acting; the body is your reasoning, not an op.");
+            tools.push("* Begin every response with <<PLAN:{planning and reasoning}:PLAN");
+        }
+        // Each available runtime tag contributes its self-documenting example —
+        // the example carries syntax + purpose, so there's no prose line. Tags
+        // with no example (sh/node, covered by the core prompt) contribute
+        // nothing; available-only, so the model never sees an unusable tag. `* `
+        // bullets + bare op forms match the packet's list/op rendering (no `- `,
+        // no backticks — see packet-wire.ts).
+        if (this.#executors !== undefined) {
+            for (const tag of this.#executors.availableRuntimes()) {
+                const example = this.#executors.entry(tag)?.example;
+                if (example)
+                    tools.push(`* ${example}`);
+            }
         }
         return tools;
     }
@@ -965,7 +1027,7 @@ class Engine {
     // SPEC §packet packet.system.log — chronological action-entries for the loop.
     // Snapshot is taken at packet build (pre-dispatch this turn), so it
     // reflects "what has happened before this turn." Each row carries a
-    // log://<loop_seq>/<turn_seq>/<sequence> coordinate the model can READ.
+    // log:///<loop_seq>/<turn_seq>/<sequence> coordinate the model can READ.
     async #buildLog(runId) {
         // SPEC §packet-terms: runs own log entries — log is the run's history,
         // not the loop's. Span all loops in the run so the model sees
@@ -1272,7 +1334,7 @@ class Engine {
         return (row?.n ?? 0) > 0;
     }
     // Inject a prompt into the run's currently-executing loop. Writes a
-    // plurnk://prompt/<loop_id>/<next-turn> entry whose body becomes
+    // plurnk:///prompt/<loop_id>/<next-turn> entry whose body becomes
     // packet.user.prompt at the next turn boundary. Last-wins: if two
     // injects target the same next-turn slot, the second overwrites the
     // first.
@@ -1401,7 +1463,8 @@ class Engine {
             return this.#denyIfDisallowed("exec", origin);
         }
         if (statement.op === "COPY" || statement.op === "MOVE") {
-            const dstScheme = this.#schemeNameOf(statement.body);
+            const dst = statement.op === "COPY" ? (statement.body === null ? null : parsePath(statement.body)) : statement.body;
+            const dstScheme = this.#schemeNameOf(dst);
             const dstDenial = this.#denyIfDisallowed(dstScheme, origin);
             if (dstDenial !== null)
                 return dstDenial;
@@ -1454,7 +1517,7 @@ class Engine {
             return { status: 403, error: `scheme '${scheme}' is inactive under current loop flags` };
         };
         if (statement.op === "COPY" || statement.op === "MOVE") {
-            return check(statement.target) ?? check(statement.body);
+            return check(statement.target) ?? check(statement.op === "COPY" ? (statement.body === null ? null : parsePath(statement.body)) : statement.body);
         }
         return check(statement.target);
     }
@@ -1462,11 +1525,14 @@ class Engine {
         if (statement.op !== "COPY")
             throw new Error("unreachable");
         const srcPath = statement.target;
-        const dstPath = statement.body;
+        // COPY's body is an opaque raw string (grammar §COPY: a dest path OR a run-fork
+        // prompt); parse it to the dest path. Non-path bodies (run:// fork prompts) are
+        // not yet handled and surface as a 400.
+        const dstPath = statement.body === null ? null : parsePath(statement.body);
         if (srcPath === null)
             return { status: 400, error: "COPY requires source path" };
         if (dstPath === null)
-            return { status: 400, error: "COPY requires destination path (in body slot)" };
+            return { status: 400, error: "COPY destination must be a parseable path in the body slot" };
         return await this.#copyOrchestration({ statement, srcPath, dstPath, ctx });
     }
     async #handleMove(statement, ctx) {
@@ -1505,12 +1571,12 @@ class Engine {
     }
     // KILL — scheme-polymorphic destroy (plurnk-grammar#203 / 0.28.0). Entry-KILL
     // permanently deletes the entry: the canonical delete now, MOVE→/dev/null
-    // retired from the model's vocabulary. Process-KILL (exec://) aborts the
+    // retired from the model's vocabulary. Process-KILL (exec:///) aborts the
     // running spawn's controller (the same teardown loop.cancel rides), addressed
     // by coordinate pathname (#203). The KILL body is an opaque
     // annotation with no runtime meaning; it survives into the log row's tx for
     // free via the statement serialization. Status: 200 killed · 404 unknown ·
-    // 405 log:// (append-only) · 403 writableBy (the #checkWritable gate, KILL ∈
+    // 405 log:/// (append-only) · 403 writableBy (the #checkWritable gate, KILL ∈
     // MUTATING_OPS) · 200/410/304/404 exec (killed / killed-earlier / exited / unknown) · 501 no-kill/delete scheme.
     async #handleKill(statement, ctx) {
         if (statement.op !== "KILL")
@@ -1522,7 +1588,7 @@ class Engine {
         if (schemeName === null)
             return { status: 400, error: "KILL target must be a URL path with a scheme" };
         if (schemeName === "log")
-            return { status: 405, error: "log:// is append-only; KILL must bounce" };
+            return { status: 405, error: "log:/// is append-only; KILL must bounce" };
         if (schemeName === "exec") {
             const execHandler = this.#schemes.get("exec");
             if (execHandler === undefined || typeof execHandler.kill !== "function")
@@ -1535,14 +1601,12 @@ class Engine {
         const delResult = await handler.deleteEntry(pathnameFromPath(path), ctx);
         return { status: delResult.status };
     }
-    // PLAN — undocumented reasoning op (plurnk-grammar 0.30.0, the 11th op). A pure
-    // no-op: the body is the model's in-content reasoning, which lands in the log
-    // row's tx for free via statement serialization, no runtime effect (PLAN ∉
-    // MUTATING_OPS). NOT taught in plurnk.md by design — reserved for a future model
-    // that must reason in the content field (no separate reasoning channel). gemma
-    // reasons on its own channel via the relaxed root, is never shown PLAN, and never
-    // emits it; this handler exists only so the op resolves cleanly if we ever
-    // deliberately reach for it (which would also require a plurnk.md override).
+    // 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.
     #handlePlan(statement) {
         if (statement.op !== "PLAN")
             throw new Error("unreachable");
@@ -1657,7 +1721,7 @@ class Engine {
     }
     // Bare paths default to the file scheme per plurnk.md (grammar sysprompt):
     // "Bare paths (no scheme) default to local relative project file paths."
-    // file:// remains an optional explicit form for absolute paths.
+    // file:/// remains an optional explicit form for absolute paths.
     #schemeNameOf(path) {
         if (path === null)
             return null;
@@ -1682,11 +1746,11 @@ class Engine {
             ? { ...result.attrs }
             : {};
         // EXEC pathname is executor-domain + coordinate: the stream entry
-        // lives at exec://<runtime>/<loop_seq>/<turn_seq>/<sequence> (e.g.
-        // exec://sh/1/1/2). The runtime leads — domain-aware, the executor
+        // lives at exec:///<runtime>/<loop_seq>/<turn_seq>/<sequence> (e.g.
+        // exec:///sh/1/1/2). The runtime leads — domain-aware, the executor
         // as authority — and the coordinate that follows is already unique
         // per statement, so no slug is injected. The log row's target points
-        // at this same address; its log:// coordinate shares the trailing
+        // at this same address; its log:/// coordinate shares the trailing
         // <loop>/<turn>/<seq>, so the model correlates op to stream output.
         // Runtime comes from statement.signal (EXEC's runtime slot) so it's
         // resolvable for failed execs too; empty/absent = the default shell.
@@ -1697,7 +1761,7 @@ class Engine {
             if (seqs === undefined)
                 throw new Error(`Engine.#writeLog: loop_turn_seqs returned no row for loop=${loopId} turn=${turnId}`);
             const runtime = (typeof statement.signal === "string" && statement.signal.length > 0) ? statement.signal : "sh";
-            const coordPathname = `${runtime}/${seqs.loop_seq}/${seqs.turn_seq}/${sequence}`;
+            const coordPathname = `/${runtime}/${seqs.loop_seq}/${seqs.turn_seq}/${sequence}`;
             target.scheme = "exec";
             target.pathname = coordPathname;
             attrsObj.pathname = coordPathname;
@@ -1748,7 +1812,7 @@ class Engine {
     }
     // Normalize a parsed path for storage. The `file` scheme is a routing
     // internal — never stored, never rendered to the model. Both bare paths
-    // and `file://...` inputs collapse to scheme=null at this boundary, so
+    // and `file:///...` inputs collapse to scheme=null at this boundary, so
     // entries.scheme / log_entries.scheme never carry the string "file".
     #extractTarget(path) {
         if (path === null)