@junghanacs/entwurf 0.41.2 → 0.50.0

package/mcp/entwurf-bridge/dist/pi-extensions/lib/agent-guidance.js

@@ -0,0 +1,299 @@
+/**
+ * Product-owned natural-language logic, authored only in root ENTWURF.json (#154).
+ * One module-relative file, read once. The compiled layout carries an exact copy at
+ * dist/ENTWURF.json; no cwd/HOME search, override, old-text fallback or hot reload.
+ * Existing operator engraving and user-configuration contracts are unrelated.
+ */
+import { readFileSync } from "node:fs";
+const TOOL_SPEC = {
+    entwurf_v2: { durable: true, parameters: ["target", "intent", "message", "mode", "wants_reply"] },
+    entwurf_self: { durable: true, parameters: [] },
+    entwurf_peers: { durable: true, parameters: [] },
+    entwurf_inbox_read: { durable: true, parameters: ["gardenId"] },
+    entwurf_register_native: { durable: false, parameters: ["backend", "nativeSessionId", "cwd"] },
+    entwurf_fresh_call: {
+        durable: true,
+        parameters: ["backend", "model", "task", "cwd", "placement.tmuxSession", "placement"],
+    },
+    entwurf_resume_call: { durable: true, parameters: ["target"] },
+    entwurf_retire_call: { durable: true, parameters: ["target"] },
+    entwurf_callback: { durable: true, parameters: [] },
+};
+/** Frozen entwurf_v2 reject wire ids whose static next-step hint text lives in the root file. */
+const REJECT_HINT_REASONS = [
+    "dormant-fire-forget-unsupported",
+    "indeterminate-no-spawn",
+    "native-push-target-dead",
+    "native-push-probe-indeterminate",
+    "native-push-paused",
+];
+/** Frozen entwurf_resume_call record/liveness reject wire ids whose static hint text lives in the root file. */
+const RESUME_REJECT_HINT_REASONS = [
+    "target-invalid",
+    "target-backend-unsupported",
+    "target-locked",
+    "target-live",
+    "target-indeterminate",
+    "target-receiver-absent",
+    "target-receiver-corrupt",
+    "target-receiver-mismatch",
+    "target-receiver-unbound",
+    "target-address-conflict",
+    "launch-refused",
+];
+/** Frozen entwurf_fresh_call tmux launch-stage reject wire ids whose static hint text lives in the root file. */
+const FRESH_LAUNCH_REJECT_HINT_REASONS = [
+    "no-tmux-context",
+    "anchor-malformed",
+    "anchor-unresolved",
+    "anchor-mismatch",
+    "caller-identity-unavailable",
+    "cwd-not-absolute",
+    "cwd-format-token",
+    "cwd-missing",
+    "cwd-not-directory",
+    "tmux-session-name-invalid",
+    "tmux-session-missing",
+    "model-empty",
+    "task-empty",
+    "runtime-unresolved",
+    "runtime-not-absolute",
+    "runtime-path-whitespace",
+    "runtime-missing",
+    "runtime-not-regular-file",
+    "runtime-not-executable",
+];
+/** Frozen entwurf_resume_call tmux launch-stage reject wire ids whose static hint text lives in the root file. */
+const RESUME_LAUNCH_REJECT_HINT_REASONS = [
+    "no-tmux-context",
+    "anchor-malformed",
+    "anchor-unresolved",
+    "anchor-mismatch",
+    "cwd-not-absolute",
+    "cwd-format-token",
+    "cwd-missing",
+    "cwd-not-directory",
+    "herdr-resume-unsupported",
+    "runtime-unresolved",
+    "runtime-not-absolute",
+    "runtime-path-whitespace",
+    "runtime-missing",
+    "runtime-not-regular-file",
+    "runtime-not-executable",
+];
+/** Frozen keys of the static delivery-result clauses whose text lives in the root file; the
+ * receipts around them (syntax, branch conditions, slots, punctuation) stay code-owned. */
+const DELIVERY_RESULT_CLAUSE_KEYS = [
+    "finalized-rejected",
+    "dirty-lock",
+    "remote-accepted",
+    "remote-reported-error",
+    "remote-indeterminate",
+];
+/** Frozen wire ids of the reject hints whose authored text sits on either side of ONE code-owned
+ * slot, and each one's exact segment keys. The slot value, the reason branch and the
+ * concatenation stay code-owned; the root file holds only the text around the slot. */
+const SLOTTED_REJECT_HINT_SEGMENTS = {
+    "record-less-socket": ["beforeFreshCutPrescription", "afterFreshCutPrescription"],
+};
+function record(value, at) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`ENTWURF.json ${at}: expected an object`);
+    }
+}
+function keys(value, expected, at) {
+    const actual = Object.keys(value).sort();
+    const wanted = [...expected].sort();
+    if (actual.length !== wanted.length || actual.some((key, i) => key !== wanted[i])) {
+        throw new Error(`ENTWURF.json ${at}: keys must be exactly ${wanted.join(", ")}`);
+    }
+}
+function text(value, at) {
+    if (typeof value !== "string" || value.length === 0) {
+        throw new Error(`ENTWURF.json ${at}: expected a non-empty string`);
+    }
+}
+/**
+ * JSON.parse owns strict grammar, but its last-key-wins value is never enough.
+ * Walk the ORIGINAL, already grammar-checked tokens and reject duplicate DECODED
+ * object keys before returning data. Object scopes are independent; strings that
+ * are values (including punctuation and escaped quotes) are never key tokens.
+ */
+function rejectDuplicateKeys(source) {
+    let pos = 0;
+    const space = () => {
+        while (pos < source.length && /[\x20\t\r\n]/.test(source[pos]))
+            pos++;
+    };
+    const string = () => {
+        const start = pos++;
+        while (pos < source.length) {
+            if (source[pos] === "\\")
+                pos += 2;
+            else if (source[pos++] === '"')
+                return JSON.parse(source.slice(start, pos));
+        }
+        throw new Error("ENTWURF.json: unterminated string");
+    };
+    const value = () => {
+        space();
+        if (source[pos] === "{") {
+            pos++;
+            space();
+            const seen = new Set();
+            if (source[pos] !== "}") {
+                for (;;) {
+                    space();
+                    const key = string();
+                    if (seen.has(key))
+                        throw new Error(`ENTWURF.json: duplicate object key ${JSON.stringify(key)}`);
+                    seen.add(key);
+                    space();
+                    pos++; // colon; JSON.parse already certified the grammar
+                    value();
+                    space();
+                    if (source[pos] !== ",")
+                        break;
+                    pos++;
+                }
+            }
+            pos++;
+        }
+        else if (source[pos] === "[") {
+            pos++;
+            space();
+            if (source[pos] !== "]") {
+                for (;;) {
+                    value();
+                    space();
+                    if (source[pos] !== ",")
+                        break;
+                    pos++;
+                }
+            }
+            pos++;
+        }
+        else if (source[pos] === '"') {
+            string();
+        }
+        else {
+            while (pos < source.length && !/[\x20\t\r\n,}\]]/.test(source[pos]))
+                pos++;
+        }
+    };
+    value();
+}
+function freeze(value) {
+    if (value === null || typeof value !== "object")
+        return;
+    for (const child of Object.values(value))
+        freeze(child);
+    Object.freeze(value);
+}
+/** Pure data-validation seam; production always reads the one fixed module URL below. */
+export function parseEntwurfGuidance(source) {
+    const data = JSON.parse(source);
+    rejectDuplicateKeys(source);
+    record(data, "root");
+    if (data.schemaVersion !== 6)
+        throw new Error("ENTWURF.json: unsupported schemaVersion");
+    keys(data, [
+        "_about",
+        "schemaVersion",
+        "revision",
+        "history",
+        "tools",
+        "rejectHints",
+        "resumeRejectHints",
+        "freshLaunchRejectHints",
+        "resumeLaunchRejectHints",
+        "deliveryResultClauses",
+        "slottedRejectHints",
+    ], "root");
+    if (!Number.isSafeInteger(data.revision) || data.revision < 1) {
+        throw new Error("ENTWURF.json: revision must be a positive safe integer");
+    }
+    record(data._about, "_about");
+    keys(data._about, ["purpose", "ownership", "scope", "editing"], "_about");
+    for (const [key, value] of Object.entries(data._about))
+        text(value, `_about.${key}`);
+    if (!Array.isArray(data.history) || data.history.length === 0) {
+        throw new Error("ENTWURF.json: history must be a non-empty array");
+    }
+    for (const entry of data.history) {
+        record(entry, "history entry");
+        keys(entry, ["revision", "source", "issue", "change"], "history entry");
+        if (!Number.isSafeInteger(entry.revision) ||
+            entry.revision < 1 ||
+            entry.revision > data.revision) {
+            throw new Error("ENTWURF.json: history revision must name an existing payload revision");
+        }
+        for (const key of ["source", "issue", "change"])
+            text(entry[key], `history.${key}`);
+    }
+    record(data.tools, "tools");
+    keys(data.tools, Object.keys(TOOL_SPEC), "tools");
+    for (const name of Object.keys(TOOL_SPEC)) {
+        const tool = data.tools[name];
+        record(tool, name);
+        keys(tool, ["descriptions", "parameters"], name);
+        record(tool.descriptions, `${name}.descriptions`);
+        keys(tool.descriptions, TOOL_SPEC[name].durable ? ["mcp", "durable"] : ["mcp"], `${name}.descriptions`);
+        for (const [rail, value] of Object.entries(tool.descriptions))
+            text(value, `${name}.descriptions.${rail}`);
+        record(tool.parameters, `${name}.parameters`);
+        keys(tool.parameters, TOOL_SPEC[name].parameters, `${name}.parameters`);
+        for (const [field, value] of Object.entries(tool.parameters))
+            text(value, `${name}.parameters.${field}`);
+    }
+    record(data.rejectHints, "rejectHints");
+    keys(data.rejectHints, REJECT_HINT_REASONS, "rejectHints");
+    for (const [reason, value] of Object.entries(data.rejectHints))
+        text(value, `rejectHints.${reason}`);
+    record(data.resumeRejectHints, "resumeRejectHints");
+    keys(data.resumeRejectHints, RESUME_REJECT_HINT_REASONS, "resumeRejectHints");
+    for (const [reason, value] of Object.entries(data.resumeRejectHints))
+        text(value, `resumeRejectHints.${reason}`);
+    record(data.freshLaunchRejectHints, "freshLaunchRejectHints");
+    keys(data.freshLaunchRejectHints, FRESH_LAUNCH_REJECT_HINT_REASONS, "freshLaunchRejectHints");
+    for (const [reason, value] of Object.entries(data.freshLaunchRejectHints))
+        text(value, `freshLaunchRejectHints.${reason}`);
+    record(data.resumeLaunchRejectHints, "resumeLaunchRejectHints");
+    keys(data.resumeLaunchRejectHints, RESUME_LAUNCH_REJECT_HINT_REASONS, "resumeLaunchRejectHints");
+    for (const [reason, value] of Object.entries(data.resumeLaunchRejectHints))
+        text(value, `resumeLaunchRejectHints.${reason}`);
+    record(data.deliveryResultClauses, "deliveryResultClauses");
+    keys(data.deliveryResultClauses, DELIVERY_RESULT_CLAUSE_KEYS, "deliveryResultClauses");
+    for (const [key, value] of Object.entries(data.deliveryResultClauses))
+        text(value, `deliveryResultClauses.${key}`);
+    record(data.slottedRejectHints, "slottedRejectHints");
+    keys(data.slottedRejectHints, Object.keys(SLOTTED_REJECT_HINT_SEGMENTS), "slottedRejectHints");
+    for (const reason of Object.keys(SLOTTED_REJECT_HINT_SEGMENTS)) {
+        const segments = data.slottedRejectHints[reason];
+        record(segments, `slottedRejectHints.${reason}`);
+        keys(segments, SLOTTED_REJECT_HINT_SEGMENTS[reason], `slottedRejectHints.${reason}`);
+        for (const [key, value] of Object.entries(segments))
+            text(value, `slottedRejectHints.${reason}.${key}`);
+    }
+    freeze(data);
+    return data;
+}
+const guidance = parseEntwurfGuidance(readFileSync(new URL("../../ENTWURF.json", import.meta.url), "utf8"));
+/** Only these exact payload strings enter tool schemas; _about/history never do. */
+export const ENTWURF_TOOL_GUIDANCE = guidance.tools;
+/** Static next-step text appended to these entwurf_v2 rejections; the decider and wire ids stay code-owned. */
+export const ENTWURF_REJECT_HINTS = guidance.rejectHints;
+/** Static next-step text in these entwurf_resume_call record/liveness rejections; the verb and the shared ACP model hint stay code-owned. */
+export const ENTWURF_RESUME_REJECT_HINTS = guidance.resumeRejectHints;
+/** Static tmux launch-stage hints of entwurf_fresh_call; slot-bearing, ACP and preflight-leaf hints stay code-owned. */
+export const ENTWURF_FRESH_LAUNCH_REJECT_HINTS = guidance.freshLaunchRejectHints;
+/** Static tmux launch-stage hints of entwurf_resume_call, kept apart from the fresh verb even where the text matches. */
+export const ENTWURF_RESUME_LAUNCH_REJECT_HINTS = guidance.resumeLaunchRejectHints;
+/** Static delivery-result clauses of the entwurf_v2 dirty-lock and remote-pair receipts; the receipt syntax around them stays code-owned. */
+export const ENTWURF_DELIVERY_RESULT_CLAUSES = guidance.deliveryResultClauses;
+/** Text on either side of one code-owned slot per reject reason; the slot value and the concatenation stay with the consumer. */
+export const ENTWURF_SLOTTED_REJECT_HINTS = guidance.slottedRejectHints;
+export const ENTWURF_GUIDANCE_VERSION = Object.freeze({
+    schemaVersion: guidance.schemaVersion,
+    revision: guidance.revision,
+});

