askshepherd 0.1.38 → 0.1.40

package/README.md

@@ -75,7 +75,8 @@ above; it performs the bounded local checks.
 
 ## Set Up Coding Agent Sessions
 
-Use this when the user asks "Help me set up coding agent sessions":
+Use this when the user asks "Help me set up coding agent sessions" or "Enable
+coding agent sessions locally for Shepherd":
 
 ```sh
 npx -y askshepherd@latest agent --login
@@ -120,9 +121,10 @@ The saved MCP state includes:
 The installed MCP server is local npm first, remote brain second. For questions
 like "what do I have set up on Shepherd?", "is Shepherd syncing?", or "help me
 set up coding agent sessions", the MCP exposes local tools such as
-`shepherd_status` and `shepherd_setup_coding_sessions` that route agents to the
-local `askshepherd status` / add-source flow. Production memory and wiki tools
-remain remote Railway-backed tools for source recall and company-memory answers.
+`shepherd_status`, `shepherd_setup_coding_sessions`, and
+`shepherd_enable_coding_sessions` that route agents to the local
+`askshepherd status` / add-source flow. Production memory and wiki tools remain
+remote Railway-backed tools for source recall and company-memory answers.
 Those local MCP tools are also the permission boundary: an MCP client should not
 use shell or file tools to inspect the user's folders or repositories for setup.
 

package/bin/shepherd-onboard.js

@@ -2,7 +2,7 @@
 import { execFile, execFileSync, spawn } from "node:child_process";
 import { createHash } from "node:crypto";
 import { constants as fsConstants, existsSync, mkdirSync, readFileSync, unlinkSync, watch, writeFileSync } from "node:fs";
-import { access, mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
+import { access, chmod, mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
 import { createServer } from "node:http";
 import { homedir, platform } from "node:os";
 import { basename, dirname, join } from "node:path";
@@ -12,7 +12,7 @@ import { fileURLToPath } from "node:url";
 const DEFAULT_API_URL = "https://brain-api-customer-facing.up.railway.app";
 const PACKAGE_NAME = "askshepherd";
 const PACKAGE_SPEC = `${PACKAGE_NAME}@latest`;
-const PACKAGE_VERSION = "0.1.37";
+const PACKAGE_VERSION = "0.1.40";
 const MCP_SERVER_NAME = "shepherd";
 const PACKAGE_DIR = dirname(dirname(fileURLToPath(import.meta.url)));
 const DEFAULT_AGENT_STATE_PATH = join(homedir(), ".shepherd", "raw-onboarding-agent.json");
@@ -133,6 +133,12 @@ async function dispatch() {
     await runMessagesChatsCommand();
   } else if (command === "messages-agent") {
     await runMessagesAgent();
+  } else if (command === "write-agent-state") {
+    await runWriteAgentState();
+  } else if (command === "write-messages-config") {
+    await runWriteMessagesConfig();
+  } else if (command === "install-messages-agent") {
+    await runInstallMessagesAgent();
   } else if (command === "coding-sessions-agent") {
     await runCodingSessionsAgent();
   } else if (command === "coding-sessions-status") {
@@ -822,13 +828,20 @@ function localMcpTools() {
       annotations: readOnlyAnnotations,
       _meta: { provider: "local_npm", command: `${agentCommand()} agent --add-sources coding-sessions` },
     },
+    {
+      name: "shepherd_enable_coding_sessions",
+      description: "Alias for shepherd_setup_coding_sessions. Use when the user asks to enable coding agent sessions locally for Shepherd. Return the local askshepherd npm setup commands; do not search, list, or read the user's folders or repos.",
+      inputSchema: emptyInputSchema,
+      annotations: readOnlyAnnotations,
+      _meta: { provider: "local_npm", command: `${agentCommand()} agent --add-sources coding-sessions` },
+    },
   ];
 }
 
 function localMcpInstructions(remoteInstructions, remoteConnectError) {
   return [
     "This MCP server is the local askshepherd npm wrapper plus production Shepherd memory/wiki tools.",
-    `For local setup/sync questions like "what do I have set up on Shepherd", "what have I enabled", "is Shepherd syncing", "help me set up coding agent sessions", or "enable coding sessions", use shepherd_status or shepherd_setup_coding_sessions first. These local tools route to the local askshepherd npm status/setup flow. The askshepherd CLI is the only component that may perform bounded local checks of Shepherd state, LaunchAgents, and known Codex/Claude session locations.`,
+    `For local setup/sync questions like "what do I have set up on Shepherd", "what have I enabled", "is Shepherd syncing", "help me set up coding agent sessions", "enable coding sessions", or "enable coding agent sessions locally for Shepherd", use shepherd_status, shepherd_setup_coding_sessions, or shepherd_enable_coding_sessions first. These local tools route to the local askshepherd npm status/setup flow. The askshepherd CLI is the only component that may perform bounded local checks of Shepherd state, LaunchAgents, and known Codex/Claude session locations.`,
     "Hard boundary: do not use shell or filesystem tools such as ls, find, rg, grep, cat, Read, Glob, or Explore to inspect the user's home directory, repositories, ~/.codex, ~/.claude, or ~/.shepherd for Shepherd setup. If local status is needed, call shepherd_status or run the exact askshepherd status command.",
     `If the user asks for raw local status outside MCP, tell them to run ${agentCommand()} status. For setup of coding agent sessions, ask consent, then use ${agentCommand()} agent --login if needed, ${agentCommand()} agent --add-sources coding-sessions --name "<full_name>" --org "<organization>", ${agentCommand()} agent --continue, then ${agentCommand()} status.`,
     "Use production memory/wiki tools only for company-memory questions, source recall, wiki lookup, messages/meetings retrieval, or coding-session work history that has already synced to Shepherd.",
@@ -849,7 +862,7 @@ async function callLocalMcpTool(name) {
     ].join("\n\n"));
   }
 
-  if (name === "shepherd_setup_coding_sessions") {
+  if (name === "shepherd_setup_coding_sessions" || name === "shepherd_enable_coding_sessions") {
     const status = await collectShepherdStatus();
     return localMcpTextResult(renderCodingSessionsSetupMcpResult(status));
   }
@@ -916,9 +929,18 @@ async function writeMcpState(state) {
   const path = mcpStatePath();
   await mkdir(dirname(path), { recursive: true });
   await writeFile(path, JSON.stringify(state, null, 2), { mode: 0o600 });
+  await chmod(path, 0o600);
   return path;
 }
 
+function sanitizeUserFileId(userId) {
+  const safeId = String(userId ?? "").replace(/[^a-zA-Z0-9._-]/g, "-");
+  if (!safeId || safeId === "." || safeId === ".." || /^\.+$/.test(safeId)) {
+    throw new Error("Onboarding returned an invalid user ID for local Messages config.");
+  }
+  return safeId;
+}
+
 function mcpStatePath() {
   return expandHomePath(stringArg("state") ?? DEFAULT_MCP_STATE_PATH);
 }
@@ -1338,6 +1360,96 @@ function renderLocalCodingSessionsStatus(status) {
   return lines;
 }
 
+async function runWriteAgentState() {
+  const input = await readJsonInput();
+  if (!input || typeof input !== "object" || Array.isArray(input)) {
+    throw new Error("write-agent-state expects a JSON object on stdin.");
+  }
+  const previous = await readOptionalAgentState();
+  const statePath = await writeAgentState({ ...(previous ?? {}), ...input });
+  console.log(JSON.stringify({ statePath }, null, 2));
+}
+
+async function runWriteMessagesConfig() {
+  const input = await readJsonInput();
+  if (!input || typeof input !== "object" || Array.isArray(input)) {
+    throw new Error("write-messages-config expects a JSON object on stdin.");
+  }
+  const configPath = await writeMessagesConfig({
+    apiUrl: trimTrailingSlash(requiredConfigString(input.apiUrl, "apiUrl")),
+    userId: requiredConfigString(input.userId, "userId"),
+    agentToken: requiredConfigString(input.agentToken, "agentToken"),
+    backfillDays: parseBackfillDays(input.backfillDays, null),
+    allowedChatIds: input.allowedChatIds,
+    selectedChats: Array.isArray(input.selectedChats) ? input.selectedChats : [],
+  });
+  console.log(JSON.stringify({ configPath }, null, 2));
+}
+
+async function runInstallMessagesAgent() {
+  const configPath = stringArg("config");
+  if (!configPath) throw new Error("install-messages-agent requires --config <path>");
+  let config;
+  try {
+    config = JSON.parse(await readFile(configPath, "utf8"));
+  } catch (err) {
+    if (err && typeof err === "object" && "code" in err) throw err;
+    throw new Error(`install-messages-agent: config file at ${configPath} does not contain valid JSON.`);
+  }
+  const userId = stringArg("user-id") ?? requiredConfigString(config.userId, "userId");
+  const overrides = {
+    programArguments: parseJsonArrayArg("program"),
+    environment: parseJsonObjectArg("env"),
+  };
+
+  if (args["dry-run"]) {
+    console.log(JSON.stringify(buildMessagesAgentInstall(configPath, userId, overrides), null, 2));
+    return;
+  }
+
+  const install = await installMessagesAgent(configPath, userId, overrides);
+  console.log(JSON.stringify(install, null, 2));
+}
+
+async function readJsonInput() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  const text = Buffer.concat(chunks).toString("utf8").trim();
+  if (!text) throw new Error("Expected JSON input on stdin.");
+  return JSON.parse(text);
+}
+
+function parseJsonArrayArg(name) {
+  const raw = stringArg(name);
+  if (!raw) return undefined;
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error(`--${name} must be a JSON array of strings.`);
+  }
+  if (!Array.isArray(parsed) || parsed.some((value) => typeof value !== "string")) {
+    throw new Error(`--${name} must be a JSON array of strings.`);
+  }
+  return parsed;
+}
+
+function parseJsonObjectArg(name) {
+  const raw = stringArg(name);
+  if (!raw) return undefined;
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error(`--${name} must be a JSON object of string values.`);
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)
+    || Object.values(parsed).some((value) => typeof value !== "string")) {
+    throw new Error(`--${name} must be a JSON object of string values.`);
+  }
+  return parsed;
+}
+
 async function runMessagesChatsCommand() {
   await ensureMessagesReadPermission({ noOpen: Boolean(args["no-open"]) });
   const chats = await listRecentMessageChats({
@@ -1752,6 +1864,31 @@ Options:
     return;
   }
 
+  if (which === "write-agent-state" || which === "write-messages-config" || which === "install-messages-agent") {
+    console.log(`Shepherd onboarding engine commands
+
+These non-interactive commands are used by GUI onboarding apps (for example the
+Shepherd macOS app) so that this CLI stays the single owner of Shepherd state
+file schemas and the launchd install flow.
+
+Usage:
+  shepherd-onboard write-agent-state            JSON object on stdin is merged into ~/.shepherd/raw-onboarding-agent.json. Prints {statePath}.
+  shepherd-onboard write-messages-config        JSON object on stdin ({apiUrl, userId, agentToken, backfillDays?, allowedChatIds, selectedChats?}) is written to ~/.shepherd/raw-messages/<userId>.json. Prints {configPath}.
+  shepherd-onboard install-messages-agent --config <path>
+                                                Installs and verifies the Messages launchd agent for an existing config. Prints install metadata.
+
+install-messages-agent options:
+  --config <path>            Messages agent config created by onboarding. Required.
+  --user-id <id>             Override the user ID. Defaults to the config's userId.
+  --program <json_array>     Replace the default npx launcher with custom ProgramArguments (e.g. a signed app binary). --config <path> is appended.
+  --env <json_object>        Extra EnvironmentVariables merged into the launchd plist (e.g. ELECTRON_RUN_AS_NODE).
+  --dry-run                  Print the launchd plist and paths without writing or loading anything.
+  --no-permission-prompt     Fail instead of prompting when Full Disk Access is missing.
+  --help                     Show this help.
+`);
+    return;
+  }
+
   if (which === "mcp") {
     console.log(`Shepherd MCP stdio proxy
 
