@plurnk/plurnk-service 0.34.0 → 0.39.0

package/dist/core/Engine.js

@@ -6,6 +6,9 @@ import EntryManifest from "../schemes/_entry-manifest.js";
 import GitMembership from "./git-membership.js";
 import GitState from "./git-state.js";
 import Fork from "./fork.js";
+import RunCap from "./run-cap.js";
+import SessionSettings from "./session-settings.js";
+import { decodePathParens } from "./path-decode.js";
 import { DEFAULT_LOOP_FLAGS } from "./scheme-types.js";
 import { LineMarkerOps, MimetypeBinary, editedSpan } from "../content/index.js";
 import { readFile } from "node:fs/promises";
@@ -60,14 +63,12 @@ const readMaxCommands = () => {
 };
 // PLURNK_MANIFEST_ITEMS — the turn-0 manifest preview. null = off (no foist);
 // -1 = the full manifest; positive N = the first N items. 0 / unset = off.
+const normalizeManifestItems = (n) => (!Number.isFinite(n) || n === 0 ? null : n < 0 ? -1 : n);
 const readManifestItems = () => {
     const raw = process.env.PLURNK_MANIFEST_ITEMS;
     if (raw === undefined || raw.length === 0)
         return null;
-    const n = Number.parseInt(raw, 10);
-    if (!Number.isFinite(n) || n === 0)
-        return null;
-    return n < 0 ? -1 : n;
+    return normalizeManifestItems(Number.parseInt(raw, 10));
 };
 // Resolution timeout — proposed entries auto-cancel if nothing arrives
 // within this window. SPEC.md §engine-rails (proposal lifecycle) + §methods (loop.resolve).
@@ -82,9 +83,9 @@ const readProposalTimeoutMs = () => {
     return n;
 };
 const pathnameFromPath = (path) => {
-    if (path.kind === "url")
-        return path.pathname;
-    return path.raw;
+    if (path.kind === "regex")
+        return path.raw; // regex source — parens are syntax, never encoded
+    return decodePathParens(path.kind === "url" ? path.pathname : path.raw); // #239 item 4
 };
 // Default turn.status when ops were emitted but no SEND. Model is implicitly
 // continuing; loop.status stays 102 either way (only SEND broadcast advances
