@plurnk/plurnk-service 3.0.0 → 3.1.0

package/dist/core/TurnRunner.js

@@ -1,7 +1,7 @@
 var _a;
 import NativeContent from "./NativeContent.js";
-import { PlurnkParser } from "@plurnk/plurnk-parser";
-import { PathSyntax, PlurnkParseError, TurnDisposition, UNKNOWN_POSITION } from "@plurnk/plurnk-contracts";
+import { PlurnkParser, parsePath } from "@plurnk/plurnk-parser";
+import { PathSyntax, PlurnkParseError, UNKNOWN_POSITION } from "@plurnk/plurnk-contracts";
 import WorkerOwners from "./WorkerOwners.js";
 import { setTimeout as delay } from "node:timers/promises";
 import { aggregateProviderAccounting } from "@plurnk/plurnk-providers";
@@ -12,20 +12,16 @@ import GitMembership from "./git-membership.js";
 import { acceptedKinds } from "./attachments.js";
 import GitState from "./git-state.js";
 import WorkspaceSettings from "./workspace-settings.js";
-import { contentWeight } from "./content-weight.js";
 import { generatedPathname } from "./plurnk-uri.js";
+import { contentWeight } from "./content-weight.js";
 import { readFile } from "node:fs/promises";
 import { resolve as resolvePath } from "node:path";
 import { homedir } from "node:os";
-// {§operator-grammar} — an operator's own GBNF is a file path: absolute, `~`-relative, or
-// relative to the daemon's working directory. The service ships no grammar profile, so a bare
-// name (no separator) is refused by name rather than resolved against anything.
+// {§operator-grammar}
 export const resolveOperatorGrammarPath = (value) => {
     if (value === "~" || value.startsWith("~/"))
         return resolvePath(homedir(), value.slice(2));
-    if (value.startsWith("/") || value.startsWith(".") || value.includes("/"))
-        return resolvePath(value);
-    throw new Error(`PLURNK_PROVIDERS_GBNF=${value} names a bundled grammar profile; the service ships none (#588). Give the path of a grammar file you wrote.`);
+    return resolvePath(value);
 };
 // Shared module imported by both Engine and the digest, so wire
 // projection and digest projection are structurally one function — no