@@ -2142,6 +2279,9 @@ async function writeAgentState(state) {
   const path = agentStatePath();
   await mkdir(dirname(path), { recursive: true });
   await writeFile(path, JSON.stringify(state, null, 2), { mode: 0o600 });
+  // writeFile's mode only applies on creation; an existing file keeps its
+  // permissions, so enforce them on every token write.
+  await chmod(path, 0o600);
   return path;
 }
 
@@ -2653,7 +2793,11 @@ function headers(token) {
 async function writeMessagesConfig(input) {
   const dir = join(homedir(), ".shepherd", "raw-messages");
   await mkdir(dir, { recursive: true });
-  const path = join(dir, `${input.userId}.json`);
+  // The userId reaches this path from the network (server-issued session id)
+  // and, via write-messages-config, from stdin; sanitize it like the launchd
+  // label does so it can never traverse outside the raw-messages directory.
+  const safeId = sanitizeUserFileId(input.userId);
+  const path = join(dir, `${safeId}.json`);
   const allowedChatIds = parseAllowedChatIds(input.allowedChatIds);
   const allChats = selectedChatIdsIncludeAll(allowedChatIds);
   if (!allChats && allowedChatIds.length === 0) {
@@ -2674,25 +2818,34 @@ async function writeMessagesConfig(input) {
     }, null, 2),
     { mode: 0o600 },
   );
+  await chmod(path, 0o600);
   return path;
 }
 
