clay-server 4.0.0-beta.15 → 4.0.0-beta.16

package/lib/capsule-frame-server.js

@@ -132,8 +132,34 @@ function createCapsuleFrameServer(opts) {
       "    if (data.type === \"state\" && typeof api.onState === \"function\") api.onState(data.state || {});",
       "    else if (data.type === \"event\" && typeof api.onEvent === \"function\") api.onEvent(data.event || null);",
       "  });",
+      "  // The host owns the iframe box, so the frame reports its natural",
+      "  // content height and the host resizes the box to fit. Without this",
+      "  // the box stays fixed and a widening layout clips the element.",
+      "  var reportedHeight = 0;",
+      "  var reportQueued = false;",
+      "  function reportSize() {",
+      "    reportQueued = false;",
+      "    var root = document.documentElement;",
+      "    var body = document.body;",
+      "    var height = Math.ceil(Math.max(root ? root.scrollHeight : 0, body ? body.scrollHeight : 0));",
+      "    if (!height || height === reportedHeight) return;",
+      "    reportedHeight = height;",
+      "    window.parent.postMessage({ clayCapsuleFrame: 1, type: \"size\", height: height }, \"*\");",
+      "  }",
+      "  function queueReport() {",
+      "    if (reportQueued) return;",
+      "    reportQueued = true;",
+      "    if (typeof requestAnimationFrame === \"function\") requestAnimationFrame(reportSize);",
+      "    else setTimeout(reportSize, 50);",
+      "  }",
+      "  if (typeof ResizeObserver === \"function\") {",
+      "    new ResizeObserver(queueReport).observe(document.documentElement);",
+      "    if (document.body) new ResizeObserver(queueReport).observe(document.body);",
+      "  }",
+      "  window.addEventListener(\"resize\", queueReport);",
       "  window.addEventListener(\"load\", function () {",
       "    window.parent.postMessage({ clayCapsuleFrame: 1, type: \"ready\" }, \"*\");",
+      "    queueReport();",
       "  });",
       "})();",
     ].join("\n");

package/lib/capsule-mate-turn.js