@@ -241,6 +242,7 @@ class Engine {
     #streamEventNotify;
     #wakeRunNotify;
     #injectRun;
+    #cancelRun;
     // Telemetry event fan-out: every TelemetryEvent pushed to the loop's
     // buffer is also broadcast live to the connected client(s) on the
     // session. Without this, the client sees `loop/terminated` with a
@@ -249,12 +251,13 @@ class Engine {
     #telemetryEventNotify;
     // Cached plurnk GBNF — read once on the first constrained generate (#189).
     #gbnfCache = null;
-    constructor({ db, schemes, mimetypes, streamEventNotify, wakeRunNotify, injectRun, telemetryEventNotify, tokenize }) {
+    constructor({ db, schemes, mimetypes, streamEventNotify, wakeRunNotify, injectRun, cancelRun, telemetryEventNotify, tokenize }) {
         this.#db = db;
         this.#schemes = schemes;
         this.#streamEventNotify = streamEventNotify;
         this.#wakeRunNotify = wakeRunNotify;
         this.#injectRun = injectRun;
+        this.#cancelRun = cancelRun;
         this.#telemetryEventNotify = telemetryEventNotify;
         // Default to empty discovery — standalone Engine construction (in
         // tests) gets no handlers, and content flows through the framework's
@@ -389,7 +392,7 @@ class Engine {
                 return { turnIds, finalStatus: row.status, hitMaxTurns: false, reason: "external" };
             }
             if (maxTurns >= 0 && turnIds.length >= maxTurns) {
-                await this.#db.engine_loop_cancel.run({ loop_id: loopId });
+                await this.#db.engine_loop_cancel.run({ loop_id: loopId, message: "max_turns" });
                 cleanup("forceful", "max_turns");
                 return { turnIds, finalStatus: 499, hitMaxTurns: true, reason: "max_turns" };
             }
@@ -410,7 +413,7 @@ class Engine {
             turnIds.push(turn.turnId);
             // SPEC §grinder: budget hard-stop — packet won't fit even collapsed → abandon.
             if (turn.budgetHardStop) {
-                await this.#db.engine_loop_cancel.run({ loop_id: loopId });
+                await this.#db.engine_loop_cancel.run({ loop_id: loopId, message: "budget_overflow" });
                 cleanup("forceful", "budget_overflow");
                 return { turnIds, finalStatus: 499, hitMaxTurns: false, reason: "budget_overflow" };
             }
@@ -451,7 +454,7 @@ class Engine {
             if (struck) {
                 state.streak++;
                 if (state.streak >= maxStrikes) {
-                    await this.#db.engine_loop_cancel.run({ loop_id: loopId });
+                    await this.#db.engine_loop_cancel.run({ loop_id: loopId, message: "strike_threshold" });
                     cleanup("forceful", "strike_threshold");
                     return { turnIds, finalStatus: 499, hitMaxTurns: false, reason: "strike_threshold" };
                 }
@@ -506,7 +509,10 @@ class Engine {
             // §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()) {
+            // #231 — env docs (PLURNK_MD_*) UNION the session's client docs; foist a READ of
+            // each materialized plurnk:///<alias>.md (loop_run materialized the same set).
+            const { mdDocs } = await SessionSettings.read(this.#db, sessionId);
+            for (const doc of await SessionSettings.resolveDocs(mdDocs)) {
                 const docTarget = {
                     kind: "url", raw: `plurnk:///${doc.entryName}`, scheme: "plurnk",
                     username: null, password: null, hostname: null, port: null,
@@ -550,8 +556,8 @@ class Engine {
             }
         }
         // 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,
+        // entry set, which changes each turn). A derived view (computed each
+        // turn), NOT an action — written directly (Engine.inject's path): no log entry,
         // no sequence slot, not dispatched. The catalog body is built in the
         // schemes layer (_entry-manifest); the engine only orchestrates the
         // per-turn write. Does not list itself.
@@ -584,7 +590,9 @@ class Engine {
         // manifest is JSON); off by default. AFTER the manifest write so the READ hits
         // it, not a 404; same plurnk-origin foist as the operator docs.
         if (seq === 1) {
-            const manifestItems = readManifestItems();
+            // #231 — a session's client-chosen manifestItems REPLACES the env default outright.
+            const { manifestItems: sessionMI } = await SessionSettings.read(this.#db, sessionId);
+            const manifestItems = sessionMI !== null ? normalizeManifestItems(sessionMI) : readManifestItems();
             if (manifestItems !== null) {
                 const manifestRead = {
                     op: "READ", suffix: "", signal: null, lineMarker: null,
@@ -710,7 +718,8 @@ class Engine {
         // entries (avoids bloating forensics with hundreds of identical refusals)
         // and the model gets a single telemetry signal next packet so it knows
         // its emission was truncated.
-        const maxCommands = readMaxCommands();
+        // #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);
         const droppedCount = opsCount - opsToDispatch.length;
         const statuses = [];
@@ -905,10 +914,12 @@ class Engine {
                 for (const t of sections.log.byTurn)
                     lines.push(`| ${t.turn} | ${t.tokens} |`);
             }
-            // The heaviest individual entries — the FOLD targets behind the
-            // weight (§tokenomics {§tokenomics-largest-entries}).
+            // The heaviest individual log items — the FOLD targets behind the weight
+            // (§tokenomics {§tokenomics-largest-entries}). "items", not "entries": the readout
+            // lists log:/// rows (log items), distinct from catalog entries (plurnk.md: "EDIT
+            // is only for entries. Do not attempt to edit log items.").
             if (sections.log.largest.length > 0) {
-                lines.push("Heaviest entries:", "| entry | tokens |", "|---|--:|");
+                lines.push("Heaviest items:", "| item | tokens |", "|---|--:|");
                 for (const e of sections.log.largest)
                     lines.push(`| ${e.path} | ${e.tokens} |`);
             }
@@ -935,13 +946,31 @@ class Engine {
         // 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}`);
+                const entry = this.#executors.entry(tag);
+                if (entry?.example)
+                    tools.push(`* ${entry.example}`);
+                // #note12 — link the executor's fuller doc (materialized at plurnk:///docs/<tag>);
+                // its token cost rides that manifest entry, so no inline recount here.
+                if (entry?.documentation)
+                    tools.push(`* docs for ${tag}: plurnk:///docs/${tag}`);
             }
         }
         return tools;
     }
+    // #note12 — the daughter-provided reference docs (schemes' + execs' `documentation`),
+    // materialized at plurnk:///docs/<name> by loop_run (like operator docs) so the
+    // catalogue's doc-links READ and the manifest carries each doc's token cost.
+    docEntries() {
+        const out = this.#schemes.docs();
+        if (this.#executors !== undefined) {
+            for (const tag of this.#executors.availableRuntimes()) {
+                const doc = this.#executors.entry(tag)?.documentation;
+                if (doc !== undefined && doc.length > 0)
+                    out.push({ name: tag, content: doc });
+            }
+        }
+        return out;
+    }
     // SPEC §grinder — the budget grinder. Runs pre-LLM (in runTurn, after the packet
     // is built, before provider.generate); fires only on actual overflow. Two
     // passes, re-measuring between. Folds (never deletes) — the prior turn's logs,
@@ -1008,7 +1037,7 @@ class Engine {
     }
     // Render-time mimetype invocation (SPEC §mimetype {§mimetype-handlers-fire-render-time},
     // §per-entry-channels {§per-entry-channels-preview-is-handler-output}). For each (run, entry, channel)
-    // with indexed=1, pass the channel's current content through
+    // with expanded=1, pass the channel's current content through
     // mimetype.preview(content, budget). State is included verbatim — engine
     // does NOT branch on it (§channel-state {§channel-state-engine-does-not-branch-on-state}).
     // SPEC §telemetry: model-facing alert surface.
@@ -1069,7 +1098,7 @@ class Engine {
             mimetype_rx: r.mimetype_rx,
             tx: r.mimetype_tx === "application/json" ? JSON.parse(r.tx) : r.tx,
             mimetype_tx: r.mimetype_tx,
-            folded: r.indexed === 0,
+            folded: r.expanded === 0,
             source: r.source,
         }));
     }
@@ -1096,6 +1125,19 @@ class Engine {
             });
             written++;
         }
+        // §run-scheme — loop-terminations: a sibling's loop reaching terminal surfaces the
+        // same way an entry-change does, carrying its deliverable (the SEND body) or the
+        // abandonment reason. Folded, attributed to the terminated run.
+        const terms = await this.#db.engine_pull_loop_terminations.all({ session_id: sessionId, run_id: runId, since });
+        for (const t of terms) {
+            await this.#db.engine_insert_loop_termination_delta.run({
+                run_id: runId, loop_id: loopId, turn_id: turnId, sequence: fromSequence + written,
+                source: String(t.run_id), pathname: `/${t.run_name}`,
+                rx: t.terminal_message ?? `loop "${t.prompt}" ended (${t.status})`,
+                status: t.status,
+            });
+            written++;
+        }
         return written;
     }
     // §env-delta — the filesystem as an actor. Ambient disk divergences detected at
@@ -1223,6 +1265,9 @@ class Engine {
             // resolve synchronously inside their handlers.
             const target = this.#extractTarget(statement.target);
             const flags = await this.#loadLoopFlags(loopId); // the loop/proposal notification carries flags (yolo) — §dual-yolo-proposal-carries-flags
+            // #note10 — if the target diverged on disk this turn, the model's EDIT is based
+            // on a stale read; flag it so a YOLO auto-accept rejects instead of clobbering.
+            const diverged = await this.#db.engine_target_diverged_this_turn.get({ run_id: runId, turn_id: turnId, scheme: target.scheme, pathname: target.pathname });
             const event = {
                 logEntryId, sessionId, runId, loopId, turnId,
                 op: statement.op,
@@ -1230,6 +1275,7 @@ class Engine {
                 body: typeof result.body === "string" ? result.body : "",
                 attrs: (result.attrs ?? {}),
                 flags,
+                staleClobberRisk: diverged !== undefined,
             };
             for (const listener of this.#proposalPendingListeners) {
                 try {
@@ -1567,6 +1613,9 @@ class Engine {
         }
         if (ctx.injectRun === undefined)
             throw new Error("run fork: injectRun capability absent");
+        const denied = await RunCap.deny(this.#db, ctx.sessionId);
+        if (denied !== null)
+            return denied;
         const branchRunId = await Fork.fork(this.#db, srcRunId);
         const branch = await this.#db.fork_get_run.get({ id: branchRunId });
         await ctx.injectRun({ sessionId: ctx.sessionId, runId: branchRunId, prompt: typeof statement.body === "string" ? statement.body : "" });
@@ -1648,6 +1697,23 @@ class Engine {
                 return { status: 501 };
             return await execHandler.kill(pathnameFromPath(path), ctx);
         }
+        if (schemeName === "run") {
+            // terminate — abort any run by address; whoever holds it may end it.
+            // `.`/"" = self. cancelRun (→ Daemon.cancelDrain) aborts the run's signal
+            // (its loop closes 499); an idle run is a no-op-200, a missing run 404.
+            const name = pathnameFromPath(path).replace(/^\/+/, "");
+            let runId = ctx.runId;
+            if (name !== "" && name !== ".") {
+                const row = await this.#db.run_resolve_by_name.get({ session_id: ctx.sessionId, name });
+                if (row === undefined)
+                    return { status: 404, error: `run:///${name} not found in this session` };
+                runId = row.id;
+            }
+            if (this.#cancelRun === undefined)
+                throw new Error("run kill: cancelRun capability absent");
+            this.#cancelRun(runId);
+            return { status: 200 };
+        }
         const handler = this.#schemes.get(schemeName);
         if (handler === undefined || typeof handler.deleteEntry !== "function")
             return { status: 501 };
@@ -1750,7 +1816,10 @@ class Engine {
         if (status === null)
             return { status: 400 };
         if (status === 200 || status === 499) {
-            await this.#db.engine_loop_set_status.run({ status, loop_id: loopId });
+            // the loop's terminal message — its deliverable — rides the termination delta.
+            const body = statement.body;
+            const message = body === null ? null : typeof body === "string" ? body : body.raw;
+            await this.#db.engine_loop_set_status.run({ status, loop_id: loopId, message });
         }
         return { status };
     }
@@ -1872,12 +1941,14 @@ class Engine {
         if (path === null)
             return { scheme: null, username: null, password: null, hostname: null, port: null, pathname: null, params: null, fragment: null };
         // `local` (bare path) and `regex` (grammar 0.46 `#pattern#flags` target) carry no URL parts — store the raw text as the pathname for the log record, scheme=null.
-        if (path.kind === "local" || path.kind === "regex")
-            return { scheme: null, username: null, password: null, hostname: null, port: null, pathname: path.raw, params: null, fragment: null };
+        if (path.kind === "regex")
+            return { scheme: null, username: null, password: null, hostname: null, port: null, pathname: path.raw, params: null, fragment: null }; // regex source — no decode
+        if (path.kind === "local")
+            return { scheme: null, username: null, password: null, hostname: null, port: null, pathname: decodePathParens(path.raw), params: null, fragment: null }; // #239 item 4
         const scheme = path.scheme === "file" ? null : path.scheme;
         return {
             scheme, username: path.username, password: path.password,
-            hostname: path.hostname, port: path.port, pathname: path.pathname,
+            hostname: path.hostname, port: path.port, pathname: decodePathParens(path.pathname), // #239 item 4
             params: JSON.stringify(path.params), fragment: path.fragment,
         };
     }