-async function installMessagesAgent(configPath, userId) {
-  if (platform() !== "darwin") {
-    throw new Error("automatic local Messages sync is only supported on macOS");
-  }
-
+function buildMessagesAgentInstall(configPath, userId, overrides = {}) {
   const safeId = userId.replace(/[^a-zA-Z0-9.-]/g, "-");
   const label = `ai.shepherd.raw-messages.${safeId}`;
   const rawDir = join(homedir(), ".shepherd", "raw-messages");
   const agentsDir = join(homedir(), "Library", "LaunchAgents");
-  await mkdir(rawDir, { recursive: true });
-  await mkdir(agentsDir, { recursive: true });
-
   const plistPath = join(agentsDir, `${label}.plist`);
   const stdoutPath = join(rawDir, `${safeId}.out.log`);
   const stderrPath = join(rawDir, `${safeId}.err.log`);
-  const launchPath = launchAgentPath();
+
+  const programPrefix = Array.isArray(overrides.programArguments) && overrides.programArguments.length > 0
+    ? overrides.programArguments
+    : ["/usr/bin/env", "npx", "-y", PACKAGE_SPEC, "messages-agent"];
+  const programArguments = [...programPrefix, "--config", configPath];
+  const environment = {
+    PATH: launchAgentPath(),
+    ...stringRecord(overrides.environment),
+  };
+
+  const programArgumentsXml = programArguments
+    .map((value) => `    <string>${xmlEscape(value)}</string>`)
+    .join("\n");
+  const environmentXml = Object.entries(environment)
+    .map(([key, value]) => `    <key>${xmlEscape(key)}</key>\n    <string>${xmlEscape(value)}</string>`)
+    .join("\n");
 
   const plist = `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
@@ -2702,32 +2855,43 @@ async function installMessagesAgent(configPath, userId) {
   <string>${xmlEscape(label)}</string>
   <key>ProgramArguments</key>
   <array>
-    <string>/usr/bin/env</string>
-    <string>npx</string>
-    <string>-y</string>
-    <string>${PACKAGE_SPEC}</string>
-    <string>messages-agent</string>
-    <string>--config</string>
-    <string>${xmlEscape(configPath)}</string>
+${programArgumentsXml}
   </array>
   <key>KeepAlive</key>
   <true/>
   <key>RunAtLoad</key>
   <true/>
+  <key>ThrottleInterval</key>
+  <integer>10</integer>
+  <key>WorkingDirectory</key>
+  <string>${xmlEscape(rawDir)}</string>
   <key>StandardOutPath</key>
   <string>${xmlEscape(stdoutPath)}</string>
   <key>StandardErrorPath</key>
   <string>${xmlEscape(stderrPath)}</string>
   <key>EnvironmentVariables</key>
   <dict>
-    <key>PATH</key>
-    <string>${xmlEscape(launchPath)}</string>
+${environmentXml}
   </dict>
 </dict>
 </plist>
 `;
 
+  return { label, rawDir, agentsDir, plistPath, stdoutPath, stderrPath, programArguments, environment, plist };
+}
+
+async function installMessagesAgent(configPath, userId, overrides = {}) {
+  if (platform() !== "darwin") {
+    throw new Error("automatic local Messages sync is only supported on macOS");
+  }
+
+  const install = buildMessagesAgentInstall(configPath, userId, overrides);
+  const { label, rawDir, agentsDir, plistPath, stdoutPath, stderrPath, plist } = install;
+  await mkdir(rawDir, { recursive: true });
+  await mkdir(agentsDir, { recursive: true });
+
   await writeFile(plistPath, plist, { mode: 0o600 });
+  await chmod(plistPath, 0o600);
   while (true) {
     const stdoutOffset = await fileLength(stdoutPath);
     const stderrOffset = await fileLength(stderrPath);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "askshepherd",
-  "version": "0.1.38",
+  "version": "0.1.40",
   "description": "Customer-facing Shepherd production onboarding and MCP CLI",
   "type": "module",
   "bin": {