pipebrain-mcp 0.32.0 → 0.34.0

package/README.md

@@ -32,7 +32,7 @@ at each launch.
 
 | Variable | Meaning |
 | --- | --- |
-| `PIPEBRAIN_TOKEN` | Your `pbt_…` API token (Settings → Organization → API tokens). A pre-rename `plt_…` token still works. |
+| `PIPEBRAIN_TOKEN` | Your `pbt_…` API token (Settings → Organization → API tokens). |
 | `PIPEBRAIN_API_URL` | API base URL, e.g. `https://api.pipebrain.dev`. Required — there is no default, so a session can always tell which environment it is bound to. |
 
 Secret VALUES never cross this server: the secrets tools return metadata only, and there

package/dist/main.js

@@ -356,9 +356,52 @@ var require_main = __commonJS({
   }
 });
 
+// ../../libs/agent-shared/dist/agent-config.js
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+// ../../libs/agent-shared/dist/agent-config-manifest.js
+var AGENT_CONFIG_DIGEST = "898da8356dac55bd14531dcb5440aa3bd7bbcaa72e873d0fee4a102e3d718ee1";
+
+// ../../libs/agent-shared/dist/agent-config.js
+function agentConfigDir(env = process.env) {
+  const configured = env.CLAUDE_CONFIG_DIR;
+  return configured !== void 0 && configured !== "" ? configured : join(homedir(), ".claude");
+}
+var STAMP_REL = "pipebrain/installed.json";
+function readInstalledStamp(dir) {
+  const file2 = join(dir, STAMP_REL);
+  if (!existsSync(file2))
+    return null;
+  try {
+    const parsed = JSON.parse(readFileSync(file2, "utf8"));
+    if (typeof parsed !== "object" || parsed === null)
+      return null;
+    const stamp = parsed;
+    return typeof stamp.configDigest === "string" && stamp.configDigest !== "" ? {
+      configDigest: stamp.configDigest,
+      installedBy: typeof stamp.installedBy === "string" ? stamp.installedBy : "unknown",
+      installedAt: typeof stamp.installedAt === "string" ? stamp.installedAt : "unknown"
+    } : null;
+  } catch {
+    return null;
+  }
+}
+function agentConfigStatus(dir, shipped = AGENT_CONFIG_DIGEST) {
+  const stamp = readInstalledStamp(dir);
+  if (stamp === null)
+    return "absent";
+  return stamp.configDigest === shipped ? "current" : "behind";
+}
+var UPDATE_COMMAND = "ppb setup";
+function agentConfigNotice(status) {
+  return status === "behind" ? `This machine's shared agent configuration is not the one this build ships \u2014 run \`${UPDATE_COMMAND}\` to see what would change and update it.` : null;
+}
+
 // ../../libs/agent-shared/dist/asset-transfer.js
 import { createHash } from "node:crypto";
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync as existsSync2, readFileSync as readFileSync2, writeFileSync } from "node:fs";
 import { basename, extname } from "node:path";
 var MIME_BY_EXT = {
   ".png": "image/png",
@@ -381,9 +424,9 @@ function guessContentType(filename) {
   return MIME_BY_EXT[extname(filename).toLowerCase()] ?? "application/octet-stream";
 }
 async function uploadAssetFromPath(client2, apiBaseUrl, input) {
-  if (!existsSync(input.path))
+  if (!existsSync2(input.path))
     throw new Error(`file not found: ${input.path}`);
-  const bytes = readFileSync(input.path);
+  const bytes = readFileSync2(input.path);
   const filename = basename(input.path);
   const contentType = input.contentType ?? guessContentType(filename);
   const sha256 = createHash("sha256").update(bytes).digest("hex");
@@ -433,21 +476,14 @@ function apiBindingLabel(apiBaseUrl) {
 var DOCTRINE = "# Pipebrain doctrine\n\nHow an agent works inside Pipebrain. These rules ship with the product and read the same in every organization, because each exists where disagreeing breaks something the product guarantees rather than merely changing house style.\n\nHow your organization *writes* is its own text, edited in Settings, and follows this document under a heading naming each scope.\n\n## Decisions are yours; escalate on consequence\n\nInside an approved requirement you choose the design, the libraries, the structure, and the sequencing. Do not ask, report, or seek ratification for the choice. Escalate on consequence, not uncertainty: a choice that changes what a user sees, costs money, or contradicts an approved requirement is filed as a question with the options you propose; everything else you decide and carry on. A technical choice worth keeping is a decision record, never a paragraph.\n\n## Every loose end has one destination, and none of them is prose\n\nAnything you notice that is not the work in front of you goes to exactly one of three places: a question, when the operator has to choose; a new issue at triage, when it is real work outside this item's scope; or nowhere. Nowhere is the default, and the right outcome whenever knowing the thing would change nothing anyone does. Never open a section called notes, caveats, observations, things to know, or next steps in a body or a comment. Filing is the report: an item recorded and then repeated in prose asks the operator to triage it twice.\n\n## A decision you need is filed as a question, never written into a body\n\nAn open decision belongs in a question on the issue, filed with `ask_questions`, carrying the options you propose. It does not belong in a body \u2014 not under a heading, and not in a field. A decision written into prose prompts nobody and records no answer, so the operator has no place to make it and a later session cannot tell whether it ever was. Retract one your own work has since settled, so nothing asks the operator to decide something nobody waits on.\n\n## Search before you create\n\nLook for the existing record before adding one. A duplicate splits one thing's history across two identifiers, and the split is permanent \u2014 nothing merges them afterward.\n\n## Link by key; never paste another record's text\n\nReference a requirement, a decision, or an issue by its key, with its title on first mention. Never paste its text into a body. The source changes and the copy does not, and the stale copy is what gets built.\n\n## Cross-cutting requirements arrive on their own\n\nThey bind every epic automatically and come back with a work-item read, at their latest approved revision. Never restate them in a body and never add them as explicit requirement links. An explicit link pins a document at an approved revision, which is a different act.\n\n## Verification modes follow what can be driven\n\nBefore assigning a mode, establish what this project can drive end to end: a harness, and the command that runs it. A criterion is `auto` when an evaluator can drive the input and read the result against the running system, including behavior shown in an interface wherever such a harness exists. What qualifies it is the evaluator's own run, never the existence of a test the implementer wrote.\n\nMark `manual` only when the verdict needs a person's judgment. A criterion you cannot describe as drivable is usually worded too vaguely: reword it against the observable rather than fall back to a person. A `manual` criterion carries instructions for whoever checks it by hand, written for someone who has not seen the code or the conversation that produced it.\n\nA manual criterion carrying no recorded artifact is the human gate working as designed rather than a coverage gap, so it is neither a finding nor weaker than one carrying evidence.\n\n## The bar for filing a bug\n\nFile a bug only when the observed behavior breaks an approved requirement or a defined acceptance criterion, and name which one before you file. Failing that, it is not a bug: code you find unclear, an edge case nobody specified, a performance number nobody set, and anything you would phrase as \"this could be better\" are opinions about the product, so file each as feedback or not at all. The bar exists because a queue holding both real defects and unshared taste has to be read entirely before any of it can be trusted.\n\n## A decision record is written once\n\nIt states what was decided and why, at the time it was decided, and is not edited as understanding moves. A superseding record replaces it, and the chain of the two is the account of how the thinking changed \u2014 which an edited record destroys. Read the existing records before re-opening a settled question.\n\n## A secret value never travels in a tool call\n\nNo tool here returns one, and that is deliberate rather than an omission to be fixed. Nor should you put one in: a value typed into a tool call is in the transcript before the server can encrypt it, so it is already disclosed and the only remedy left is rotation. Set values with the command-line tool, from a file or on standard input, and inject them at run time rather than reading them into context.\n\n## Setting an instruction replaces the whole body\n\nThere is no partial update. Writing an instruction stores exactly the body you supply and discards everything that was there, so a partial write destroys the rest of the text. The procedure is: read the live value, compose the complete replacement, write it, then read the live value again to confirm what landed.\n\nWhat you are reading now is a snapshot taken when this session started, and so are the tool descriptions. An edit reaches the next session, never this one, so reading the text back after a write shows the pre-edit value. An agent that reports a diff of what it just wrote has read the snapshot instead of the record.\n";
 
 // ../../libs/agent-shared/dist/resolve-agent-env.js
-function pick(env, primary, legacy) {
-  const fromPrimary = env[primary];
-  if (fromPrimary !== void 0 && fromPrimary !== "") {
-    return { value: fromPrimary, source: primary };
-  }
-  const fromLegacy = env[legacy];
-  if (fromLegacy !== void 0 && fromLegacy !== "") {
-    return { value: fromLegacy, source: legacy };
-  }
-  return void 0;
+function pick(env, name) {
+  const value = env[name];
+  return value !== void 0 && value !== "" ? { value, source: name } : void 0;
 }
 function resolveAgentEnv(env) {
   return {
-    apiUrl: pick(env, "PIPEBRAIN_API_URL", "PIPELINE_API_URL"),
-    token: pick(env, "PIPEBRAIN_TOKEN", "PIPELINE_TOKEN")
+    apiUrl: pick(env, "PIPEBRAIN_API_URL"),
+    token: pick(env, "PIPEBRAIN_TOKEN")
   };
 }
 
@@ -15044,9 +15080,9 @@ var widgetOriginSchema = external_exports.string().trim().transform((raw) => raw
 });
 var emailSchema = external_exports.email({ message: "enter a valid email address" });
 var passwordSchema = external_exports.string().min(8, { message: "password must be at least 8 characters" }).max(128, { message: "password must be at most 128 characters" });
-var ACCEPTED_TOKEN_PREFIXES = ["pbt_", "plt_"];
+var ACCEPTED_TOKEN_PREFIXES = ["pbt_"];
 var tokenPrefixSchema = external_exports.string().regex(new RegExp(`^(?:${ACCEPTED_TOKEN_PREFIXES.join("|")})[0-9A-Za-z]{4}$`), {
-  message: "token prefix must be `pbt_` (or the legacy `plt_`) followed by 4 base62 characters"
+  message: "token prefix must be `pbt_` followed by 4 base62 characters"
 });
 var SECRET_NAME_RE = /^[A-Z_][A-Z0-9_]*$/;
 var secretNameSchema = external_exports.string().regex(SECRET_NAME_RE, {
@@ -15589,6 +15625,22 @@ var orgInstructionSchema = external_exports.object({
   body: external_exports.string().min(1),
   createdBy: uuidSchema.nullable(),
   viaTokenId: uuidSchema.nullable(),
+  /**
+   * sha256 of the shipped default this row was SEEDED from, or null when nothing seeded
+   * it — a row written by a person, a row re-created after its scope was cleared, or a row
+   * that predates seeding.
+   *
+   * It is what lets a settings page say the shipped default has MOVED since this
+   * organization got it, without the product ever applying that move: comparing this digest
+   * against the running release's default for the same scope is the whole signal. It is not
+   * updated by an edit, because what it records is what was seeded — which stays true after
+   * the organization rewrites the body, and is exactly then that the comparison is worth
+   * making.
+   *
+   * `.default(null)` rather than a bare nullable, for the tolerance this schema keeps
+   * throughout: a payload from a server that predates the column still parses.
+   */
+  seededDefaultSha: external_exports.string().nullable().default(null),
   createdAt: external_exports.iso.datetime({ offset: true }),
   updatedAt: external_exports.iso.datetime({ offset: true }),
   deletedAt: external_exports.iso.datetime({ offset: true }).nullable()
@@ -16105,6 +16157,12 @@ var listEnvelopeSchema = (item) => external_exports.object({ items: external_exp
 var mintedTokenSchema = apiTokenSchema.extend({ token: external_exports.string().min(1) }).loose();
 var tokenListSchema = listEnvelopeSchema(apiTokenSchema);
 var orgInstructionListSchema = listEnvelopeSchema(orgInstructionSchema);
+var instructionDefaultSchema = external_exports.object({
+  scope: external_exports.string().min(1),
+  body: external_exports.string().min(1),
+  sha256: external_exports.string().min(1)
+}).loose();
+var instructionDefaultListSchema = listEnvelopeSchema(instructionDefaultSchema);
 var ApiClient = class _ApiClient {
   baseUrl;
   auth;
@@ -16715,6 +16773,18 @@ var ApiClient = class _ApiClient {
     const body = await this.request("GET", "/api/v1/org-instructions", {}, orgInstructionListSchema);
     return body.items;
   }
+  /**
+   * The starting text THIS RELEASE ships, per scope, with the digest a seeded row records.
+   *
+   * Shipped content rather than the org's, so it carries no tenant data and any
+   * authenticated caller may read it. Comparing a row's `seededDefaultSha` against the
+   * `sha256` here is how a settings page says the shipped default has MOVED since this
+   * organization was seeded — a difference the product reports and never applies.
+   */
+  async listInstructionDefaults() {
+    const body = await this.request("GET", "/api/v1/org-instructions/defaults", {}, instructionDefaultListSchema);
+    return body.items;
+  }
   /** Upserts one scope's instruction text (ADMIN+; body ≤ 4000 chars). */
   setOrgInstruction(scope, body) {
     return this.request("PUT", `/api/v1/org-instructions/${enc(scope)}`, { body: { body } }, orgInstructionSchema);
@@ -16867,11 +16937,18 @@ function bindingBanner(apiBaseUrl) {
   return `Pipebrain MCP server, bound to the ${apiBindingLabel(apiBaseUrl)} API at ${apiBaseUrl}. Every tool reads and writes THAT environment \u2014 confirm it is the one you intend before mutating.`;
 }
 var INDEX_RULES = "Until you have it: an open decision is filed as a question with `ask_questions` and never written into a body; search for an existing record before creating one, because a duplicate splits one thing\u2019s history across two identifiers and nothing merges them afterward; and a secret value never travels in a tool call, because a value in a call is disclosed before the server can encrypt it.";
-function composeIndex(base) {
+function composeIndex(base, machineNotice2 = null) {
   return [
     base,
     "Call `get_work_context` before you write anything \u2014 it returns the binding guidance, the product doctrine and this organization\u2019s own writing rules, together with the work. Nothing else delivers that guidance in full; every other read only names this call.",
-    INDEX_RULES
+    INDEX_RULES,
+    // LAST, and usually absent. It is about the MACHINE rather than about the work, so it
+    // must never displace a rule: a squeezed share keeps the prefix, and losing a sentence
+    // about an installer costs less than losing the sentence that recovers everything else.
+    // Present only when this machine's shared configuration is not the one this build ships
+    // (PIPE-354 AC-5) — a machine that never installed it is passed over in silence, since
+    // it has no configuration to be behind with.
+    ...machineNotice2 === null ? [] : [machineNotice2]
   ].join("\n\n");
 }
 async function fetchOrgInstructionsSafe(client2) {
@@ -16912,10 +16989,12 @@ ${body}`);
 }
 
 // ../../libs/mcp-server/dist/server.js
-var SUCCESSOR_NOTICE = "NOTICE \u2014 this server is the FINAL release of the `@fvcsolutions/pipeline-mcp` package. The server moved to `pipebrain-mcp` on npmjs.org (public, no registry auth), and the CLI moved to `pipebrain-cli`, which provides the `ppb` command in place of `pipeline`. Re-register through the team bootstrap, or: `claude mcp add pipebrain -s user -e PIPEBRAIN_API_URL=https://api.pipebrain.dev -e 'PIPEBRAIN_TOKEN=${PIPEBRAIN_TOKEN}' -- npx -y pipebrain-mcp@latest`. Tell the operator; this build still works and will not be updated again.\n\n";
-function successorNotice() {
-  const armed = process.env.PIPELINE_MCP_SUCCESSOR_NOTICE;
-  return armed === void 0 || armed === "" ? "" : SUCCESSOR_NOTICE;
+function machineNotice() {
+  try {
+    return agentConfigNotice(agentConfigStatus(agentConfigDir()));
+  } catch {
+    return null;
+  }
 }
 var DEFAULT_VERSION = "0.0.0";
 function ok(data, appended) {
@@ -16983,7 +17062,13 @@ function createMcpServer(client2, apiBaseUrl, orgInstructions2 = /* @__PURE__ */
     // which environment this is bound to, the call that returns the binding guidance,
     // and the three rules whose violation cannot be undone. Everything else comes from
     // `docs/DOCTRINE.md` and the org's saved texts, on the work-context read.
-    instructions: composeIndex(successorNotice() + banner)
+    //
+    // Plus, only when there is something to say, one line about the MACHINE: its shared
+    // agent configuration is not the one this build ships (PIPE-354 AC-5). Read here
+    // rather than passed in, because the fact is about the filesystem this process is
+    // running on and there is no caller better placed to know it; a read failure
+    // degrades to silence, since a session must not fail to start over an installer.
+    instructions: composeIndex(banner, machineNotice())
   });
   server2.registerTool("list_projects", {
     description: "List all projects with their key, environments, milestones (token, label, active), and open-issue counts \u2014 the project switcher and workflow entry point (\xA77).",
@@ -17012,10 +17097,17 @@ function createMcpServer(client2, apiBaseUrl, orgInstructions2 = /* @__PURE__ */
     // path that has no precedent anywhere on this surface. The viewer narrowing the
     // web queue offers is filter state on that view, not something an agent picks.
   }, () => (
-    // `{ items }`, mirroring the HTTP envelope rather than unwrapping to a bare
-    // array like the sibling list tools: AC-7 asks that an agent read the SAME set
-    // the queue shows, and the two surfaces answering in the same shape is what
-    // makes that comparable at a glance.
+    // `{ items }`, mirroring the HTTP envelope rather than unwrapping to a bare array
+    // like the sibling list tools. The reason is the envelope itself: this tool is a
+    // pass-through of one endpoint's answer, and reshaping it here would be a second
+    // place for that answer's shape to be decided.
+    //
+    // The two surfaces are NOT interchangeable, and nothing here should suggest they
+    // are. This tool takes no narrowing arguments and returns the org's WHOLE queue,
+    // while the web view narrows what it DRAWS — by project, by category, and by viewer
+    // scope. One endpoint decides what counts as a gate, so that definition cannot drift
+    // between them; what an agent reads here is everything waiting, rather than whatever
+    // the operator happens to be looking at.
     run(async () => ({ items: await client2.listWaiting() }), GUIDANCE_POINTER)
   ));
   server2.registerTool(
@@ -17352,11 +17444,11 @@ function createMcpServer(client2, apiBaseUrl, orgInstructions2 = /* @__PURE__ */
     inputSchema: linkAssetInputSchema.shape
   }, (args) => run(() => client2.linkAsset(args)));
   server2.registerTool("unlink_asset", {
-    description: "Remove an asset reference by its link id (soft-delete). The asset itself is untouched \u2014 this only drops the reference from its target.",
+    description: "Remove an asset reference by its link id (soft-delete). The asset itself is untouched \u2014 this only drops the reference from its target. A link whose target is a CHAT MESSAGE is author-only: anyone but the person who wrote that message is refused with `not_message_author` (403), so an attachment you did not post is not yours to detach. Every other target type is removable by any member.",
     inputSchema: unlinkAssetInputSchema.shape
   }, (args) => run(() => client2.unlinkAsset(args.linkId)));
   server2.registerTool("set_secret", {
-    description: "Create a secret or add a new version under a project + environment (metadata only \u2014 the response NEVER echoes the value). `name` is UPPER_SNAKE_CASE (e.g. API_KEY); `environment` is the environment slug (dev/prod); optional `description`.",
+    description: "Create a secret or add a new version under a project + environment (metadata only \u2014 the response NEVER echoes the value). `name` is UPPER_SNAKE_CASE (e.g. API_KEY); `environment` is the environment slug (dev/prod); optional `description`. Writing guidance for that description lives in the product doctrine, which `get_work_context` returns.",
     inputSchema: {
       project: projectKeySchema,
       environment: external_exports.string().min(1),
@@ -17451,14 +17543,14 @@ var apiTokenSchema2 = external_exports.string().min(1).superRefine((value, ctx)
   if (!isAcceptedTokenShape(value)) {
     ctx.addIssue({
       code: "custom",
-      message: "is not a Pipebrain API token \u2014 expected `pbt_\u2026` (legacy `plt_\u2026` accepted) (value withheld). Mint one under Settings \u2192 Organization \u2192 API tokens."
+      message: "is not a Pipebrain API token \u2014 expected `pbt_\u2026` (value withheld). Mint one under Settings \u2192 Organization \u2192 API tokens."
     });
   }
 });
-function validate(schema, resolved, primary, legacy, issues, variables) {
+function validate(schema, resolved, name, issues, variables) {
   if (resolved === void 0) {
-    issues.push(`${primary}: is not set (the legacy ${legacy} is still honored as a fallback)`);
-    variables.push(primary);
+    issues.push(`${name}: is not set`);
+    variables.push(name);
     return void 0;
   }
   const result = schema.safeParse(resolved.value);
@@ -17476,8 +17568,8 @@ function loadMcpConfig() {
   const resolved = resolveAgentEnv(process.env);
   const issues = [];
   const variables = [];
-  const apiUrl = validate(external_exports.url(), resolved.apiUrl, "PIPEBRAIN_API_URL", "PIPELINE_API_URL", issues, variables);
-  const token = validate(apiTokenSchema2, resolved.token, "PIPEBRAIN_TOKEN", "PIPELINE_TOKEN", issues, variables);
+  const apiUrl = validate(external_exports.url(), resolved.apiUrl, "PIPEBRAIN_API_URL", issues, variables);
+  const token = validate(apiTokenSchema2, resolved.token, "PIPEBRAIN_TOKEN", issues, variables);
   if (apiUrl === void 0 || token === void 0) {
     throw new EnvValidationError(issues, variables);
   }
@@ -17485,7 +17577,7 @@ function loadMcpConfig() {
 }
 
 // src/version.ts
-var VERSION = "0.32.0";
+var VERSION = "0.34.0";
 
 // src/main.ts
 var config2 = loadMcpConfig();
@@ -17500,8 +17592,6 @@ var server = createMcpServer(client, config2.apiUrl, orgInstructions, {
 });
 var transport = new StdioServerTransport();
 await server.connect(transport);
-var notice = successorNotice();
-if (notice !== "") process.stderr.write(notice);
 process.stderr.write(
   `pipebrain mcp connected \u2014 ${apiBindingLabel(config2.apiUrl)} API base ${config2.apiUrl}
 `

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pipebrain-mcp",
-  "version": "0.32.0",
-  "description": "Pipebrain MCP server for Claude Code and Claude Desktop — issues, requirements, content, assets, and metadata-only secrets over the Pipebrain API.",
+  "version": "0.34.0",
+  "description": "Pipebrain MCP server for Claude Code and Claude Desktop \u2014 issues, requirements, content, assets, and metadata-only secrets over the Pipebrain API.",
   "type": "module",
   "license": "MIT",
   "main": "./dist/main.js",