package/mcp/entwurf-bridge/dist/pi-extensions/lib/entwurf-v2-surface.js

@@ -17,6 +17,7 @@
  *     surface never needs to name the `EntwurfV2RunResult` union (it only sees `{text,isError}`).
  */
 import { basename } from "node:path";
+import { ENTWURF_DELIVERY_RESULT_CLAUSES, ENTWURF_REJECT_HINTS, ENTWURF_SLOTTED_REJECT_HINTS, } from "./agent-guidance.js";
 import { makeProductionEntwurfV2Deps } from "./entwurf-v2-production.js";
 import { runEntwurfV2 } from "./entwurf-v2-runner.js";
 import { FRESH_CUT_PRESCRIPTION } from "./meta-session.js";
@@ -36,7 +37,9 @@ export function toDispatchInput(params) {
  * Detour B (B-a) — actionable rendering of an honest reject. The decider is UNCHANGED:
  * a reject stays a reject (Hard Rule 3). This only appends a one-line "what to do instead"
  * to the reject TEXT, so an honest reject stops reading as "delivery impossible". Returns
- * undefined for rejects with no useful next step.
+ * undefined for rejects with no useful next step. Hint English is authored in root ENTWURF.json
+ * (#154); the reason switch stays here, and so do the record-less-socket slot value and its
+ * concatenation (#154 E1b).
  */
 export function actionableRejectHint(reason) {
     switch (reason) {
@@ -45,11 +48,7 @@ export function actionableRejectHint(reason) {
             // state — the citizen exists and is not running — matters more than ever now that
             // there is no verb behind it: a caller that reads "reject" as "wrong id" goes
             // looking in the wrong place.
-            return ("this citizen's record is intact but its session is not running, and delivery has no way to wake it. " +
-                "The resume that used to answer here launched a hidden background child and was withdrawn under the " +
-                "visible-first rule; the visible same-id resume is the separate lifecycle verb entwurf_resume_call. " +
-                "Only on an explicit operator request, use entwurf_resume_call {target} for Pi or Claude Code; " +
-                "it submits no prompt. This capability hint is not permission to resume automatically.");
+            return ENTWURF_REJECT_HINTS["dormant-fire-forget-unsupported"];
         case "indeterminate-no-spawn":
             // The socket probe did not settle, so liveness is UNKNOWN — an unestablished probe
             // is not a measured death, and dispatching into it could double-deliver. Say
@@ -60,31 +59,27 @@ export function actionableRejectHint(reason) {
             // (never dispatch into an indeterminate target), not a capability that still
             // exists. So the hint's job is to say plainly what did NOT happen: nothing
             // delivered, nothing started.
-            return ("the control-socket probe was inconclusive, so the target's liveness is UNKNOWN — this is not a " +
-                "measured death. NOTHING was delivered and NO process was started (the reason id keeps its frozen " +
-                "'-no-spawn' wire spelling from an era when one could be; entwurf_v2 starts nothing on any rail). " +
-                "Re-run entwurf_peers to re-probe; if it stays indeterminate, check for a stale socket file left at " +
-                "that garden id by a session that died without cleaning up.");
+            return ENTWURF_REJECT_HINTS["indeterminate-no-spawn"];
         case "native-push-target-dead":
             // The adapter probe found no live native host serving this conversation/thread. Stays
             // backend-neutral: agy speaks conversations over an LS port, Codex threads over an
             // app-server socket, and this hint is read by callers of both.
-            return "the native-push conversation/thread is not live — no native host (harness process or app-server) answered the probe for it. Re-open that conversation/thread in its own harness, then retry; there is nothing to inject into.";
+            return ENTWURF_REJECT_HINTS["native-push-target-dead"];
         case "native-push-probe-indeterminate":
             // Native host up, but nothing served this conversation/thread — inconclusive, not a
             // hard dead. Backend-neutral for the same reason as the dead cell above.
-            return "the native host (harness process or app-server) is up, but nothing served this conversation/thread, so the probe is INCONCLUSIVE — not a measured death. Retry once it is loaded, or verify the conversation/thread id.";
+            return ENTWURF_REJECT_HINTS["native-push-probe-indeterminate"];
         case "native-push-paused":
             // #152: a policy refusal, not a liveness verdict — this dispatch probed and sent nothing.
-            return "native-push for this backend is paused (#152): its language server refused entwurf's measured external calls for a missing CSRF token, so this dispatch probed and sent nothing. The citizen and its record are kept; reach it from inside its own harness instead.";
-        case "record-less-socket":
+            return ENTWURF_REJECT_HINTS["native-push-paused"];
+        case "record-less-socket": {
             // #50 C4: name the true cause AND the fix — a bare socket is a diagnostic
-            // state, not an addressable citizen (the record is the address).
-            return ("a control socket exists at this garden id but NO meta-record claims it — the record is the " +
-                "sole address authority, so a bare socket is not an addressable citizen. If a pre-record-era " +
-                "resident owns that socket, restart it under the current runtime (session_start births its " +
-                `record); if the store predates the current generation, quiesce and archive it with ` +
-                `${FRESH_CUT_PRESCRIPTION}. A stale/forged socket should be removed.`);
+            // state, not an addressable citizen (the record is the address). The text on either
+            // side of the fix command is authored in root ENTWURF.json; the command itself stays
+            // with its owner (meta-session.ts), so the root file never copies it.
+            const hint = ENTWURF_SLOTTED_REJECT_HINTS["record-less-socket"];
+            return `${hint.beforeFreshCutPrescription}${FRESH_CUT_PRESCRIPTION}${hint.afterFreshCutPrescription}`;
+        }
         default:
             return undefined;
     }
@@ -185,13 +180,14 @@ export function renderEntwurfV2Result(result) {
                 // the same acceptance vocabulary the ordinary receipt uses is named here too — a
                 // dirty lock is a reason to be MORE precise about what happened, not less, because
                 // the operator is about to decide by hand whether anything needs re-sending.
+                // The two static clauses are authored in root ENTWURF.json (#154 E1a); this receipt's
+                // syntax, branches and slots stay here.
                 const what = result.finalizedOutcome === "rejected"
-                    ? `rejected${result.finalizedRejectReason ? ` (${result.finalizedRejectReason})` : ""} — the receiver refused it; nothing was accepted`
+                    ? `rejected${result.finalizedRejectReason ? ` (${result.finalizedRejectReason})` : ""} — ${ENTWURF_DELIVERY_RESULT_CLAUSES["finalized-rejected"]}`
                     : `${result.finalizedBoundary ?? "mailbox-enqueued"}${result.finalizedMessagePath ? ` (enqueued ${basename(result.finalizedMessagePath)})` : ""}`;
                 return {
-                    text: `entwurf_v2 ${result.transport} finalized as ${what}, and the lock is DIRTY ` +
-                        `(release failed) — do NOT retry, a re-send would double-deliver. Clear the lock by hand.` +
-                        `\n  error: ${result.error}`,
+                    text: `entwurf_v2 ${result.transport} finalized as ${what}, and ` +
+                        `${ENTWURF_DELIVERY_RESULT_CLAUSES["dirty-lock"]}\n  error: ${result.error}`,
                     isError: true,
                 };
             }