@jaggerxtrm/specialists 2.1.0 → 2.1.2

package/README.md

@@ -86,15 +86,22 @@ The orchestrating agent can retrieve the `beadId` from `poll_specialist` output
 
 ## Installation
 
-### One-line installer (recommended)
+### Recommended
 
 ```bash
-npx --package=@jaggerxtrm/specialists install
+npm install -g @jaggerxtrm/specialists
+specialists install
 ```
 
 Installs: **pi** (`@mariozechner/pi-coding-agent`), **beads** (`@beads/bd`), **dolt** (interactive sudo on Linux / brew on macOS), registers the `specialists` MCP at user scope, scaffolds `~/.agents/specialists/`.
 
-After running, **restart Claude Code** to load the MCP.
+After running, **restart Claude Code** to load the MCP. Re-run `specialists install` at any time to update or repair the installation.
+
+### One-time (no global install)
+
+```bash
+npx --package=@jaggerxtrm/specialists install
+```
 
 ---
 

package/dist/index.js

@@ -13393,6 +13393,11 @@ var require_public_api = __commonJS((exports) => {
   exports.stringify = stringify;
 });
 
+// src/index.ts
+import { execFileSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname as dirname2, join as join4 } from "node:path";
+
 // node_modules/zod/v3/external.js
 var exports_external = {};
 __export(exports_external, {
@@ -25080,6 +25085,57 @@ class PiAgentSession {
 }
 
 // src/specialist/beads.ts
+import { spawnSync } from "node:child_process";
+
+class BeadsClient {
+  available;
+  constructor() {
+    this.available = BeadsClient.checkAvailable();
+    if (!this.available) {
+      console.warn("[specialists] bd CLI not found — beads tracking disabled");
+    }
+  }
+  static checkAvailable() {
+    const result = spawnSync("bd", ["--version"], { stdio: "ignore" });
+    return result.status === 0;
+  }
+  isAvailable() {
+    return this.available;
+  }
+  createBead(specialistName) {
+    if (!this.available)
+      return null;
+    const result = spawnSync("bd", ["q", `specialist:${specialistName}`, "--type", "task", "--labels", "specialist"], { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] });
+    if (result.status !== 0)
+      return null;
+    const id = result.stdout?.trim();
+    return id || null;
+  }
+  closeBead(id, status, durationMs, model) {
+    if (!this.available || !id)
+      return;
+    const reason = `${status}, ${Math.round(durationMs)}ms, ${model}`;
+    spawnSync("bd", ["close", id, "-r", reason], { stdio: "ignore" });
+  }
+  auditBead(id, toolName, model, exitCode) {
+    if (!this.available || !id)
+      return;
+    spawnSync("bd", [
+      "audit",
+      "record",
+      "--kind",
+      "tool_call",
+      "--tool-name",
+      toolName,
+      "--model",
+      model,
+      "--issue-id",
+      id,
+      "--exit-code",
+      String(exitCode)
+    ], { stdio: "ignore" });
+  }
+}
 function shouldCreateBead(beadsIntegration, permissionRequired) {
   if (beadsIntegration === "never")
     return false;
@@ -25096,7 +25152,7 @@ class SpecialistRunner {
     this.deps = deps;
     this.sessionFactory = deps.sessionFactory ?? PiAgentSession.create.bind(PiAgentSession);
   }
-  async run(options, onProgress, onEvent, onMeta, onKillRegistered) {
+  async run(options, onProgress, onEvent, onMeta, onKillRegistered, onBeadCreated) {
     const { loader, hooks, circuitBreaker, beadsClient } = this.deps;
     const invocationId = crypto.randomUUID();
     const start = Date.now();
@@ -25156,6 +25212,8 @@ You have access via Bash:
     let beadId;
     if (beadsClient && shouldCreateBead(beadsIntegration, execution.permission_required)) {
       beadId = beadsClient.createBead(metadata.name) ?? undefined;
+      if (beadId)
+        onBeadCreated?.(beadId);
     }
     let output;
     let session;
@@ -25240,7 +25298,7 @@ You have access via Bash:
       model: "?",
       specialistVersion
     });
-    this.run(options, (text) => registry2.appendOutput(jobId, text), (eventType) => registry2.setCurrentEvent(jobId, eventType), (meta) => registry2.setMeta(jobId, meta), (killFn) => registry2.setKillFn(jobId, killFn)).then((result) => registry2.complete(jobId, result)).catch((err) => registry2.fail(jobId, err));
+    this.run(options, (text) => registry2.appendOutput(jobId, text), (eventType) => registry2.setCurrentEvent(jobId, eventType), (meta) => registry2.setMeta(jobId, meta), (killFn) => registry2.setKillFn(jobId, killFn), (beadId) => registry2.setBeadId(jobId, beadId)).then((result) => registry2.complete(jobId, result)).catch((err) => registry2.fail(jobId, err));
     return jobId;
   }
 }