@@ -0,0 +1,105 @@
+// Bridges Capsule engagement events to the opponent Mate's session.
+//
+// This module knows no game. A Capsule's Logic declares on its causal event
+// when the Mate should be engaged (`event.engage = {kind}`): "turn" asks the
+// Mate to read the state and act, "start" asks it to acknowledge a fresh
+// game without acting. The bridge only carries that declaration: it finds the
+// opponent Mate's project and delivers a prompt through it, so the Capsule
+// round-trips for every game alike: the human plays on the Display, the Mate
+// wakes up, reads the state over clay_tool_snapshot, and acts through the
+// same clay_tool_act pipeline. The prompt carries words only; it grants no
+// authority the Mate does not already have, and a lost prompt costs a
+// reminder, never the game. Only human-caused events engage, whatever Logic
+// declares, so a Mate can never wake itself.
+//
+// The opponent is the Mate that last acted on this Capsule for this user.
+// Before any Mate has acted, the built-in host Mate (Clay) takes the seat, so
+// a fresh game is playable with zero setup.
+
+function attachCapsuleMateTurn(deps) {
+  var users = deps.users;
+  var findMateProject = deps.findMateProject || null;
+  var broadcastToUser = deps.broadcastToUser || null;
+  var opponents = Object.create(null);
+  var nudgedSeqs = Object.create(null);
+
+  function keyFor(userId, toolId) {
+    return String(userId) + "\u0000" + String(toolId);
+  }
+
+  // Called when a Mate acts on a Capsule: that Mate holds the opponent seat
+  // for this user's game from then on.
+  function rememberOpponent(userId, toolId, mateId) {
+    if (typeof mateId === "string" && mateId) opponents[keyFor(userId, toolId)] = mateId;
+  }
+
+  function turnPrompt(manifest) {
+    return "Capsule turn: it is your seat's turn in the \"" + manifest.name + "\" Capsule (toolId \"" + manifest.id + "\"). "
+      + "Read the game with clay_tool_snapshot, decide your move, and take your turn with clay_tool_act. "
+      + "Keep playing until the turn passes away from your seat, and say your reasoning in one or two short sentences as you play. "
+      + "If an act is refused, read the snapshot again instead of retrying blindly.";
+  }
+
+  function startPrompt(manifest) {
+    return "Capsule game: the user just started a new game of \"" + manifest.name + "\" (toolId \"" + manifest.id + "\") against you. "
+      + "The user moves first. Reply with one short line of table talk, and do not call clay_tool_act now: "
+      + "you will be woken in this session whenever it is your turn.";
+  }
+
+  // Fire-and-forget from the act pipeline: delivers a Logic-declared
+  // engagement exactly once per event, and only for human-caused events.
+  function maybeNudge(userId, manifest, actor, event) {
+    if (!findMateProject || !manifest || !event) return Promise.resolve(null);
+    if (actor !== "human") return Promise.resolve(null);
+    var kind = event.engage && (event.engage.kind === "turn" || event.engage.kind === "start") ? event.engage.kind : null;
+    if (!kind) return Promise.resolve(null);
+    var key = keyFor(userId, manifest.id);
+    if (nudgedSeqs[key] !== undefined && event.seq <= nudgedSeqs[key]) return Promise.resolve(null);
+    nudgedSeqs[key] = event.seq;
+    return Promise.resolve().then(function () {
+      var mateId = opponents[key] || null;
+      // The mates registry keys single-user data off a null userId, exactly
+      // like the home chat surface does.
+      var mateUserId = users.isMultiUser() ? userId : null;
+      var found = findMateProject(mateUserId, mateId, true);
+      if (!found && mateId) found = findMateProject(mateUserId, null, true);
+      if (!found || !found.ctx || typeof found.ctx.deliverCapsuleTurn !== "function") {
+        console.error("[capsules] No Mate project could take the '" + manifest.id + "' turn; is a Mate installed?");
+        return null;
+      }
+      var principal = { userId: users.isMultiUser() ? userId : null };
+      var mateId = found.mate && found.mate.id ? found.mate.id : null;
+      return found.ctx.deliverCapsuleTurn(principal, {
+        toolId: manifest.id,
+        toolName: manifest.name,
+        kind: kind,
+        text: kind === "turn" ? turnPrompt(manifest) : startPrompt(manifest),
+      }).then(function (delivered) {
+        // An explicit game start navigates the user's home board into the
+        // Mate's game session, so starting a game visibly opens the table.
+        if (broadcastToUser && delivered && delivered.reference && mateId) {
+          broadcastToUser(userId, {
+            type: "capsule_game_session",
+            toolId: manifest.id,
+            toolName: manifest.name,
+            mateId: mateId,
+            sessionId: delivered.reference,
+            kind: kind,
+            created: !!delivered.created,
+          });
+        }
+        return delivered;
+      });
+    }).catch(function (error) {
+      console.error("[capsules] Could not deliver the Mate's turn:", error && error.message ? error.message : error);
+      return null;
+    });
+  }
+
+  return {
+    rememberOpponent: rememberOpponent,
+    maybeNudge: maybeNudge,
+  };
+}
+
+module.exports = { attachCapsuleMateTurn: attachCapsuleMateTurn };

package/lib/capsule-pig-logic.js

@@ -159,6 +159,18 @@ function reset(state, seat) {
   return newGame();
 }
 
+function statusTextFor(state, complete, userTurn) {
+  if (complete) {
+    return state.winner === USER ? "You win this game!" : "Your Mate wins this game.";
+  }
+  if (userTurn) {
+    return state.turnTotal > 0
+      ? "Your turn: roll again or hold to bank " + state.turnTotal + " point(s)."
+      : "Your turn: roll the die.";
+  }
+  return "Your Mate's turn. Moves appear here as they happen.";
+}
+
 // The projection a Display renders and a Mate reads. It adds no meaning that is
 // absent from state: every derived field is a restatement of the fields above.
 // The score series exist because a progress chart binds to a collection.
@@ -172,7 +184,12 @@ function project(state) {
     userScoreSeries: [{ seat: SEAT_LABELS.user, value: state.scores.user }],
     mateScoreSeries: [{ seat: SEAT_LABELS.mate, value: state.scores.mate }],
     turnTotal: state.turnTotal,
+    turnTotalSeries: [{ label: "Turn total", value: state.turnTotal }],
     turnTotalText: "Turn total " + state.turnTotal + " of " + state.target + ", " + SEAT_LABELS[state.turn] + " to play.",
+    statusText: statusTextFor(state, complete, userTurn),
+    lastRollText: state.lastRoll === null
+      ? "No rolls yet."
+      : "Last roll: " + state.lastRoll + " by " + SEAT_LABELS[state.lastActor || state.turn] + ".",
     lastRoll: state.lastRoll,
     lastActor: state.lastActor,
     winner: state.winner,
@@ -184,17 +201,32 @@ function project(state) {
   };
 }
 