@@ -101,6 +97,24 @@ const windowOverflowFailure = (overflow) => Results.failure("engine:context", "w
 // {§context-over-budget-row} — the row is the mandate; the gauge is the one home for the numbers
 // ({§context-gauge}), which the row's own charge would otherwise put out of agreement.
 const OVER_BUDGET_DETAIL = "Context exceeds budget. YOU MUST ONLY KILL, MOVE or NOTE this turn.";
+// {§worker-initialization-entry} — the one NOTE that leads the initialization surveys.
+const INITIALIZATION_NOTE = {
+    op: "NOTE", aside: null, metadata: null, target: null, lineMarker: null,
+    body: "Surveyed tooling, documentation, extended context, and project root.", position: UNKNOWN_POSITION,
+};
+// {§continued-without-note} — said once, in the next packet, of a continuing turn that carried no NOTE.
+const CONTINUED_WITHOUT_NOTE = "The turn continued without a NOTE.";
+// Trial (#1073): a continuing turn that carried NOTEs and no other operation is told so under the same
+// per-turn rule; it is a notice, never a strike.
+const NOTED_WITHOUT_OPERATION = "The turn carried NOTEs and no other operation.";
+// {§notice-directive} — what each notice of the model's own output asks of it: MUST where the card says MUST
+// or the output was refused, SHOULD where a near-miss was accepted.
+const DIRECTIVE = Object.freeze({
+    note: "YOU MUST emit at least one NOTE operation with a complete status summary and at least one other operation per turn.",
+    emission: "YOU MUST ONLY emit fenced operations; with the parameters, pattern, and terse aside on the fenced Operation line.",
+    advisory: "YOU SHOULD write the canonical form.",
+    output: "YOU SHOULD emit fewer or shorter operations per turn.",
+});
 const overBudgetFailure = () => Results.failure("engine:context", "packet-exceeds-budget", 413, OVER_BUDGET_DETAIL);
 const INVALID_EMISSION_RECOVERY_MESSAGE = "Response rejected before dispatch; no operations were performed.";
 // {§output-allowance-notice} — THE single derivation of a ceiling cut: a
@@ -109,7 +123,7 @@ const INVALID_EMISSION_RECOVERY_MESSAGE = "Response rejected before dispatch; no
 // path. Null means the emission was not cut by the allowance.
 const allowanceCutMessage = (finishReason, grant) => finishReason !== "length"
     ? null
-    : `emission truncated at the output allowance${grant === null ? "" : ` (${grant} tokens)`}`;
+    : `Emission truncated at the output allowance${grant === null ? "" : ` (${grant} tokens)`}`;
 const readEmissionAttempts = () => Knob.integer("PLURNK_SERVICE_EMISSION_ATTEMPTS", 1);
 // The wall's abort reason — runLoop branches a mid-turn teardown to the 504 terminal on it.
 export const LOOP_TIMEOUT_REASON = "loop_timeout";
@@ -488,9 +502,14 @@ class TurnRunner {
             await Turn.complete(this.#db, initializationTurn.id, 200);
             return;
         }
-        const program = TurnOps.renderInternal(admittedInitializationStatements);
+        // {§worker-initialization-entry} — the example turn keeps the NOTE contract the card teaches:
+        // when the surveys run, one NOTE leads them.
+        const programStatements = admittedInitializationStatements.some((statement) => statement.op === "FIND")
+            ? [INITIALIZATION_NOTE, ...admittedInitializationStatements]
+            : admittedInitializationStatements;
+        const program = TurnOps.renderInternal(programStatements);
         const admitted = PlurnkParser.parseStatements(program).items.flatMap((item) => item.kind === "statement" ? [item.statement] : []);
-        if (admitted.length !== admittedInitializationStatements.length) {
+        if (admitted.length !== programStatements.length) {
             throw new Error("initialization program did not preserve every authored operation");
         }
         await Turn.recordSource(this.#db, initializationTurn.id, "ops", program);
@@ -505,7 +524,7 @@ class TurnRunner {
             turnId: initializationTurn.id,
             fromSequence: 1,
             failOnOperationError: true,
-            fit: this.#fitFor(args, { turnId: initializationTurn.id, seq: initializationTurn.sequence, gitStatus, notices: [], transientOpenLogEntryId: container.transientOpenLogEntryId, projection: { bodiless: new Set(), omitPreviousEmission: false } }),
+            fit: this.#fitFor(args, { turnId: initializationTurn.id, seq: initializationTurn.sequence, gitStatus, notices: [], transientOpenLogEntryId: container.transientOpenLogEntryId, projection: { bodiless: new Set(), omitEmissionHistory: false } }),
             signal: this.#loopSignal(loopId),
             onDispatch,
             onSettled,
@@ -517,11 +536,18 @@ class TurnRunner {
     // {§actor-boundary-catalog-preview} — the opening surveys, each admitted only when
     // its scheme is registered for the workspace. A positive filesItems caps the
     // project rows.
-    async #catalogSurveys({ workspaceId }, { workerName, initializationPolicies }, filesItems) {
+    async #catalogSurveys({ workspaceId }, { workerName, initializationPolicies, loopSequence }, filesItems) {
         const catalogSchemes = await this.#db.engine_scheme_catalog_summary.all({ workspace_id: workspaceId });
         const fileItems = catalogSchemes.find(({ scheme }) => scheme === "file")?.shallow_items ?? 0;
         const fileCap = filesItems > 0 && fileItems > 0 ? Math.min(filesItems, fileItems) : null;
         const surveys = [
+            {
+                // Trial (#1073): the survey reads its own program, so the log carries one program verbatim
+                // and shows that every ops:// turn is readable.
+                op: "READ", aside: "this program",
+                target: { kind: "url", raw: `ops://${workerName}/${loopSequence}/1`, scheme: "ops", username: null, password: null, hostname: workerName, port: null, pathname: `/${loopSequence}/1`, query: null, fragment: null },
+                metadata: null, lineMarker: null, matcher: null, body: null, position: UNKNOWN_POSITION,
+            },
             {
                 op: "FIND", aside: null,
                 target: { kind: "url", raw: "skill://*/SKILL.md", scheme: "skill", username: null, password: null, hostname: "*", port: null, pathname: "/SKILL.md", query: null, fragment: null },
@@ -631,7 +657,7 @@ class TurnRunner {
         const systemCtx = this.#schemeContext(args, turnId);
         // {§context-fit} — one measure for everything this turn lands: the budget less the packet as it
         // would render now. The drained notices join the same facts below.
-        const facts = { turnId, seq, gitStatus, notices: [], transientOpenLogEntryId: container.transientOpenLogEntryId, projection: { bodiless: new Set(), omitPreviousEmission: false } };
+        const facts = { turnId, seq, gitStatus, notices: [], transientOpenLogEntryId: container.transientOpenLogEntryId, projection: { bodiless: new Set(), omitEmissionHistory: false } };
         const fit = this.#fitFor(args, facts);
         const messages = await this.#publishMessages(args, turnId, fit);
         let nextActionIndex = await this.#readOpenPaths(args, turnId, messages.openPaths, messages.nextActionIndex, fit);
@@ -692,20 +718,20 @@ class TurnRunner {
         }
         return { nextActionIndex, openPaths };
     }
-    // {§methods-loop-run-open-paths}: selected workspace paths belong to the message.
+    // {§methods-loop-run-open-paths}: selected resources belong to the message.
     // Publish it, then dispatch ordinary core READs in that same turn;
     // missing/non-member paths retain their normal 4xx. Returns the next action index.
     async #readOpenPaths({ workspaceId, workerId, loopId, onDispatch, onSettled }, turnId, openPaths, fromSequence, fit) {
         let nextActionIndex = fromSequence;
         for (const [index, raw] of openPaths.entries()) {
-            const fileRead = {
+            const resourceRead = {
                 op: "READ", aside: null, lineMarker: null, matcher: null,
-                target: { kind: "local", raw },
+                target: parsePath(PathSyntax.escapeTarget(raw)),
                 metadata: null,
                 body: null, position: UNKNOWN_POSITION,
             };
             await this.#dispatch({
-                statement: fileRead, workspaceId, workerId, loopId, turnId,
+                statement: resourceRead, workspaceId, workerId, loopId, turnId,
                 sequence: nextActionIndex, origin: "_plurnk", onDispatch, onSettled,
                 fit: reserved(fit, openPaths.length - index - 1),
             });
@@ -728,12 +754,12 @@ class TurnRunner {
             transientOpenLogEntryId: facts.transientOpenLogEntryId,
             turnId: facts.turnId,
             bodiless: facts.projection.bodiless,
-            omitPreviousEmission: facts.projection.omitPreviousEmission,
+            omitEmissionHistory: facts.projection.omitEmissionHistory,
         });
-        // {§previous-emission}: all builds, including result-admission probes, shed the optional
+        // {§emission-history}: all builds, including result-admission probes, shed the optional
         // replay before taking result bodies. Share the decision across this request's rebuilds.
-        if (PacketWire.sectionContent(packet, "previous-emission").length > 0 && this.#packets.windowOverflow(packet, provider) !== null) {
-            facts.projection.omitPreviousEmission = true;
+        if (PacketWire.sectionContent(packet, "emission-history").length > 0 && this.#packets.windowOverflow(packet, provider) !== null) {
+            facts.projection.omitEmissionHistory = true;
             return this.#buildPacket(args, facts);
         }
         return packet;
@@ -796,12 +822,12 @@ class TurnRunner {
         }
     }
     // {§context-own-rows-fit} — one shedding step for whichever measure found the request over the wall: the
-    // previous program goes whole first ({§previous-emission}), then the newest rows still carrying a body,
+    // previous program goes whole first ({§emission-history}), then the newest rows still carrying a body,
     // enough of them by their rendered tokens to shed the excess; every body stays stored. Null when nothing
     // is left to take.
     async #shed(args, request, overflow) {
-        if (!request.projection.omitPreviousEmission && PacketWire.sectionContent(request.packet, "previous-emission").length > 0) {
-            request.projection.omitPreviousEmission = true;
+        if (!request.projection.omitEmissionHistory && PacketWire.sectionContent(request.packet, "emission-history").length > 0) {
+            request.projection.omitEmissionHistory = true;
         }
         else {
             let shed = 0;
@@ -1260,7 +1286,8 @@ class TurnRunner {
                 source: "engine:capacity",
                 kind: "output_truncated",
                 level: "error",
-                message: `${cut}; no operations were performed`,
+                directive: DIRECTIVE.output,
+                message: `${cut}; no operations were performed.`,
             });
         }
         else {
@@ -1268,6 +1295,7 @@ class TurnRunner {
                 source: "engine:grammar",
                 kind: "invalid_emission",
                 level: "error",
+                directive: DIRECTIVE.emission,
                 message: diagnostic === undefined
                     ? INVALID_EMISSION_RECOVERY_MESSAGE
                     : `${INVALID_EMISSION_RECOVERY_MESSAGE} Parser: ${diagnostic.message}`,
@@ -1303,7 +1331,8 @@ class TurnRunner {
                 source: "engine:turn",
                 kind: "output_truncated",
                 level: "warn",
-                message: `${allowanceCut}; no authored operations were performed`,
+                directive: DIRECTIVE.output,
+                message: `${allowanceCut}; no authored operations were performed.`,
             });
         }
         // Non-fatal provider transport notices on an accepted turn. Forward each
@@ -1317,6 +1346,7 @@ class TurnRunner {
             this.#notices.push(workspaceId, workerId, loopId, {
                 source: notice.source,
                 kind: notice.kind,
+                ...(notice.directive === undefined ? {} : { directive: notice.directive }),
                 message: notice.message ?? "",
                 level: notice.level,
                 ...(located !== null
@@ -1328,27 +1358,19 @@ class TurnRunner {
             this.#notices.push(workspaceId, workerId, loopId, {
                 source: "engine:capacity",
                 kind: "output_truncated",
-                message: allowanceCut,
+                directive: DIRECTIVE.output,
+                message: `${allowanceCut}.`,
                 level: "warn",
             });
         }
-        // {§outside-text} — text outside the operations is the turn's own source, never a log row
-        // or a packet field; the model reads only its weight, the client reads its text once.
+        // {§outside-text} — a turn that fenced no operation keeps its text as its outside source: the
+        // evidence behind the empty turn's strike and a terminal's citation; no row, notice or NOTE.
         if (split.outside !== null) {
-            await Turn.recordSource(this.#db, request.turnId, "outside", split.outside.text, { modelCallId: emission.modelCallId });
-            this.#notices.push(workspaceId, workerId, loopId, {
-                source: "engine:turn",
-                kind: "outside_text",
-                level: "warn",
-                message: `${split.outside.tokens} tokens emitted outside OPs. Discarded.`,
-            });
+            await Turn.recordSource(this.#db, request.turnId, "outside", split.outside, { modelCallId: emission.modelCallId });
             this.#notify.outsideEventNotify?.(workspaceId, {
-                workerId,
-                loopId,
-                turnId: request.turnId,
+                workerId, loopId, turnId: request.turnId,
                 coordinate: `${request.workerName}-${request.loopSeq}-${request.seq}`,
-                text: split.outside.text,
-                tokens: split.outside.tokens,
+                text: split.outside, tokens: contentWeight(split.outside),
             });
         }
         // {§operator-grammar} — transport evidence only: the turn records whether the operator's
@@ -1404,7 +1426,7 @@ class TurnRunner {
             fit: request.fit,
             recoverableParseErrors: split.recoverableParseErrors,
             emptyTurn: split.emptyTurn,
-            finalResponse: split.finalResponse,
+            completionAllowed: split.completionAllowed,
             bare: {
                 provider: childProvider,
                 loopSequence: request.loopSeq,
@@ -1415,6 +1437,22 @@ class TurnRunner {
             onDispatch,
             onSettled,
         });
+        // {§continued-without-note} — a turn the loop continues past or parks on, having carried no NOTE
+        // forward in its program or from its reasoning, is told so in the next packet. An empty turn has
+        // its own no-operation row instead.
+        const ops = split.packetAssistant.ops;
+        if ((executed.status === 102 || executed.status === 202) && ops.length > 0
+            && !ops.some((statement) => "op" in statement && statement.op === "NOTE")) {
+            this.#notices.push(workspaceId, workerId, loopId, {
+                source: "engine:turn", kind: "continued_without_note", level: "warn", directive: DIRECTIVE.note, message: CONTINUED_WITHOUT_NOTE,
+            });
+        }
+        const annotationOnly = ops.length > 0 && ops.every((statement) => "op" in statement && statement.op === "NOTE");
+        if ((executed.status === 102 || executed.status === 202) && annotationOnly) {
+            this.#notices.push(workspaceId, workerId, loopId, {
+                source: "engine:turn", kind: "noted_without_operation", level: "warn", directive: DIRECTIVE.note, message: NOTED_WITHOUT_OPERATION,
+            });
+        }
         return turnResult(request, executed.status, {
             outcomes: executed.outcomes,
             progressed: executed.progressed,
@@ -1477,10 +1515,9 @@ class TurnRunner {
         const parseErrors = [];
         let contentStatementCount = 0;
         let hasUnparsedTail = false;
+        let operationOmitted = false;
         const parseNotices = [];
         const fabrications = [];
-        // {§outside-text}: every span outside an operation, verbatim and in source order; never an
-        // operation of its own, so a repetitive or length-cut response stays one source.
         const outside = [];
         if (preParsedOps !== undefined) {
             ops.push(...preParsedOps);
@@ -1496,13 +1533,33 @@ class TurnRunner {
                 span.setAttribute("statements", result.items.filter((item) => item.kind === "statement").length);
                 return result;
             });
+            // {§outside-text}: beside a fenced operation, the text between two operations is one NOTE at its
+            // position, annotation the model wrote without its fence; a turn that fenced no operation keeps
+            // its text as its outside source and stays an empty turn ({§empty-turn}). Echoed emission
+            // headings are announcements, not annotation, and are dropped ({§fabricated-log-entry}).
+            const fenced = parsed.items.filter((item) => item.kind === "statement").length;
+            let span = null;
+            const flushSpan = () => {
+                if (span === null)
+                    return;
+                const body = span.body.join("\n\n");
+                if (body.length > 0) {
+                    if (fenced > 0) {
+                        ops.push({ op: "NOTE", aside: null, metadata: null, target: null, lineMarker: null, body, position: span.position });
+                        contentStatementCount += 1;
+                    }
+                    else
+                        outside.push(body);
+                }
+                span = null;
+            };
             for (const item of parsed.items) {
+                if (item.kind !== "text")
+                    flushSpan();
                 if (item.kind === "statement") {
                     ops.push(item.statement);
                     contentStatementCount += 1;
                 }
-                // Operation boundaries stay the parser's responsibility; what falls outside them is
-                // stored as the turn's outside source and counted as nothing.
                 else if (item.kind === "text") {
                     // {§fabricated-log-entry}: a log-entry heading in outside text rejects the attempt.
                     const fabricated = FabricatedLog.find(item.content);
@@ -1510,16 +1567,22 @@ class TurnRunner {
                         fabrications.push({ message: FabricatedLog.message(fabricated.heading), line: item.position.line + fabricated.line, column: 1, source: "harness" });
                         continue;
                     }
-                    outside.push(item.content.trim());
+                    const body = FabricatedLog.stripEchoes(item.content);
+                    if (body.length === 0)
+                        continue;
+                    span ??= { body: [], position: item.position };
+                    span.body.push(body);
                 }
                 else if (item.kind === "error") {
                     const err = item.error;
                     if (err instanceof PlurnkParseError) {
+                        operationOmitted ||= err.operationOmitted;
                         if (err.severity === "warning") {
                             parseNotices.push({
                                 source: "grammar",
                                 kind: "parse_advisory",
                                 level: "warn",
+                                directive: DIRECTIVE.advisory,
                                 message: err.message,
                                 position: {
                                     type: "content-offset",
@@ -1539,6 +1602,7 @@ class TurnRunner {
                     }
                 }
             }
+            flushSpan();
             // {§unparsed-tail-boundary} — the lexer's one boundary fact: from `unparsedTail.from` on,
             // nothing was read. The statements that closed before it are ordinary facts and run; the
             // loss itself is one more hard diagnostic, a failed row the model sees. An emission that
@@ -1555,6 +1619,7 @@ class TurnRunner {
                 source: "grammar:reasoning",
                 kind: "parse_advisory",
                 level: "warn",
+                directive: DIRECTIVE.advisory,
                 message: warning.message,
                 parserSource: warning.source,
             });
@@ -1571,9 +1636,9 @@ class TurnRunner {
         parseErrors.unshift(...fabrications.slice(0, 1));
         const emissionStatements = preParsedOps === undefined && contentStatementCount > 0 ? [...ops] : null;
         ops.unshift(...reasoningOps);
-        const finalResponse = TurnDisposition.requestsCompletion(ops)
-            && !hasUnparsedTail && parseErrors.length === 0
-            && assistant.finishReason !== "length";
+        const completionAllowed = !hasUnparsedTail && !operationOmitted && !assistant.nativeToolCalls
+            && parseErrors.every((error) => error.message === PlurnkParser.NO_VALID_OPERATION)
+            && !["length", "content_filter", "tool_calls"].includes(assistant.finishReason ?? "");
         const emptyTurn = preParsedOps === undefined && operationCount === 0 && !hasUnparsedTail;
         // {§unparsed-tail-boundary}: outside text is not operational work.
         const emissionValid = fabrications.length === 0 && (preParsedOps !== undefined
@@ -1582,7 +1647,6 @@ class TurnRunner {
         const recoverableParseErrors = parseErrors
             .filter((error) => error.message !== PlurnkParser.NO_VALID_OPERATION)
             .toSorted(comparePosition);
-        const outsideText = outside.join("\n\n");
         return {
             packetAssistant: { content: assistant.content, ops, reasoning },
             sourceBacked: preParsedOps === undefined,
@@ -1590,10 +1654,10 @@ class TurnRunner {
             parseErrors,
             recoverableParseErrors: emissionValid ? recoverableParseErrors : [],
             emptyTurn,
-            finalResponse,
+            completionAllowed,
             parseNotices,
             emissionValid,
-            outside: outside.length === 0 ? null : { text: outsideText, tokens: contentWeight(outsideText) },
+            outside: outside.length === 0 ? null : outside.join("\n\n"),
             emissionStatements,
         };
     }