@korso/shepherd 0.10.0 → 0.11.1

package/dist/index.js

@@ -481,7 +481,12 @@ var JoinRequest = z2.object({
 });
 var JoinResponse = z2.object({
   agentName: z2.string(),
-  sessionId: z2.string().uuid()
+  sessionId: z2.string().uuid(),
+  // Advertised so clients can nudge their humans to update. Optional: older
+  // hubs omit them, and a hub that cannot determine its bundled client
+  // version fails open by leaving them out.
+  latestClientVersion: z2.string().optional(),
+  minimumClientVersion: z2.string().optional()
 });
 var WorkRequest = z2.object({
   sessionId: z2.string().uuid(),
@@ -1368,6 +1373,81 @@ function defaultRunGitStatus(cwd) {
   });
 }
 
+// src/updateNudge.ts
+import { mkdirSync as mkdirSync3, readFileSync as readFileSync4, writeFileSync as writeFileSync4 } from "node:fs";
+import { dirname as dirname4 } from "node:path";
+var NUDGE_COOLDOWN_MS = 24 * 60 * 60 * 1e3;
+function parseVersion(v) {
+  const m = /^v?(\d+(?:\.\d+)*)/.exec(v.trim());
+  if (!m) return null;
+  return m[1].split(".").map(Number);
+}
+function compareVersions(a, b) {
+  const pa = parseVersion(a) ?? [];
+  const pb = parseVersion(b) ?? [];
+  const len = Math.max(pa.length, pb.length);
+  for (let i = 0; i < len; i++) {
+    const d = (pa[i] ?? 0) - (pb[i] ?? 0);
+    if (d !== 0) return d < 0 ? -1 : 1;
+  }
+  return 0;
+}
+function readStamp(stampFile) {
+  try {
+    const parsed = JSON.parse(readFileSync4(stampFile, "utf8"));
+    if (typeof parsed === "object" && parsed !== null && typeof parsed.latest === "string" && typeof parsed.at === "number") {
+      return parsed;
+    }
+  } catch {
+  }
+  return null;
+}
+function writeStamp(stampFile, stamp) {
+  try {
+    mkdirSync3(dirname4(stampFile), { recursive: true });
+    writeFileSync4(stampFile, JSON.stringify(stamp), "utf8");
+  } catch {
+  }
+}
+var SUGGEST = "Let your human know, and suggest the update command that matches how Shepherd is installed on this machine (global npm, an npx cache, a version manager, \u2026).";
+function maybeUpdateNudge(opts) {
+  const now = opts.nowMs ?? Date.now();
+  if (!parseVersion(opts.current)) return "";
+  const latest = opts.latest !== void 0 && parseVersion(opts.latest) ? opts.latest : void 0;
+  const minimum = opts.minimum !== void 0 && parseVersion(opts.minimum) ? opts.minimum : void 0;
+  const belowMinimum = minimum !== void 0 && compareVersions(opts.current, minimum) < 0;
+  const behind = latest !== void 0 && compareVersions(opts.current, latest) < 0;
+  if (!belowMinimum && !behind) return "";
+  if (!belowMinimum) {
+    const stamp = readStamp(opts.stampFile);
+    if (stamp !== null && compareVersions(latest, stamp.latest) <= 0 && now - stamp.at < NUDGE_COOLDOWN_MS) {
+      return "";
+    }
+  }
+  writeStamp(opts.stampFile, { latest: latest ?? opts.current, at: now });
+  if (belowMinimum) {
+    const latestPart = latest !== void 0 ? ` (latest: ${latest})` : "";
+    return `[shepherd] This client (${opts.current}) is below the minimum supported version ${minimum}${latestPart} \u2014 coordination may misbehave until it is updated. ${SUGGEST}`;
+  }
+  return `[shepherd] Update available: @korso/shepherd ${latest} (this machine runs ${opts.current}). ${SUGGEST}`;
+}
+
+// src/version.ts
+import { createRequire } from "node:module";
+var PACKAGE_VERSION = (() => {
+  try {
+    const req = createRequire(import.meta.url);
+    const pkg = req("../package.json");
+    return pkg.version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+})();
+
+// src/tools.ts
+import { homedir as homedir3 } from "node:os";
+import nodePath from "node:path";
+
 // src/linkPopup.ts
 var NEVER_ASK_CHOICE = "No \u2014 don't ask again";
 async function offerLinkPopup({
@@ -1582,6 +1662,33 @@ function registerTools(server, deps) {
   const { hubClient, config, context, heartbeat, inboxFile } = deps;
   const markerCwd = deps.cwd ?? process.cwd();
   const declinedDir = deps.declinedDir;
+  const updateNudge = deps.updateNudge ?? ((versions) => maybeUpdateNudge({
+    current: PACKAGE_VERSION,
+    latest: versions.latest,
+    minimum: versions.minimum,
+    stampFile: nodePath.join(homedir3(), ".shepherd", "update-nudge.json")
+  }));
+  let latestClientVersion;
+  let minimumClientVersion;
+  let nudgeDelivered = false;
+  function withUpdateNudge(text) {
+    if (nudgeDelivered) return text;
+    if (latestClientVersion === void 0 && minimumClientVersion === void 0) {
+      return text;
+    }
+    nudgeDelivered = true;
+    let nudge = "";
+    try {
+      nudge = updateNudge({
+        latest: latestClientVersion,
+        minimum: minimumClientVersion
+      });
+    } catch {
+    }
+    return nudge ? `${text}
+
+${nudge}` : text;
+  }
   const repoRoot = findRepoRoot(markerCwd);
   let sessionId = null;
   let agentName = null;
@@ -1616,8 +1723,12 @@ function registerTools(server, deps) {
     syncToolSurface();
   }
   let joinFailure = null;
+  let joinFailureTransient = false;
+  let targetWorkspaceSlug = null;
+  let gateRetry = null;
   let joinInFlight = Promise.resolve();
   async function activate(workspaceSlug) {
+    targetWorkspaceSlug = workspaceSlug;
     if (sessionId !== null && activeWorkspaceSlug === workspaceSlug) {
       return { ok: true };
     }
@@ -1637,6 +1748,7 @@ function registerTools(server, deps) {
         const parsed = JoinResponse.safeParse(raw);
         if (!parsed.success || !parsed.data.sessionId) {
           joinFailure = "validation";
+          joinFailureTransient = false;
           console.error(
             "[shepherd] join failed (validation): hub returned a malformed join response (no usable sessionId)"
           );
@@ -1646,14 +1758,18 @@ function registerTools(server, deps) {
         heartbeat.start(newSessionId);
         sessionId = newSessionId;
         agentName = parsed.data.agentName;
+        latestClientVersion = parsed.data.latestClientVersion;
+        minimumClientVersion = parsed.data.minimumClientVersion;
         activeWorkspaceSlug = workspaceSlug;
         linked = true;
         hostedWorkspaceRejected = false;
         joinFailure = null;
+        joinFailureTransient = false;
         return { ok: true };
       } catch (err) {
         const reason = classifyActivateFailure(err);
         joinFailure = classifyJoinFailure(err);
+        joinFailureTransient = err instanceof HubUnreachable || err instanceof HubRequestError && reason === "unknown";
         if (reason === "workspaceRejected") {
           hostedWorkspaceRejected = true;
           console.error(
@@ -1714,6 +1830,13 @@ function registerTools(server, deps) {
     await awaitJoin();
     if (!linked) return notLinked();
     if (selfHostMismatch || hostedWorkspaceRejected) return workspaceMismatch();
+    if (sessionId === null && targetWorkspaceSlug !== null && joinFailureTransient) {
+      gateRetry ??= activate(targetWorkspaceSlug).finally(() => {
+        gateRetry = null;
+      });
+      await gateRetry;
+      if (hostedWorkspaceRejected) return workspaceMismatch();
+    }
     if (sessionId === null) return sessionNotReady();
     return null;
   }
@@ -1787,7 +1910,7 @@ ${section}` : body;
 You hold this claim until you call done (workItemId: ${result.workItemId}) or it expires (~60 min). Calling work or sync renews it.`
           )
         );
-        return { content: [{ type: "text", text }] };
+        return { content: [{ type: "text", text: withUpdateNudge(text) }] };
       } catch (err) {
         if (err instanceof HubUnreachable || err instanceof HubRequestError) {
           return degradedResult(err);
@@ -1818,9 +1941,14 @@ You hold this claim until you call done (workItemId: ${result.workItemId}) or it
           mergeAnnouncements(result.announcements, drainLocalInbox())
         );
         return {
-          content: [{ type: "text", text: msgs ? `${base}
+          content: [
+            {
+              type: "text",
+              text: withUpdateNudge(msgs ? `${base}
 
-${msgs}` : base }]
+${msgs}` : base)
+            }
+          ]
         };
       } catch (err) {
         if (err instanceof HubUnreachable || err instanceof HubRequestError) {
@@ -1852,9 +1980,14 @@ ${msgs}` : base }]
           mergeAnnouncements(result.announcements, drainLocalInbox())
         );
         return {
-          content: [{ type: "text", text: msgs ? `${base}
+          content: [
+            {
+              type: "text",
+              text: withUpdateNudge(msgs ? `${base}
 
-${msgs}` : base }]
+${msgs}` : base)
+            }
+          ]
         };
       } catch (err) {
         if (err instanceof HubUnreachable || err instanceof HubRequestError) {
@@ -1892,7 +2025,7 @@ ${msgs}` : base }]
             formatLandscape(result.landscape)
           )
         );
-        return { content: [{ type: "text", text }] };
+        return { content: [{ type: "text", text: withUpdateNudge(text) }] };
       } catch (err) {
         if (err instanceof HubUnreachable || err instanceof HubRequestError) {
           return degradedResult(err);
@@ -2100,13 +2233,13 @@ function postLinkGuidance(workspace) {
 }
 
 // src/identityCache.ts
-import { mkdirSync as mkdirSync3, readFileSync as readFileSync4, writeFileSync as writeFileSync4 } from "node:fs";
-import { homedir as homedir3, tmpdir as tmpdir3 } from "node:os";
-import { dirname as dirname4, join as join4 } from "node:path";
+import { mkdirSync as mkdirSync4, readFileSync as readFileSync5, writeFileSync as writeFileSync5 } from "node:fs";
+import { homedir as homedir4, tmpdir as tmpdir3 } from "node:os";
+import { dirname as dirname5, join as join4 } from "node:path";
 function defaultIdentityCachePath() {
   let base = "";
   try {
-    base = homedir3();
+    base = homedir4();
   } catch {
     base = "";
   }
@@ -2116,7 +2249,7 @@ function defaultIdentityCachePath() {
 function readCachedHuman(filePath = defaultIdentityCachePath()) {
   let raw;
   try {
-    raw = readFileSync4(filePath, "utf8");
+    raw = readFileSync5(filePath, "utf8");
   } catch {
     return null;
   }
@@ -2131,9 +2264,9 @@ function readCachedHuman(filePath = defaultIdentityCachePath()) {
 function writeCachedHuman(human, filePath = defaultIdentityCachePath()) {
   if (typeof human !== "string" || human.trim().length === 0) return;
   try {
-    mkdirSync3(dirname4(filePath), { recursive: true });
+    mkdirSync4(dirname5(filePath), { recursive: true });
     const payload = JSON.stringify({ human });
-    writeFileSync4(filePath, payload + "\n", "utf8");
+    writeFileSync5(filePath, payload + "\n", "utf8");
   } catch {
   }
 }
@@ -2397,30 +2530,16 @@ async function ancestorChain(maxDepth = 32, snapshot = snapshotParentMap) {
 
 // src/hookInstall.ts
 import {
-  readFileSync as readFileSync5,
-  writeFileSync as writeFileSync5,
-  mkdirSync as mkdirSync4,
+  readFileSync as readFileSync6,
+  writeFileSync as writeFileSync6,
+  mkdirSync as mkdirSync5,
   copyFileSync,
   existsSync as existsSync4,
   renameSync as renameSync2
 } from "node:fs";
-import { homedir as homedir4 } from "node:os";
-import { dirname as dirname5, join as join5 } from "node:path";
+import { homedir as homedir5 } from "node:os";
+import { dirname as dirname6, join as join5 } from "node:path";
 import { fileURLToPath } from "node:url";
-
-// src/version.ts
-import { createRequire } from "node:module";
-var PACKAGE_VERSION = (() => {
-  try {
-    const req = createRequire(import.meta.url);
-    const pkg = req("../package.json");
-    return pkg.version ?? "0.0.0";
-  } catch {
-    return "0.0.0";
-  }
-})();
-
-// src/hookInstall.ts
 function detectClient(clientName) {
   const name = (clientName ?? "").toLowerCase();
   if (!name) return "unknown";
@@ -2433,16 +2552,16 @@ function detectClient(clientName) {
 var HOOK_COMMAND = `npx -y --package=@korso/shepherd@${PACKAGE_VERSION} shepherd-inbox-hook`;
 var HOOK_MARKER = "shepherd-inbox-hook";
 function ensureHookScript(homeDir, hookScriptSource) {
-  const source = hookScriptSource ?? join5(dirname5(fileURLToPath(import.meta.url)), "inboxHook.js");
+  const source = hookScriptSource ?? join5(dirname6(fileURLToPath(import.meta.url)), "inboxHook.js");
   try {
     if (!existsSync4(source)) return null;
     const dest = join5(homeDir, ".shepherd", "hooks", "shepherd-inbox-hook.mjs");
-    const next = readFileSync5(source);
-    const current = existsSync4(dest) ? readFileSync5(dest) : null;
+    const next = readFileSync6(source);
+    const current = existsSync4(dest) ? readFileSync6(dest) : null;
     if (current === null || !current.equals(next)) {
-      mkdirSync4(dirname5(dest), { recursive: true });
+      mkdirSync5(dirname6(dest), { recursive: true });
       const tmp = dest + ".tmp";
-      writeFileSync5(tmp, next);
+      writeFileSync6(tmp, next);
       renameSync2(tmp, dest);
     }
     return dest;
@@ -2465,7 +2584,7 @@ function codexHookBlock(scriptPath) {
 }
 async function autoInstallHooks({
   clientName,
-  homeDir = homedir4(),
+  homeDir = homedir5(),
   disabled = false,
   extensionSource,
   hookScriptSource,
@@ -2490,8 +2609,8 @@ async function autoInstallHooks({
     } else {
       status = installPi(homeDir, extensionSource, log);
     }
-    mkdirSync4(dirname5(recordFile), { recursive: true });
-    writeFileSync5(
+    mkdirSync5(dirname6(recordFile), { recursive: true });
+    writeFileSync6(
       recordFile,
       JSON.stringify({ status, at: (/* @__PURE__ */ new Date()).toISOString() }, null, 2) + "\n",
       "utf8"
@@ -2513,7 +2632,7 @@ function installClaude(homeDir, scriptPath, log) {
   const settingsFile = join5(homeDir, ".claude", "settings.json");
   let raw = "";
   if (existsSync4(settingsFile)) {
-    raw = readFileSync5(settingsFile, "utf8");
+    raw = readFileSync6(settingsFile, "utf8");
     if (raw.includes(HOOK_MARKER)) return "already-present";
   }
   let settings = {};
@@ -2556,8 +2675,8 @@ function installClaude(homeDir, scriptPath, log) {
     matcher: "*",
     hooks: [{ type: "command", command }]
   });
-  mkdirSync4(dirname5(settingsFile), { recursive: true });
-  writeFileSync5(settingsFile, JSON.stringify(settings, null, 2) + "\n", "utf8");
+  mkdirSync5(dirname6(settingsFile), { recursive: true });
+  writeFileSync6(settingsFile, JSON.stringify(settings, null, 2) + "\n", "utf8");
   return "installed";
 }
 function installCodex(homeDir, scriptPath, log) {
@@ -2565,13 +2684,13 @@ function installCodex(homeDir, scriptPath, log) {
   const manualHint = "Add the hook manually (see the dashboard's Connect screen).";
   const hookBlock = codexHookBlock(scriptPath);
   if (!existsSync4(configFile)) {
-    mkdirSync4(dirname5(configFile), { recursive: true });
-    writeFileSync5(configFile, `[features]
+    mkdirSync5(dirname6(configFile), { recursive: true });
+    writeFileSync6(configFile, `[features]
 hooks = true
 ${hookBlock}`, "utf8");
     return "installed";
   }
-  const toml = readFileSync5(configFile, "utf8");
+  const toml = readFileSync6(configFile, "utf8");
   if (toml.includes(HOOK_MARKER)) return "already-present";
   if (/^\s*\[hooks\.UserPromptSubmit\]\s*$/m.test(toml)) {
     log(
@@ -2592,10 +2711,10 @@ ${hookBlock}`, "utf8");
       updated = toml.replace(/^(\s*\[features\]\s*)$/m, `$1
 hooks = true`);
     }
-    writeFileSync5(configFile, updated + hookBlock, "utf8");
+    writeFileSync6(configFile, updated + hookBlock, "utf8");
     return "installed";
   }
-  writeFileSync5(
+  writeFileSync6(
     configFile,
     `${toml}
 [features]
@@ -2609,7 +2728,7 @@ function installCursor(homeDir, scriptPath, log) {
   const hooksFile = join5(homeDir, ".cursor", "hooks.json");
   let raw = "";
   if (existsSync4(hooksFile)) {
-    raw = readFileSync5(hooksFile, "utf8");
+    raw = readFileSync6(hooksFile, "utf8");
     if (raw.includes(HOOK_MARKER)) return "already-present";
   }
   let config = {};
@@ -2644,12 +2763,12 @@ function installCursor(homeDir, scriptPath, log) {
     return "skipped";
   }
   entries.push({ command: hookCommandFor(scriptPath) });
-  mkdirSync4(dirname5(hooksFile), { recursive: true });
-  writeFileSync5(hooksFile, JSON.stringify(config, null, 2) + "\n", "utf8");
+  mkdirSync5(dirname6(hooksFile), { recursive: true });
+  writeFileSync6(hooksFile, JSON.stringify(config, null, 2) + "\n", "utf8");
   return "installed";
 }
 function installPi(homeDir, extensionSource, log) {
-  const source = extensionSource ?? join5(dirname5(fileURLToPath(import.meta.url)), "inboxExtension.js");
+  const source = extensionSource ?? join5(dirname6(fileURLToPath(import.meta.url)), "inboxExtension.js");
   const dest = join5(homeDir, ".pi", "agent", "extensions", "shepherd-inbox.js");
   if (existsSync4(dest)) return "already-present";
   if (!existsSync4(source)) {
@@ -2658,7 +2777,7 @@ function installPi(homeDir, extensionSource, log) {
     );
     return "skipped";
   }
-  mkdirSync4(dirname5(dest), { recursive: true });
+  mkdirSync5(dirname6(dest), { recursive: true });
   copyFileSync(source, dest);
   return "installed";
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@korso/shepherd",
-  "version": "0.10.0",
+  "version": "0.11.1",
   "description": "Shepherd MCP server — gives any MCP-capable agent (Claude Code, Codex, etc.) advisory cross-session coordination tools (work/done/announce/sync, plus link/unlink/decline) backed by the shared Shepherd hub. Joins the workspace automatically and ships standing instructions so the agent self-coordinates.",
   "homepage": "https://github.com/Korso-AI/shepherd#readme",
   "bugs": {