+// When the Mate should be engaged is a game rule, so Logic declares it on the
+// event rather than the host inferring it from Pig's fields. The host bridge
+// delivers any declared engagement generically for every Capsule: "turn"
+// means play your seat now, "start" means the human opened a fresh game and
+// you should acknowledge it without acting.
+function engagementFor(seat, actionId, next) {
+  if (seat !== USER) return null;
+  if (next.status === "playing" && next.turn === MATE) return { kind: "turn" };
+  if (actionId === "reset" && next.status === "playing") return { kind: "start" };
+  return null;
+}
+
 // Causality for the live Display: {actor, action, previous, next} plus a
 // monotonic seq. Sending only the new state would make a Mate's move teleport
 // onto the human's screen; the event lets the Display replay and attribute it.
 function buildEvent(seat, actionId, previous, next) {
-  return {
+  var event = {
     seq: next.eventSeq,
     actor: seat,
     action: actionId,
     previous: previous,
     next: next,
   };
+  var engage = engagementFor(seat, actionId, next);
+  if (engage) event.engage = engage;
+  return event;
 }
 
 function seatFor(context) {

package/lib/capsule-server-runtimes.js

@@ -13,11 +13,9 @@ var path = require("path");
 var toolStorage = require("./tool-storage");
 var toolsRegistry = require("./tools-registry");
 var pigLogic = require("./capsule-pig-logic");
-var tictactoeLogic = require("./capsule-tictactoe-logic");
 
 var RUNTIME_FACTORIES = {
   pig: pigLogic.createRuntime,
-  tictactoe: tictactoeLogic.createRuntime,
 };
 
 function hasRuntime(toolId) {

package/lib/capsules/pig/display.js

@@ -42,6 +42,14 @@
   controls.style.marginTop = "10px";
   root.appendChild(controls);
 
+  var rulesEl = document.createElement("p");
+  rulesEl.textContent = "Pig is a push-your-luck dice game: roll to build this turn's total, but a 1 loses it. Hold to bank your points; the first player to 100 wins.";
+  rulesEl.style.margin = "12px 0 0";
+  rulesEl.style.color = "#b8b8b8";
+  rulesEl.style.fontSize = "12px";
+  rulesEl.style.lineHeight = "1.45";
+  root.appendChild(rulesEl);
+
   function makeButton(label, action, accent) {
     var button = document.createElement("button");
     button.type = "button";

package/lib/capsules/pig/manifest.json

@@ -5,5 +5,5 @@
   "lucideIcon": "sparkles",
   "description": "Two-player push-your-luck dice game shared by the user and one Mate.",
   "useWhen": "Use when the user wants to play Pig, take a turn, or hear how the current game stands.",
-  "skills": "# Pig\n\nA two-seat push-your-luck dice game. The seats are `user` and `mate`; the person holds the user seat and you hold the mate seat. All randomness, turn order, and scoring are enforced server-side by the Capsule's Logic; you cannot roll a die yourself, and neither can the user.\n\n## Rules\n\n- Seats alternate turns. On your turn you may roll as often as you like.\n- Each roll adds its face value to the turn total. Rolling a 1 loses the entire turn total and passes play to the other seat.\n- Holding banks the turn total into your score and passes play.\n- The first seat to bank at least 100 points wins. A finished game is frozen until it is reset.\n- Only the user may reset a game that is still in progress. You may reset once the game is complete.\n\n## How to play\n\n1. `clay_tool_snapshot` with toolId `pig` to read the current state: `turn`, `scores.user`, `scores.mate`, `turnTotal`, `status`, `winner`, and `recentRolls`, which lists recent rolls only and never holds or wins.\n2. Act only when `turn` is `mate`. `clay_tool_act` with actionId `roll`, `hold`, or `reset`. Arguments are not used.\n3. An out-of-turn or post-game call is refused by Logic with an explanatory error. Read the snapshot again rather than retrying blindly.\n4. Every act returns the complete new state, so a snapshot immediately after an act is redundant.\n\n## Playing well\n\nThe interesting part of this Capsule is the judgement call, not the mechanics: decide whether to roll again or hold, and say why in your own words before you act. Typical play holds at a turn total near 20, but the score gap matters more than the rule of thumb, so explain the trade-off you are taking. Never claim a roll result before the act returns it."
+  "skills": "# Pig\n\nA two-seat push-your-luck dice game. The seats are `user` and `mate`; the person holds the user seat and you hold the mate seat. All randomness, turn order, and scoring are enforced server-side by the Capsule's Logic; you cannot roll a die yourself, and neither can the user.\n\n## Rules\n\n- Seats alternate turns. On your turn you may roll as often as you like.\n- Each roll adds its face value to the turn total. Rolling a 1 loses the entire turn total and passes play to the other seat.\n- Holding banks the turn total into your score and passes play.\n- The first seat to bank at least 100 points wins. A finished game is frozen until it is reset.\n- Only the user may reset a game that is still in progress. You may reset once the game is complete.\n\n## How to play\n\n1. `clay_tool_snapshot` with toolId `pig` to read the current state: `turn`, `scores.user`, `scores.mate`, `turnTotal`, `status`, `winner`, and `recentRolls`, which lists recent rolls only and never holds or wins.\n2. Act only when `turn` is `mate`. `clay_tool_act` with actionId `roll`, `hold`, or `reset`. Arguments are not used.\n3. An out-of-turn or post-game call is refused by Logic with an explanatory error. Read the snapshot again rather than retrying blindly.\n4. Every act returns the complete new state, so a snapshot immediately after an act is redundant.\n\n## Playing well\n\nThe interesting part of this Capsule is the judgement call, not the mechanics: decide whether to roll again or hold, and say why in your own words before you act. Typical play holds at a turn total near 20, but the score gap matters more than the rule of thumb, so explain the trade-off you are taking. Never claim a roll result before the act returns it.\n\n## Turn flow\n\nWhen the user's move hands the turn to your seat, Clay wakes you in a dedicated game session with a \"Capsule turn\" message. Take your whole turn there: roll as often as you judge right, then hold (or bust), and stop once the turn passes away from your seat. The user's Display updates live as you act, so never narrate moves you have not made. If nothing wakes you, you are not on turn."
 }

package/lib/capsules/pig/ui.json

@@ -3,16 +3,42 @@
   "props": { "gap": "md" },
   "children": [
     {
-      "type": "chart",
-      "bind": "userScoreSeries",
-      "props": { "label": "Your score", "kind": "progress", "categoryKey": "seat", "valueKey": "value", "max": 100 }
+      "type": "callout",
+      "when": { "equals": { "path": "$state.complete", "value": true } },
+      "props": { "title": "Game over", "text": { "$bind": "$state.statusText", "fallback": "Game over." }, "icon": "circle-check", "variant": "soft" },
+      "else": {
+        "type": "callout",
+        "props": { "title": "Pig", "text": { "$bind": "$state.statusText", "fallback": "Your turn: roll the die." }, "icon": "sparkles", "variant": "soft" }
+      }
     },
     {
-      "type": "chart",
-      "bind": "mateScoreSeries",
-      "props": { "label": "Your Mate's score", "kind": "progress", "categoryKey": "seat", "valueKey": "value", "max": 100 }
+      "type": "row",
+      "props": { "gap": "md", "wrap": true },
+      "children": [
+        {
+          "type": "chart",
+          "bind": "userScoreSeries",
+          "props": { "label": "Your score", "kind": "progress", "categoryKey": "seat", "valueKey": "value", "max": 100 }
+        },
+        {
+          "type": "chart",
+          "bind": "mateScoreSeries",
+          "props": { "label": "Your Mate's score", "kind": "progress", "categoryKey": "seat", "valueKey": "value", "max": 100 }
+        }
+      ]
+    },
+    {
+      "type": "row",
+      "props": { "gap": "md", "align": "center", "wrap": true },
+      "children": [
+        {
+          "type": "chart",
+          "bind": "turnTotalSeries",
+          "props": { "label": "Turn total", "kind": "metric", "valueKey": "value" }
+        },
+        { "type": "text", "props": { "text": { "$bind": "$state.lastRollText", "fallback": "No rolls yet." }, "role": "muted" } }
+      ]
     },
-    { "type": "text", "props": { "text": { "$bind": "$state.turnTotalText", "fallback": "Turn total 0 of 100." }, "role": "output" } },
     {
       "type": "row",
       "props": { "gap": "sm", "wrap": true },
@@ -20,26 +46,38 @@
         {
           "type": "button",
           "action": "roll",
-          "when": { "all": [{ "equals": { "path": "$state.status", "value": "playing" } }, { "equals": { "path": "$state.turn", "value": "user" } }] },
+          "when": { "equals": { "path": "$state.userTurn", "value": true } },
           "props": { "label": "Roll", "variant": "primary" },
           "else": { "type": "button", "action": "roll", "props": { "label": "Roll", "variant": "primary", "disabled": true } }
         },
         {
           "type": "button",
           "action": "hold",
-          "when": { "all": [{ "equals": { "path": "$state.status", "value": "playing" } }, { "equals": { "path": "$state.turn", "value": "user" } }] },
+          "when": { "equals": { "path": "$state.userTurn", "value": true } },
           "props": { "label": "Hold", "variant": "secondary" },
           "else": { "type": "button", "action": "hold", "props": { "label": "Hold", "variant": "secondary", "disabled": true } }
         },
-        { "type": "button", "action": "reset", "props": { "label": "Reset", "variant": "ghost" } }
+        {
+          "type": "button",
+          "action": "reset",
+          "when": { "equals": { "path": "$state.complete", "value": true } },
+          "props": { "label": "New game", "variant": "primary" },
+          "else": { "type": "button", "action": "reset", "props": { "label": "Start over", "variant": "ghost" } }
+        }
       ]
     },
     {
-      "type": "list",
-      "bind": "recentRolls",
-      "props": { "variant": "divided", "gap": "xs" },
+      "type": "section",
+      "props": { "label": "Recent rolls", "variant": "inset", "gap": "xs" },
       "children": [
-        { "type": "text", "props": { "text": "$item.text", "role": "body" } }
+        {
+          "type": "list",
+          "bind": "recentRolls",
+          "props": { "variant": "divided", "gap": "xs" },
+          "children": [
+            { "type": "text", "props": { "text": "$item.text", "role": "body" } }
+          ]
+        }
       ]
     }
   ]

package/lib/daemon.js

@@ -740,6 +740,7 @@ var relay = createServer({
       inheritGroups: config.inheritGroups !== false,
       chatLayout: config.chatLayout || "channel",
       matesEnabled: config.matesEnabled === true,
+      capsulesEnabled: config.capsulesEnabled === true,
       pinEnabled: !!config.pinHash,
       platform: process.platform,
       hostname: os2.hostname(),
@@ -818,6 +819,13 @@ var relay = createServer({
     console.log("[daemon] Project Mate DMs:", want ? "shown" : "hidden", "(web)");
     return { ok: true, matesEnabled: want };
   },
+  onSetCapsulesEnabled: function (value) {
+    var want = value === true;
+    config.capsulesEnabled = want;
+    saveConfig(config);
+    console.log("[daemon] Experimental Capsules:", want ? "enabled" : "disabled", "(web)");
+    return { ok: true, capsulesEnabled: want };
+  },
   onGetToolPalettes: function () {
     return config.toolPalettes || {};
   },

package/lib/migrate-single-user.js

@@ -23,6 +23,7 @@ var SETTING_KEYS = [
   "chatLayout",
   "autoContinueOnRateLimit",
   "matesEnabled",
+  "capsulesEnabled",
   "terminalFont",
   "deletedBuiltinKeys",
   "mateOnboardingShown",
@@ -189,6 +190,7 @@ function migrateSingleUserToMulti() {
       if (cfg.chatLayout !== undefined && users.setChatLayout) users.setChatLayout(userId, cfg.chatLayout);
       if (cfg.autoContinueOnRateLimit !== undefined && users.setAutoContinue) users.setAutoContinue(userId, cfg.autoContinueOnRateLimit);
       if (cfg.matesEnabled !== undefined && users.setMatesEnabled) users.setMatesEnabled(userId, cfg.matesEnabled);
+      if (cfg.capsulesEnabled !== undefined && users.setCapsulesEnabled) users.setCapsulesEnabled(userId, cfg.capsulesEnabled);
       if (cfg.terminalFont && users.setTerminalFont) {
         users.setTerminalFont(userId, cfg.terminalFont.family, cfg.terminalFont.size);
       }

package/lib/project-capsule-turn.js

@@ -0,0 +1,96 @@
+// Delivers a Capsule turn prompt into this Mate project.
+//
+// A Capsule game against a Mate needs the Mate to actually take its turns:
+// when Logic passes the turn to the mate seat, this module wakes the Mate
+// with a prompt telling it to snapshot the game and act. One session hosts
+// the whole game (found again by session.capsuleGame.toolId), so the user
+// watches a single running conversation of the Mate playing rather than a
+// new session per turn. The prompt is recorded as an internal user message,
+// the same shape the debate engine uses, so the transcript shows the nudge
+// without pretending the human typed it.
+//
+// This module only carries words to the Mate. Every actual game mutation the
+// Mate then makes goes through the same clay_tool_act pipeline as always.
+
+function attachCapsuleTurn(ctx) {
+  var sm = ctx.sm;
+
+  function ownsSession(session, principal) {
+    if (ctx.isMultiUser()) return !!principal.userId && session.ownerId === principal.userId;
+    return !session.ownerId;
+  }
+
+  function findGameSession(principal, toolId) {
+    var found = null;
+    sm.sessions.forEach(function (session) {
+      if (found || !session || session.hidden || session.destroying) return;
+      if (!session.capsuleGame || session.capsuleGame.toolId !== toolId) return;
+      if (!ownsSession(session, principal)) return;
+      found = session;
+    });
+    return found;
+  }
+
+  async function createGameSession(principal, options) {
+    var selection = await ctx.resolveModel(principal);
+    if (!selection || selection.status !== "ready" || !selection.vendor || !selection.model) {
+      throw new Error(selection && selection.error ? selection.error : "No configured model is available for the Mate.");
+    }
+    var create = typeof sm.createSessionRaw === "function" ? sm.createSessionRaw : sm.createSession;
+    var session = create.call(sm, {
+      ownerId: principal.userId || null,
+      vendor: selection.vendor,
+      model: selection.model,
+    });
+    session.title = (options.toolName || options.toolId) + " game";
+    session.capsuleGame = { toolId: options.toolId };
+    return session;
+  }
+
+  async function deliverCapsuleTurn(principal, options) {
+    if (!principal || !options || !options.toolId || !options.text) {
+      throw new Error("A bound owner, toolId, and turn text are required.");
+    }
+    var sdk = ctx.getSdk();
+    if (!sdk || typeof sdk.startQuery !== "function") throw new Error("Mate project runtime is unavailable.");
+    var session = findGameSession(principal, options.toolId);
+    var created = false;
+    if (!session) {
+      session = await createGameSession(principal, options);
+      created = true;
+    }
+    // Recorded as a dedicated event, not a user message: the transcript shows
+    // a short system note (see historyToHomeChat) instead of pretending the
+    // human typed the delivery prompt. The full prompt still reaches the
+    // model through the query below.
+    sm.sendAndRecord(session, {
+      type: "capsule_turn",
+      text: options.text,
+      toolId: options.toolId,
+      toolName: options.toolName || options.toolId,
+      kind: options.kind || "turn",
+    });
+    session.isProcessing = true;
+    session.lastActivity = Date.now();
+    sm.broadcastSessionList();
+    try {
+      var delivered = typeof sdk.pushMessage === "function" ? sdk.pushMessage(session, options.text) : false;
+      if (!delivered) await Promise.resolve(sdk.startQuery(session, options.text, undefined, ctx.getLinuxUserForSession(session)));
+    } catch (error) {
+      session.isProcessing = false;
+      sm.sendAndRecord(session, { type: "error", text: "Capsule turn could not start: " + (error && error.message ? error.message : String(error)) });
+      sm.broadcastSessionList();
+      throw error;
+    }
+    // The reference shape the home chat surface opens sessions by.
+    return {
+      session: session,
+      created: created,
+      reference: (typeof session.cliSessionId === "string" && session.cliSessionId) || "local:" + session.localId,
+    };
+  }
+
+  return { deliverCapsuleTurn: deliverCapsuleTurn };
+}
+
+module.exports = { attachCapsuleTurn: attachCapsuleTurn };

package/lib/project-logs-mcp-server.js

@@ -12,14 +12,15 @@ var logsSchema = require("./project-logs-schema");
 var logsComments = require("./project-logs-comments");
 
 var LOGS_CONTRACT =
-  "Project Logs are this project's durable record of decisions and work, written the way a good Git history reads. " +
+  "Project Logs are this project's durable work-continuity record, written so a newly created Driver can understand what the user asked for, what happened, and what remains without reading the previous chat. " +
   "You are the only author: connected people read the log and may add comments, but they cannot create or revise entries. That makes accuracy your responsibility. " +
-  "Write an entry when the project gains something worth knowing weeks from now: a decision and the reasoning behind it, a security finding, an investigation's outcome, an incident and its resolution, an operational runbook, a durable reference, or real progress. " +
-  "Every entry needs a concise meaningful title, a one or two sentence summary explaining what was decided or done and why, and a category. Set priority when an entry genuinely outranks routine work. " +
+  "Log every concrete user work instruction that changes, diagnoses, designs, or verifies project state, not only unusually important work. Create or identify one entry for the coherent task, then revise that same entry as work progresses instead of creating one entry per turn. " +
+  "The entry must preserve the user's requested outcome and material constraints, followed by what was changed, discovered, or decided, the affected area, verification, and the current result. If work is incomplete or blocked, state the remaining work and next action explicitly. For a small task, one completed entry is enough; for longer work, create it when the task starts and update it at meaningful milestones and completion. " +
+  "Every entry needs a concise meaningful title, a one or two sentence summary that combines the request with the current outcome, and a category. Set priority when an entry genuinely outranks routine work; routine work still belongs in the ledger at normal priority. " +
   "Categories are this project's own evolving vocabulary rather than a fixed list: list or search first, reuse an established category when one fits, and coin a new concise one only when the project needs a durable distinction it lacks. " +
   "Prefer updating an existing entry over creating a near-duplicate: when a decision supersedes an earlier one, revise that entry so its history shows the change. " +
-  "Do not log conversation summaries, task narration, restatements of the request, completed-work announcements, speculation, or anything the repository and its history already record. " +
-  "Every write is attributed and permanently revision-tracked, so keep entries short, concrete, and true.";
+  "Do not paste raw conversation transcripts, log command-by-command narration, trivial confirmations, or speculation. Repository history may show the code change but usually does not preserve the user's intent, constraints, verification, or unfinished state, so it is not a substitute for the work log. " +
+  "Every write is attributed and permanently revision-tracked, so keep entries concise, concrete, and true while retaining enough context for a clean Driver handoff.";
 
 // User learning moments are a durable project asset, so capturing them is a
 // default rather than an option. This category is about a change in the user's
@@ -75,7 +76,7 @@ var CATEGORY_DESCRIPTION = "Record category: a short lowercase hyphen-separated
   "Common starting points are " + logsSchema.SEED_CATEGORIES.join(", ") + ". A category is dry metadata, never a persona or an identifier. " +
   "Use `learning` only for a user learning moment described by the learning contract, never for knowledge or lessons acquired by the Driver.";
 var PRIORITY_DESCRIPTION = "How much this outranks routine work: " + logsSchema.PRIORITIES.join(", ") + ". Defaults to normal. Priority is independent of category, so an urgent decision is both.";
-var SUMMARY_DESCRIPTION = "One or two sentences explaining what was decided or done and why. This is what a reader sees in the ledger, so it must stand alone. For a learning entry, identify the concept the user engaged with plainly enough that the row itself teaches it.";
+var SUMMARY_DESCRIPTION = "One or two sentences combining the user's requested outcome with the current result or status. This is what a new Driver sees in the ledger, so it must stand alone. For a learning entry, identify the concept the user engaged with plainly enough that the row itself teaches it.";
 var REF_DESCRIPTION = "Opaque log reference returned by list_logs, search_logs, or create_log.";
 
 function textResult(value) {
@@ -148,27 +149,27 @@ function projectTools(bound) {
     },
     {
       name: "create_log",
-      description: LOGS_CONTRACT + " " + LEARNING_CONTRACT + " Create a log entry in this project. Apply the test first: will someone need this fact weeks from now, and is it not already recorded? If it supersedes an existing entry, revise that entry instead of adding a new one.",
+      description: LOGS_CONTRACT + " " + LEARNING_CONTRACT + " Create a log entry for a new coherent user-directed task or durable project record. Search first; if the task already has an entry, revise it instead of adding a duplicate.",
       inputSchema: buildShape({
         kind: { type: "string", description: CATEGORY_DESCRIPTION },
         priority: { type: "string", enum: logsSchema.PRIORITIES, description: PRIORITY_DESCRIPTION },
         title: { type: "string", description: "Short factual title, plain text, written like a good commit subject." },
         summary: { type: "string", description: SUMMARY_DESCRIPTION },
-        body: { type: "string", description: "The durable facts, context, and outcome in Markdown. No narration of your own activity. For a learning entry, cover the user's original wording or mental model, the precise concept, how it applies here, and any boundary or misconception." },
+        body: { type: "string", description: "The concise continuity record in Markdown: requested outcome and constraints, work/result, affected area, verification, current status, and next action when unfinished. Omit raw transcripts and command-by-command narration. For a learning entry, cover the user's original wording or mental model, the precise concept, how it applies here, and any boundary or misconception." },
         tags: { type: "string", description: "Optional JSON array of short tag strings." },
       }, ["kind", "title", "summary"]),
       handler: handler(bound, "createLog"),
     },
     {
       name: "update_log",
-      description: LOGS_CONTRACT + " " + LEARNING_CONTRACT + " Revise an existing log entry, including when a later decision supersedes it, or when new learning refines an existing learning entry. The previous revision, its title, and its summary are all retained in the entry history.",
+      description: LOGS_CONTRACT + " " + LEARNING_CONTRACT + " Revise the coherent task entry when work progresses, completes, becomes blocked, or a later decision supersedes it. Also revise when new learning refines an existing learning entry. The previous revision, its title, and its summary are all retained in the entry history.",
       inputSchema: buildShape({
         ref: { type: "string", description: REF_DESCRIPTION },
         kind: { type: "string", description: CATEGORY_DESCRIPTION },
         priority: { type: "string", enum: logsSchema.PRIORITIES, description: PRIORITY_DESCRIPTION },
         title: { type: "string", description: "Replacement title. The previous title stays in the entry's history." },
         summary: { type: "string", description: "Replacement summary. The previous summary stays in the entry's history." },
-        body: { type: "string", description: "Replacement record body in Markdown." },
+        body: { type: "string", description: "Replacement continuity record body in Markdown, including the request, current result, verification, and any remaining next action." },
         tags: { type: "string", description: "Optional JSON array of short tag strings, replacing the current tags." },
       }, ["ref"]),
       handler: handler(bound, "updateLog"),

package/lib/project-session-pair.js

@@ -3,7 +3,7 @@ var pairPrompts = require("./session-pair-prompts");
 var { attachPairFactory } = require("./session-pair-factory");
 var { attachPairLifecycle } = require("./project-pair-lifecycle");
 var { attachPairTurnControl } = require("./session-pair-turn-control");
-var driverEligibility = require("./session-driver-eligibility");
+var driverEligibility = require("./session-driver-eligibility"), driverOrchestration = require("./session-driver-orchestration");
 var { attachWorkerPermission } = require("./project-worker-permission");
 var { attachWorkerProposal } = require("./project-worker-proposal");
 var MAX_RESPONSE_CHARS = 30000;
@@ -372,7 +372,8 @@ function attachSessionPair(ctx) {
     if (group && group.pair && group.pair.driverId !== boundSession.localId) return [];
     var adHocSplit = !!(group && !group.pair);
     if (!driverEligibility.isEligibleDriverSession(boundSession, sm)) return [];
-    if (!group) {
+    var persistentCatalog = boundSession.vendor === "codex" && (!group || !!group.pair);
+    if (!group && !persistentCatalog) {
       return workerProposal.getToolDefs(boundSession)
         .concat(workerPermission.getToolDefs(boundSession, { dormantDriver: true }));
     }
@@ -393,7 +394,12 @@ function attachSessionPair(ctx) {
         });
       },
       evaluate: lifecycleHandlers.evaluate,
-    }, { lifecycle: !adHocSplit });
+    }, { lifecycle: persistentCatalog || !adHocSplit });
+    if (persistentCatalog) {
+      return workerProposal.getToolDefs(boundSession, { persistent: true })
+        .concat(tools)
+        .concat(workerPermission.getToolDefs(boundSession, { dormantDriver: true }));
+    }
     return tools
       .concat(workerPermission.getToolDefs(boundSession, { dormantDriver: false }));
   }
@@ -466,8 +472,12 @@ function attachSessionPair(ctx) {
     var group = store.groupForMember(session.localId);
     var pairPrompt = "";
     if (group && group.pair && group.pair.driverId === session.localId) {
-      pairPrompt = pairPrompts.DRIVER;
-    } else if (!group && !ctx.isMate && driverEligibility.isEligibleDriverSession(session, sm)) {
+      pairPrompt = pairPrompts.DRIVER_CORE;
+      if (driverOrchestration.isHighTierDriverSession(session, sm)) {
+        pairPrompt += " " + pairPrompts.DRIVER_DELEGATION;
+      }
+    } else if (!group && !ctx.isMate && driverEligibility.isEligibleDriverSession(session, sm) &&
+      driverOrchestration.isHighTierDriverSession(session, sm)) {
       pairPrompt = pairPrompts.UNPAIRED + " " + workerProposal.getSystemPrompt(session);
     }
     return pairPrompt;