@korso/shepherd 0.5.0 → 0.6.0

package/dist/index.js

@@ -558,15 +558,25 @@ var ListTokensResponse = z2.object({
 });
 var CreateInviteRequest = z2.object({
   expiresInDays: z2.number().int().positive().optional(),
+  // Omitted = unlimited, redeemable until explicitly revoked. Pass a positive
+  // integer to cap it instead.
   maxUses: z2.number().int().positive().optional()
 });
 var InviteResponse = z2.object({
   code: z2.string(),
   // ISO timestamp string, or null when the invite never expires.
   expiresAt: IsoTimestamp.nullable(),
-  maxUses: z2.number().int().positive(),
+  // null = unlimited (redeemable until revoked).
+  maxUses: z2.number().int().positive().nullable(),
   useCount: z2.number().int().nonnegative()
 });
+var InviteByEmailRequest = z2.object({
+  email: z2.string().email()
+});
+var InviteByEmailResponse = z2.object({
+  email: z2.string(),
+  sentAt: IsoTimestamp
+});
 var RedeemInviteResponse = z2.object({
   // The workspace the caller just joined.
   workspace: WorkspaceSummary
@@ -581,6 +591,16 @@ var MemberSummary = z2.object({
 var ListMembersResponse = z2.object({
   members: z2.array(MemberSummary)
 });
+var FeedbackType = z2.enum(["bug", "suggestion", "other"]);
+var FeedbackRequest = z2.object({
+  type: FeedbackType,
+  body: z2.string().trim().min(1).max(4e3)
+});
+var FeedbackResponse = z2.object({
+  ok: z2.literal(true),
+  // uuid PK (the feedback table, like workspaces, uses gen_random_uuid()).
+  id: z2.string()
+});
 
 // src/marker.ts
 import * as fs from "fs";
@@ -634,6 +654,66 @@ function removeMarker(cwd = process.cwd()) {
   }
 }
 
+// src/declined.ts
+import { createHash } from "crypto";
+import { existsSync as existsSync2, mkdirSync, readFileSync as readFileSync2, rmSync as rmSync2, writeFileSync as writeFileSync2 } from "fs";
+import { homedir, tmpdir } from "os";
+import { dirname as dirname2, join as join2, resolve as resolve2 } from "path";
+function defaultDeclinedDir() {
+  let base = "";
+  try {
+    base = homedir();
+  } catch {
+    base = "";
+  }
+  if (!base) base = tmpdir();
+  return join2(base, ".shepherd", "declined");
+}
+function declinedFilePath(repoRoot, dir = defaultDeclinedDir()) {
+  let normalized = resolve2(repoRoot);
+  if (process.platform === "win32") normalized = normalized.toLowerCase();
+  const hash = createHash("sha256").update(normalized).digest("hex").slice(0, 16);
+  return join2(dir, hash);
+}
+function isDeclined(repoRoot, dir = defaultDeclinedDir()) {
+  const file = declinedFilePath(repoRoot, dir);
+  let raw;
+  try {
+    raw = readFileSync2(file, "utf8");
+  } catch {
+    return false;
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    return typeof parsed?.declinedAt === "string";
+  } catch {
+    return false;
+  }
+}
+function setDeclined(repoRoot, dir = defaultDeclinedDir()) {
+  const file = declinedFilePath(repoRoot, dir);
+  try {
+    mkdirSync(dirname2(file), { recursive: true });
+    const payload = JSON.stringify({ declinedAt: (/* @__PURE__ */ new Date()).toISOString() });
+    writeFileSync2(file, payload + "\n", "utf8");
+  } catch (err) {
+    console.error(
+      `[shepherd] declined-state write failed: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+}
+function clearDeclined(repoRoot, dir = defaultDeclinedDir()) {
+  const file = declinedFilePath(repoRoot, dir);
+  if (!existsSync2(file)) return;
+  try {
+    rmSync2(file, { force: true });
+  } catch (err) {
+    console.error(
+      `[shepherd] declined-state clear failed: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+}
+
 // src/gitContext.ts
 import { execFileSync } from "child_process";
 import * as path2 from "path";
@@ -879,37 +959,37 @@ async function buildChangeReport(cwd, config) {
 }
 
 // src/inbox.ts
-import { createHash } from "crypto";
+import { createHash as createHash2 } from "crypto";
 import {
   appendFileSync,
-  mkdirSync,
-  readFileSync as readFileSync2,
+  mkdirSync as mkdirSync2,
+  readFileSync as readFileSync3,
   renameSync,
-  rmSync as rmSync2,
-  existsSync as existsSync2
+  rmSync as rmSync3,
+  existsSync as existsSync3
 } from "fs";
-import { homedir, tmpdir } from "os";
-import { dirname as dirname2, join as join2, resolve as resolve2 } from "path";
+import { homedir as homedir2, tmpdir as tmpdir2 } from "os";
+import { dirname as dirname3, join as join3, resolve as resolve3 } from "path";
 function defaultInboxDir() {
   let base = "";
   try {
-    base = homedir();
+    base = homedir2();
   } catch {
     base = "";
   }
-  if (!base) base = tmpdir();
-  return join2(base, ".shepherd", "inbox");
+  if (!base) base = tmpdir2();
+  return join3(base, ".shepherd", "inbox");
 }
 function inboxFilePath(dir, cwd) {
-  let normalized = resolve2(cwd);
+  let normalized = resolve3(cwd);
   if (process.platform === "win32") normalized = normalized.toLowerCase();
-  const hash = createHash("sha256").update(normalized).digest("hex").slice(0, 16);
-  return join2(dir, `${hash}.jsonl`);
+  const hash = createHash2("sha256").update(normalized).digest("hex").slice(0, 16);
+  return join3(dir, `${hash}.jsonl`);
 }
 function appendAnnouncements(filePath, announcements) {
   if (!announcements || announcements.length === 0) return;
   try {
-    mkdirSync(dirname2(filePath), { recursive: true });
+    mkdirSync2(dirname3(filePath), { recursive: true });
     const payload = announcements.map((a) => JSON.stringify(a)).join("\n") + "\n";
     appendFileSync(filePath, payload, "utf8");
   } catch {
@@ -919,17 +999,17 @@ function drainInbox(filePath) {
   const tmp = `${filePath}.draining`;
   let raw = "";
   try {
-    if (existsSync2(tmp)) {
-      raw += readFileSync2(tmp, "utf8");
-      rmSync2(tmp, { force: true });
+    if (existsSync3(tmp)) {
+      raw += readFileSync3(tmp, "utf8");
+      rmSync3(tmp, { force: true });
     }
   } catch {
   }
   try {
-    if (existsSync2(filePath)) {
+    if (existsSync3(filePath)) {
       renameSync(filePath, tmp);
-      raw += readFileSync2(tmp, "utf8");
-      rmSync2(tmp, { force: true });
+      raw += readFileSync3(tmp, "utf8");
+      rmSync3(tmp, { force: true });
     }
   } catch {
   }
@@ -970,6 +1050,12 @@ function classifyJoinFailure(err) {
   }
   return "unknown";
 }
+function classifyActivateFailure(err) {
+  if (err instanceof HubRequestError && (err.status === 403 || err.status === 404)) {
+    return "workspaceRejected";
+  }
+  return classifyJoinFailure(err);
+}
 function joinFailureCause(reason) {
   switch (reason) {
     case "unreachable":
@@ -1107,57 +1193,88 @@ function degradedResult(err) {
 function registerTools(server, deps) {
   const { hubClient, config, context, heartbeat, inboxFile } = deps;
   const markerCwd = deps.cwd ?? process.cwd();
+  const declinedDir = deps.declinedDir;
+  const repoRoot = findRepoRoot(markerCwd);
   let sessionId = null;
   let agentName = null;
   const isHosted = Boolean(config.SHEPHERD_TOKEN);
   const selfHostMismatch = !isHosted && context.linked && config.WORKSPACE !== void 0 && config.WORKSPACE !== context.workspace;
   let hostedWorkspaceRejected = false;
   const dormant = !context.linked || selfHostMismatch;
+  let linked = context.linked;
+  let declined = context.declined;
+  function rememberDecline() {
+    if (repoRoot !== null) setDeclined(repoRoot, declinedDir);
+    declined = true;
+  }
+  function forgetDecline() {
+    if (repoRoot !== null) clearDeclined(repoRoot, declinedDir);
+    declined = false;
+  }
   let joinFailure = null;
-  const joinBody = {
-    workspace: context.workspace,
-    repo: context.repo,
-    branch: context.branch,
-    human: context.human,
-    program: context.program
-  };
-  if (context.model !== void 0) {
-    joinBody.model = context.model;
+  let joinInFlight = Promise.resolve();
+  async function activate(workspaceSlug) {
+    const joinBody = {
+      workspace: workspaceSlug,
+      repo: context.repo,
+      branch: context.branch,
+      human: context.human,
+      program: context.program
+    };
+    if (context.model !== void 0) {
+      joinBody.model = context.model;
+    }
+    const attempt = (async () => {
+      try {
+        const raw = await hubClient.post("/join", joinBody);
+        const parsed = JoinResponse.safeParse(raw);
+        if (!parsed.success || !parsed.data.sessionId) {
+          joinFailure = "validation";
+          console.error(
+            "[shepherd] join failed (validation): hub returned a malformed join response (no usable sessionId)"
+          );
+          return { ok: false, reason: "validation" };
+        }
+        const newSessionId = parsed.data.sessionId;
+        heartbeat.start(newSessionId);
+        sessionId = newSessionId;
+        agentName = parsed.data.agentName;
+        linked = true;
+        hostedWorkspaceRejected = false;
+        joinFailure = null;
+        return { ok: true };
+      } catch (err) {
+        const reason = classifyActivateFailure(err);
+        joinFailure = classifyJoinFailure(err);
+        if (reason === "workspaceRejected") {
+          hostedWorkspaceRejected = true;
+          console.error(
+            `[shepherd] This repo is linked to workspace "${workspaceSlug}" but your configured token is for a different workspace \u2014 coordination disabled.`
+          );
+        } else {
+          console.error(
+            `[shepherd] join failed (${reason}): ${err instanceof Error ? err.message : String(err)}`
+          );
+        }
+        return { ok: false, reason };
+      }
+    })();
+    joinInFlight = attempt.then(() => void 0);
+    return attempt;
   }
   if (!context.linked) {
     console.error(
-      "[shepherd] This repo isn't linked to a Shepherd workspace \u2014 staying uncoordinated. Run `link` to choose one."
+      context.declined ? "[shepherd] This repo was declined \u2014 staying uncoordinated. Run `link` to change your mind." : "[shepherd] This repo isn't linked to a Shepherd workspace \u2014 staying uncoordinated. Run `link` to choose one."
     );
   } else if (selfHostMismatch) {
     console.error(
       `[shepherd] This repo is linked to workspace "${context.workspace}" but your configured token is for a different workspace \u2014 coordination disabled.`
     );
   }
-  const joinInFlight = dormant ? Promise.resolve() : hubClient.post("/join", joinBody).then((raw) => {
-    const parsed = JoinResponse.safeParse(raw);
-    if (!parsed.success || !parsed.data.sessionId) {
-      joinFailure = "validation";
-      console.error(
-        "[shepherd] join failed (validation): hub returned a malformed join response (no usable sessionId)"
-      );
-      return;
-    }
-    sessionId = parsed.data.sessionId;
-    agentName = parsed.data.agentName;
-    heartbeat.start(parsed.data.sessionId);
-  }).catch((err) => {
-    joinFailure = classifyJoinFailure(err);
-    if (err instanceof HubRequestError && (err.status === 403 || err.status === 404)) {
-      hostedWorkspaceRejected = true;
-      console.error(
-        `[shepherd] This repo is linked to workspace "${context.workspace}" but your configured token is for a different workspace \u2014 coordination disabled.`
-      );
-    } else {
-      console.error(
-        `[shepherd] join failed (${joinFailure}): ${err instanceof Error ? err.message : String(err)}`
-      );
-    }
-  });
+  if (!dormant) {
+    forgetDecline();
+    void activate(context.workspace);
+  }
   async function awaitJoin() {
     await joinInFlight;
   }
@@ -1172,14 +1289,8 @@ function registerTools(server, deps) {
     };
   }
   function notLinked() {
-    return {
-      content: [
-        {
-          type: "text",
-          text: "This repo isn't linked to a Shepherd workspace \u2014 run `link` to choose one, or ignore to stay uncoordinated."
-        }
-      ]
-    };
+    const text = declined ? "Not coordinating this repo \u2014 you declined. Run `link` anytime to change your mind." : "This repo isn't linked to a Shepherd workspace \u2014 run `link` to choose one, or `decline` to stay uncoordinated and not be asked again.";
+    return { content: [{ type: "text", text }] };
   }
   function workspaceMismatch() {
     return {
@@ -1193,7 +1304,7 @@ function registerTools(server, deps) {
   }
   async function coordinationGate() {
     await awaitJoin();
-    if (!context.linked) return notLinked();
+    if (!linked) return notLinked();
     if (selfHostMismatch || hostedWorkspaceRejected) return workspaceMismatch();
     if (sessionId === null) return sessionNotReady();
     return null;
@@ -1363,13 +1474,25 @@ ${msgs}` : base }
   function advisory(text) {
     return { content: [{ type: "text", text }] };
   }
+  async function linkAndActivate(slug) {
+    writeMarker(markerCwd, slug);
+    forgetDecline();
+    linked = true;
+    const result = await activate(slug);
+    if (result.ok) {
+      return advisory(`Linked this repo to \`${slug}\` \u2014 coordinating in \`${slug}\` now.`);
+    }
+    return advisory(
+      `Linked this repo to \`${slug}\`, but coordination couldn't start just now (${joinFailureCause(joinFailure)}). It'll connect on your next tool call or session.`
+    );
+  }
   server.registerTool(
     "link",
     {
       title: "Link this repo to a Shepherd workspace",
-      description: "Opt this repository into Shepherd coordination by writing a committed `.shepherd` marker naming the workspace. Call with no argument to see the workspaces you can link to, then call again with one. You can only link to a workspace you are a member of. Takes effect on the next session (restart to coordinate now). Use `unlink` to opt out.",
+      description: "Opt this repository into Shepherd coordination by writing a committed `.shepherd` marker naming the workspace. Call with no argument: if you belong to exactly one workspace it is linked and coordination starts immediately; if you belong to several, the choices are listed for you to confirm one with the agent's user, then call `link` again with that `workspace`. You can only link to a workspace you are a member of. Takes effect immediately \u2014 no restart. Use `unlink` to opt out, or `decline` to stay uncoordinated without linking.",
       inputSchema: z3.object({
-        workspace: z3.string().min(1).optional().describe("The workspace slug to link this repo to. Omit to list your choices.")
+        workspace: z3.string().min(1).optional().describe("The workspace slug to link this repo to. Omit to auto-pick or list choices.")
       }).shape
     },
     async (args) => {
@@ -1381,21 +1504,12 @@ ${msgs}` : base }
             "Self-host mode has no configured workspace (WORKSPACE is unset) \u2014 cannot link."
           );
         }
-        if (requested === void 0) {
-          return advisory(
-            `This is a self-host deployment with a single workspace: \`${allowed}\`.
-Run \`link\` again with workspace "${allowed}" to opt this repo in.`
-          );
-        }
-        if (requested !== allowed) {
+        if (requested !== void 0 && requested !== allowed) {
           return advisory(
             `This self-host deployment only serves the workspace \`${allowed}\`; you asked for \`${requested}\`. Choose: ${allowed}`
           );
         }
-        writeMarker(markerCwd, allowed);
-        return advisory(
-          `Linked this repo to \`${allowed}\` \u2014 restart the session for it to take effect (it applies on the next launch).`
-        );
+        return linkAndActivate(allowed);
       }
       let slugs;
       try {
@@ -1409,12 +1523,15 @@ Run \`link\` again with workspace "${allowed}" to opt this repo in.`
       }
       if (slugs.length === 0) {
         return advisory(
-          "Your account isn't a member of any workspaces yet \u2014 nothing to link to. Create or join a workspace first, then run `link` again."
+          "Your account isn't a member of any workspaces yet \u2014 nothing to link to. Create one in the Shepherd dashboard, then run `link` again."
         );
       }
       if (requested === void 0) {
+        if (slugs.length === 1) {
+          return linkAndActivate(slugs[0]);
+        }
         return advisory(
-          "You can link this repo to one of these workspaces:\n" + slugs.map((s) => `  - ${s}`).join("\n") + "\n\nRun `link` again with one of them as the `workspace` argument."
+          "You're a member of multiple Shepherd workspaces:\n" + slugs.map((s) => `  - ${s}`).join("\n") + "\n\nAsk the user which one to use for this repo, then call `link` again with it as the `workspace` argument."
         );
       }
       if (!slugs.includes(requested)) {
@@ -1422,23 +1539,47 @@ Run \`link\` again with workspace "${allowed}" to opt this repo in.`
           `You're not a member of \`${requested}\`; choose one of: ${slugs.join(", ")}`
         );
       }
-      writeMarker(markerCwd, requested);
-      return advisory(
-        `Linked this repo to \`${requested}\` \u2014 restart the session for it to take effect (it applies on the next launch).`
-      );
+      return linkAndActivate(requested);
     }
   );
   server.registerTool(
     "unlink",
     {
       title: "Unlink this repo from its Shepherd workspace",
-      description: "Opt this repository OUT of Shepherd coordination by removing its `.shepherd` marker. The repo stays uncoordinated (no claims, no presence) until you `link` it again.",
+      description: "Opt this repository OUT of Shepherd coordination by removing its `.shepherd` marker. Also records a local decline so you aren't re-prompted to link on the next session. The repo stays uncoordinated (no claims, no presence) until you `link` it again.",
       inputSchema: z3.object({}).shape
     },
     async () => {
       removeMarker(markerCwd);
+      rememberDecline();
+      linked = false;
+      if (sessionId !== null) {
+        heartbeat.stop();
+        await leave();
+        sessionId = null;
+        agentName = null;
+      }
       return advisory(
-        "Unlinked \u2014 this repo will stay uncoordinated until re-linked."
+        "Unlinked \u2014 this repo will stay uncoordinated and won't ask again. Run `link` to re-enable."
+      );
+    }
+  );
+  server.registerTool(
+    "decline",
+    {
+      title: "Decline Shepherd coordination for this repo",
+      description: "Opt out of Shepherd for this repo WITHOUT linking: records a local, per-user 'don't ask again' so this repo stays uncoordinated and you aren't prompted to link on future sessions. This is local only \u2014 it is never committed, so a teammate on the same repo can still link it. Run `link` anytime to change your mind.",
+      inputSchema: z3.object({}).shape
+    },
+    async () => {
+      if (linked) {
+        return advisory(
+          `Already coordinating \`${context.workspace}\` \u2014 run \`unlink\` to stop coordinating this repo.`
+        );
+      }
+      rememberDecline();
+      return advisory(
+        "Won't coordinate this repo or ask again. Run `link` anytime to change your mind."
       );
     }
   );
@@ -1457,23 +1598,23 @@ Run \`link\` again with workspace "${allowed}" to opt this repo in.`
 }
 
 // src/identityCache.ts
-import { mkdirSync as mkdirSync2, readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "fs";
-import { homedir as homedir2, tmpdir as tmpdir2 } from "os";
-import { dirname as dirname3, join as join3 } from "path";
+import { mkdirSync as mkdirSync3, readFileSync as readFileSync4, writeFileSync as writeFileSync3 } from "fs";
+import { homedir as homedir3, tmpdir as tmpdir3 } from "os";
+import { dirname as dirname4, join as join4 } from "path";
 function defaultIdentityCachePath() {
   let base = "";
   try {
-    base = homedir2();
+    base = homedir3();
   } catch {
     base = "";
   }
-  if (!base) base = tmpdir2();
-  return join3(base, ".shepherd", "identity.json");
+  if (!base) base = tmpdir3();
+  return join4(base, ".shepherd", "identity.json");
 }
 function readCachedHuman(filePath = defaultIdentityCachePath()) {
   let raw;
   try {
-    raw = readFileSync3(filePath, "utf8");
+    raw = readFileSync4(filePath, "utf8");
   } catch {
     return null;
   }
@@ -1488,9 +1629,9 @@ function readCachedHuman(filePath = defaultIdentityCachePath()) {
 function writeCachedHuman(human, filePath = defaultIdentityCachePath()) {
   if (typeof human !== "string" || human.trim().length === 0) return;
   try {
-    mkdirSync2(dirname3(filePath), { recursive: true });
+    mkdirSync3(dirname4(filePath), { recursive: true });
     const payload = JSON.stringify({ human });
-    writeFileSync2(filePath, payload + "\n", "utf8");
+    writeFileSync3(filePath, payload + "\n", "utf8");
   } catch {
   }
 }
@@ -1501,6 +1642,8 @@ var defaultDeps = {
   detectBranch,
   detectHuman,
   readMarker,
+  findRepoRoot,
+  isDeclined: (repoRoot) => isDeclined(repoRoot),
   readCachedHuman,
   writeCachedHuman
 };
@@ -1516,7 +1659,10 @@ async function resolveContext(config, cwd = process.cwd(), deps = defaultDeps) {
   const marker = deps.readMarker(cwd);
   const linked = marker !== null;
   const workspace = marker?.workspace ?? config.WORKSPACE ?? DEFAULT_WORKSPACE;
-  return { workspace, repo, branch, human, program, model, linked };
+  const repoRoot = deps.findRepoRoot(cwd);
+  const declined = repoRoot !== null ? deps.isDeclined(repoRoot) : false;
+  const linkState = linked ? "linked" : declined ? "declined" : "unanswered";
+  return { workspace, repo, branch, human, program, model, linked, declined, linkState };
 }
 function resolveHuman(config, cwd, deps) {
   if (config.HUMAN) return config.HUMAN;
@@ -1588,9 +1734,11 @@ function createHeartbeat({
 }
 
 // src/instructions.ts
-var SHEPHERD_INSTRUCTIONS = `You are connected to Shepherd, the shared coordination hub for a team of agents (human and AI) working in the same repositories. You have ALREADY been joined to the workspace automatically \u2014 there is no setup step, and you must not ask the user how to connect.
+var SHEPHERD_INSTRUCTIONS = `You are connected to Shepherd, the shared coordination hub for a team of agents (human and AI) working in the same repositories.
+
+On your first coordination-relevant action in a repo, if it isn't linked and hasn't been declined, call \`link\` with no argument: it auto-starts coordination if you belong to exactly one workspace, or lists your workspaces \u2014 ask the user "Coordinate this repo with Shepherd? Which workspace?" then call \`link <workspace>\` with their answer, or \`decline\` if they say no. Ask at most once per repo: once linked or declined, do not ask again \u2014 the marker is committed and teammates inherit it, so coordination is automatic from then on.
 
-Follow this procedure on every session, proactively and without being asked:
+Once linked, follow this procedure on every session, proactively and without being asked:
 
 1. Before you start producing or changing files in an AREA of the codebase, call \`work\` ONCE. This includes authoring a plan or design doc: claim the doc's path (e.g. ["docs/plans/auth.md"], or the directory you'll write into) BEFORE you write it \u2014 a plan you're about to author counts as a unit of work, not exploration. Pass a one-line \`intent\` and the \`pathGlobs\` covering the files you expect to touch. Scope the globs as specifically as you reasonably can \u2014 tight enough to avoid colliding with unrelated work, broad enough to cover the task (e.g. ["src/auth/**"], not ["src/**"] and not a single file). Hold that one claim across all your edits in that area; do NOT re-claim per file. If it reports a conflict, coordinate or pick different work \u2014 never silently collide.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@korso/shepherd",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Shepherd MCP server — gives any MCP-capable agent (Claude Code, Codex, etc.) four advisory cross-session coordination tools (work/done/announce/sync) backed by the shared Shepherd hub. Joins the workspace automatically and ships standing instructions so the agent self-coordinates.",
   "type": "module",
   "main": "dist/index.js",
@@ -15,10 +15,10 @@
   "engines": {
     "node": ">=18"
   },
-  "license": "UNLICENSED",
+  "license": "AGPL-3.0-only",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/Korsoai/shepherd.git",
+    "url": "git+https://github.com/Korso-AI/shepherd.git",
     "directory": "packages/mcp-server"
   },
   "keywords": [