@@ -25343,7 +25401,7 @@ var useSpecialistSchema = exports_external.object({
 function createUseSpecialistTool(runner) {
   return {
     name: "use_specialist",
-    description: "Execute a specialist. Full lifecycle: load → agents.md → pi → validate → output.",
+    description: "Run a specialist synchronously and wait for the result. " + "Full lifecycle: load → agents.md → pi session → output. " + "Response includes output, model, durationMs, and beadId (string | undefined). " + "beadId is set when the specialist's beads_integration policy triggered bead creation " + "(default: auto — creates for LOW/MEDIUM/HIGH permission, skips for READ_ONLY). " + "If beadId is present, use `bd update <beadId> --notes` to attach findings or " + "`bd remember` to persist key discoveries for future sessions.",
     inputSchema: useSpecialistSchema,
     async execute(input, onProgress) {
       return runner.run({
@@ -25584,7 +25642,7 @@ var startSpecialistSchema = exports_external.object({
 function createStartSpecialistTool(runner, registry2) {
   return {
     name: "start_specialist",
-    description: "Start a specialist asynchronously. Returns job_id immediately — use poll_specialist to track progress and get output. Enables true parallel execution of multiple specialists.",
+    description: "Start a specialist asynchronously. Returns job_id immediately. " + "Use poll_specialist to track progress, receive output delta, and retrieve beadId " + "(the beads issue auto-created for this run, if beads_integration policy applies). " + "Use stop_specialist to cancel. Enables true parallel execution of multiple specialists.",
     inputSchema: startSpecialistSchema,
     async execute(input) {
       const jobId = await runner.startAsync({
@@ -25606,7 +25664,7 @@ var pollSpecialistSchema = exports_external.object({
 function createPollSpecialistTool(registry2) {
   return {
     name: "poll_specialist",
-    description: "Poll a running specialist job. Returns status (running|done|error), delta (new content since cursor), next_cursor, and full output only when done. Pass next_cursor from each response as cursor on the next poll to receive only new tokens.",
+    description: "Poll a running specialist job. Returns status (running|done|error|cancelled), " + "delta (new tokens since cursor), next_cursor, and full output when done. " + "Pass next_cursor back as cursor on each subsequent poll to receive only new content. " + "Response also includes beadId (string | undefined) once the specialist has started — " + "this is the beads issue tracking this run. If present after status=done, consider: " + '`bd update <beadId> --notes "<key finding>"` to attach results, or ' + '`bd remember "<insight>"` to persist discoveries across sessions.',
     inputSchema: pollSpecialistSchema,
     async execute(input) {
       const snapshot = registry2.snapshot(input.job_id, input.cursor ?? 0);
@@ -25638,19 +25696,19 @@ function createStopSpecialistTool(registry2) {
 }
 
 // src/tools/specialist/specialist_init.tool.ts
-import { spawnSync } from "node:child_process";
+import { spawnSync as spawnSync2 } from "node:child_process";
 import { existsSync as existsSync2 } from "node:fs";
 import { join as join2 } from "node:path";
-var specialistInitSchema = exports_external.object({});
+var specialistInitSchema = objectType({});
 function createSpecialistInitTool(loader, deps) {
   const resolved = deps ?? {
-    bdAvailable: () => spawnSync("bd", ["--version"], { stdio: "ignore" }).status === 0,
+    bdAvailable: () => spawnSync2("bd", ["--version"], { stdio: "ignore" }).status === 0,
     beadsExists: () => existsSync2(join2(process.cwd(), ".beads")),
-    bdInit: () => spawnSync("bd", ["init"], { stdio: "ignore" })
+    bdInit: () => spawnSync2("bd", ["init"], { stdio: "ignore" })
   };
   return {
     name: "specialist_init",
-    description: "Session bootstrap: initializes beads in the project if not already set up, " + "then returns available specialists. Call at session start for orientation.",
+    description: "Call this first at session start. Returns available specialists and initializes beads " + "tracking (runs `bd init` if not already set up). " + "Response includes: specialists[] (use with use_specialist/start_specialist), " + "beads.available (bool), beads.initialized (bool). " + "If beads.available is true, specialists with permission LOW/MEDIUM/HIGH will auto-create " + "a beads issue when they run — no action needed from you.",
     inputSchema: specialistInitSchema,
     async execute(_input) {
       const available = resolved.bdAvailable();
@@ -25682,7 +25740,8 @@ class SpecialistsServer {
     const hooks = new HookEmitter({
       tracePath: join3(process.cwd(), ".specialists", "trace.jsonl")
     });
-    const runner = new SpecialistRunner({ loader, hooks, circuitBreaker });
+    const beadsClient = new BeadsClient;
+    const runner = new SpecialistRunner({ loader, hooks, circuitBreaker, beadsClient });
     const registry2 = new JobRegistry;
     this.tools = [
       createListSpecialistsTool(loader),
@@ -25769,6 +25828,12 @@ class SpecialistsServer {
 }
 
 // src/index.ts
+if (process.argv[2] === "install") {
+  const __dirname2 = dirname2(fileURLToPath(import.meta.url));
+  const installerPath = join4(__dirname2, "..", "bin", "install.js");
+  execFileSync(process.execPath, [installerPath], { stdio: "inherit" });
+  process.exit(0);
+}
 async function main() {
   logger.info("Starting Specialists MCP Server...");
   const server = new SpecialistsServer;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaggerxtrm/specialists",
-  "version": "2.1.0",
+  "version": "2.1.2",
   "description": "OmniSpecialist — 7-tool MCP orchestration layer powered by the Specialist System. Discover and execute .specialist.yaml files across project/user/system scopes via pi.",
   "main": "dist/index.js",
   "type": "module",