askshepherd 0.1.26 → 0.1.29

package/README.md

@@ -1,6 +1,13 @@
 # AskShepherd
 
-Customer-facing raw sync onboarding for Shepherd.
+Customer-facing production onboarding and MCP for Shepherd.
+
+The npm package is `askshepherd`. The installed binary also exposes `shepherd`,
+but the public one-liner uses the package name:
+
+```sh
+npx -y askshepherd@latest agent
+```
 
 ## Coding Agent One-liner
 
@@ -10,8 +17,8 @@ Give this to a coding agent:
 npx -y askshepherd@latest agent
 ```
 
-The command defaults to the customer-facing production Shepherd cloud. It prints the exact prompt the agent should follow, then the exact follow-up commands to open Shepherd WorkOS login/signup, guide Google Workspace Admin Console delegation, open source auth for non-Google sources, open Granola's API key page, finalize, start cloud raw polling/backfills, request downstream production processing, and install local Messages sync.
-The agent prompt tells coding agents to ask short selection questions first: existing/new org, sources to connect, and Messages skip/provide-handle. If Messages is selected, the agent runs `messages-chats`, opens a minimal searchable local webpage, and has the user select which contacts/groups to sync. Account creation/relinking always starts with Shepherd WorkOS auth.
+The command defaults to the customer-facing production Shepherd cloud. In coding-agent shells, it gives the agent the onboarding contract and follow-up commands. In a normal interactive terminal, it does not print the agent contract; it points the user to the direct terminal onboarding flow instead.
+Coding-agent onboarding asks short selection questions first: existing/new org, sources to connect, and Messages skip/provide-handle. If Messages is selected, the agent runs `messages-chats`, opens a minimal searchable local webpage, and has the user select which contacts/groups to sync. Account creation/relinking always starts with Shepherd WorkOS auth.
 Existing-organization joins are verified from Shepherd login and company email domain; the typed org name is not trusted by itself.
 
 For experiments, pass a separate non-production API explicitly:

package/bin/shepherd-onboard.js

@@ -11,7 +11,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.26";
+const PACKAGE_VERSION = "0.1.29";
 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");
@@ -283,7 +283,11 @@ async function runAgentOnboarding() {
   );
 
   if (!wantsStart) {
-    printAgentContract();
+    if (shouldPrintAgentContract()) {
+      printAgentContract();
+    } else {
+      printAgentTerminalHandoff();
+    }
     return;
   }
   if (!workosAuth) {
@@ -665,7 +669,7 @@ async function runMcpProxy() {
     { StreamableHTTPClientTransport },
     { Server },
     { StdioServerTransport },
-    { ResultSchema },
+    { CallToolRequestSchema, ListToolsRequestSchema, ResultSchema },
   ] = await Promise.all([
     import("@modelcontextprotocol/sdk/client/index.js"),
     import("@modelcontextprotocol/sdk/client/streamableHttp.js"),
@@ -673,6 +677,7 @@ async function runMcpProxy() {
     import("@modelcontextprotocol/sdk/server/stdio.js"),
     import("@modelcontextprotocol/sdk/types.js"),
   ]);
+  const proxyRequestOptions = { timeout: 240_000, resetTimeoutOnProgress: true };
 
   const remote = new Client(
     { name: "askshepherd-mcp-proxy", version: PACKAGE_VERSION },
@@ -697,13 +702,17 @@ async function runMcpProxy() {
       fallbackRequestHandler: async (request, extra) => remote.request(
         request,
         passthroughResultSchema,
-        { signal: extra.signal, timeout: 120_000, resetTimeoutOnProgress: true },
+        { ...proxyRequestOptions, signal: extra.signal },
       ),
       fallbackNotificationHandler: async (notification) => {
         await remote.notification(notification);
       },
     },
   );
+  local.setRequestHandler(ListToolsRequestSchema, async (request, extra) =>
+    remote.listTools(request.params, { ...proxyRequestOptions, signal: extra.signal }));
+  local.setRequestHandler(CallToolRequestSchema, async (request, extra) =>
+    remote.callTool(request.params, passthroughResultSchema, { ...proxyRequestOptions, signal: extra.signal }));
   await local.connect(new StdioServerTransport());
 }
 
@@ -1048,19 +1057,19 @@ function parseArgs(argv) {
 
 function printHelp(which) {
   if (which === "agent") {
-    console.log(`Shepherd coding-agent onboarding
+    console.log(`Shepherd coding-agent setup
 
 Usage:
   npx -y ${PACKAGE_NAME}@latest agent
   npx -y ${PACKAGE_NAME}@latest agent --login
   npx -y ${PACKAGE_NAME}@latest agent --name <name> --org <organization>
-  npx -y ${PACKAGE_NAME}@latest messages-chats
   npx -y ${PACKAGE_NAME}@latest agent --continue --granola-api-key <key> --messages-handle <value> --messages-chat-ids <ids>
   npx -y ${PACKAGE_NAME}@latest agent --status
+  npx -y ${PACKAGE_NAME}@latest messages-chats
   npx -y ${PACKAGE_NAME}@latest granola-api-keys
 
-Agent mode is non-interactive. It prints the user prompt and exact commands a coding agent should run.
-Always run --login first. WorkOS login/signup creates or relinks the Shepherd account before source setup; Google Workspace uses Admin Console domain-wide delegation, not WorkOS OAuth.
+The bare agent command is intended for coding-agent shells. For direct terminal setup, run:
+  npx -y ${PACKAGE_NAME}@latest
 `);
     return;
   }
@@ -1204,6 +1213,26 @@ Options:
 `);
 }
 
+function shouldPrintAgentContract() {
+  return Boolean(args.prompt || args.json || !isInteractiveTerminal());
+}
+
+function isInteractiveTerminal() {
+  return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+
+function printAgentTerminalHandoff() {
+  console.log(`Shepherd raw sync setup
+
+This command is meant for coding-agent shells. To set up Shepherd directly in this terminal, run:
+  ${agentCommand()}
+
+If a coding agent asked you to onboard Shepherd, ask the agent to run:
+  ${agentCommand()} agent
+
+No source setup has started.`);
+}
+
 function printAgentContract() {
   const command = agentCommand();
   const payload = {

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "askshepherd",
-  "version": "0.1.26",
-  "description": "Customer-facing Shepherd raw sync onboarding CLI",
+  "version": "0.1.29",
+  "description": "Customer-facing Shepherd production onboarding and MCP CLI",
   "type": "module",
   "bin": {
     "askshepherd": "bin/shepherd-onboard.js",
+    "shepherd": "bin/shepherd-onboard.js",
     "shepherd-onboard": "bin/shepherd-onboard.js"
   },
   "dependencies": {