@signal4/s4 2.6.1 → 2.8.0

package/dist/handlers/timeline.js

@@ -1,22 +1,25 @@
 /** Timeline handler: get_timeline */
 import * as client from "../client.js";
 import { formatTimeline } from "../format.js";
-import { mcpWindowFooter } from "../provenance.js";
-import { wantsJson, jsonResult } from "../handler_types.js";
+import { mcpWindowFooter, scopeFooter } from "../provenance.js";
+import { wantsJson, jsonResult, collectionOf } from "../handler_types.js";
 export async function handleGetTimeline(params) {
     const topic = params.topic;
     if (!topic) {
-        return { content: [{ type: "text", text: "Error: topic is required." }] };
+        return { content: [{ type: "text", text: "Error: topic is required." }], isError: true };
     }
     const days = params.days ?? 30;
-    const startDate = params.start_date ?? new Date(Date.now() - days * 86400000).toISOString().slice(0, 10);
     const endDate = params.end_date ?? new Date().toISOString().slice(0, 10);
+    const endMs = Date.parse(endDate);
+    const startDate = params.start_date
+        ?? new Date((Number.isNaN(endMs) ? Date.now() : endMs) - days * 86400000).toISOString().slice(0, 10);
     const speakerName = (params.speaker ?? params.speaker_name);
     const channelName = (params.channel ?? params.channel_name);
     const channelNames = channelName?.split(",").map(s => s.trim()).filter(Boolean);
     const language = params.language;
     const granularity = params.granularity ?? "day";
     const minSimilarity = params.min_similarity;
+    const project = collectionOf(params);
     const data = await client.getTimeline({
         topic,
         speaker_name: speakerName,
@@ -26,14 +29,17 @@ export async function handleGetTimeline(params) {
         language,
         granularity,
         min_similarity: minSimilarity,
+        project,
     });
     if (wantsJson(params))
         return jsonResult(data);
+    const explicit = params.start_date != null || params.end_date != null;
     const footer = mcpWindowFooter({
-        startDate, endDate,
-        days: params.start_date == null ? days : undefined,
-        defaultWindow: params.start_date == null && params.days == null,
+        startDate: data.window?.start_date ?? startDate,
+        endDate: data.window?.end_date ?? endDate,
+        days: explicit ? undefined : days,
+        defaultWindow: !explicit && params.days == null,
     });
-    return { content: [{ type: "text", text: formatTimeline(data, footer) }] };
+    return { content: [{ type: "text", text: formatTimeline(data, footer + scopeFooter(data.scope, project)) }] };
 }
 //# sourceMappingURL=timeline.js.map

package/dist/handlers/timeline.js.map

@@ -1 +1 @@
-{"version":3,"file":"timeline.js","sourceRoot":"","sources":["../../src/handlers/timeline.ts"],"names":[],"mappings":"AAAA,qCAAqC;AAErC,OAAO,KAAK,MAAM,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAG5D,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,MAA+B;IACrE,MAAM,KAAK,GAAG,MAAM,CAAC,KAAe,CAAC;IACrC,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,2BAA2B,EAAE,CAAC,EAAE,CAAC;IAC5E,CAAC;IAED,MAAM,IAAI,GAAI,MAAM,CAAC,IAAe,IAAI,EAAE,CAAC;IAC3C,MAAM,SAAS,GAAI,MAAM,CAAC,UAAqB,IAAI,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,GAAG,QAAQ,CAAC,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACrH,MAAM,OAAO,GAAI,MAAM,CAAC,QAAmB,IAAI,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACrF,MAAM,WAAW,GAAG,CAAC,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,YAAY,CAAuB,CAAC;IAClF,MAAM,WAAW,GAAG,CAAC,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,YAAY,CAAuB,CAAC;IAClF,MAAM,YAAY,GAAG,WAAW,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAChF,MAAM,QAAQ,GAAG,MAAM,CAAC,QAA8B,CAAC;IACvD,MAAM,WAAW,GAAI,MAAM,CAAC,WAAsB,IAAI,KAAK,CAAC;IAC5D,MAAM,aAAa,GAAG,MAAM,CAAC,cAAoC,CAAC;IAElE,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC;QACpC,KAAK;QACL,YAAY,EAAE,WAAW;QACzB,aAAa,EAAE,YAAY;QAC3B,UAAU,EAAE,SAAS;QACrB,QAAQ,EAAE,OAAO;QACjB,QAAQ;QACR,WAAW;QACX,cAAc,EAAE,aAAa;KAC9B,CAAC,CAAC;IAEH,IAAI,SAAS,CAAC,MAAM,CAAC;QAAE,OAAO,UAAU,CAAC,IAAI,CAAC,CAAC;IAE/C,MAAM,MAAM,GAAG,eAAe,CAAC;QAC7B,SAAS,EAAE,OAAO;QAClB,IAAI,EAAE,MAAM,CAAC,UAAU,IAAI,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS;QAClD,aAAa,EAAE,MAAM,CAAC,UAAU,IAAI,IAAI,IAAI,MAAM,CAAC,IAAI,IAAI,IAAI;KAChE,CAAC,CAAC;IACH,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC;AAC7E,CAAC"}
+{"version":3,"file":"timeline.js","sourceRoot":"","sources":["../../src/handlers/timeline.ts"],"names":[],"mappings":"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"}

package/dist/http.js

@@ -17,7 +17,7 @@ import { createServer } from "node:http";
 import { parseArgs } from "node:util";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { withApiKey } from "./client.js";
-import { buildServer, CachedManifest } from "./server_core.js";
+import { buildServer, CachedManifest, loadInstructions } from "./server_core.js";
 // ---------------------------------------------------------------------------
 // Per-key manifest cache
 //
@@ -80,17 +80,19 @@ async function handleMcpRequest(req, res) {
         sendJson(res, 401, { detail: "Invalid API key format. Signal4 keys start with 'sk_'." });
         return;
     }
-    const server = buildServer(manifestFor(key));
+    const provider = manifestFor(key);
     const transport = new StreamableHTTPServerTransport({
         sessionIdGenerator: undefined, // stateless mode
     });
+    let server;
     res.on("close", () => {
         void transport.close();
-        void server.close();
+        void server?.close();
     });
     // Everything the MCP handlers do — manifest fetch, tool handler backend
     // calls — runs inside this key's context, so client.ts sends THIS key.
     await withApiKey(key, async () => {
+        server = buildServer(provider, await loadInstructions(provider));
         await server.connect(transport);
         await transport.handleRequest(req, res);
     });
@@ -129,4 +131,24 @@ httpServer.listen(port, args.host, () => {
     console.log(`Signal4 MCP (streamable-http) listening on http://${args.host}:${port}/mcp ` +
         `(backend: ${process.env.SIGNAL4_API_URL ?? "https://api.signal4.ca"})`);
 });
+// ---------------------------------------------------------------------------
+// Graceful stop
+// ---------------------------------------------------------------------------
+// Deploys restart one MCP instance at a time behind Caddy (signal4#306). On
+// SIGINT/SIGTERM stop accepting — Caddy sends new requests to the other
+// instance — and let in-flight tool calls finish (a paid analysis can run for
+// minutes) before exiting. Node's default was to die mid-response. PM2's
+// kill_timeout (160s) is the backstop above this 150s cap.
+let stopping = false;
+function shutdown(signal) {
+    if (stopping)
+        return;
+    stopping = true;
+    console.log(`Received ${signal}: finishing in-flight requests, then exiting`);
+    httpServer.close(() => process.exit(0));
+    httpServer.closeIdleConnections();
+    setTimeout(() => process.exit(0), 150_000).unref();
+}
+process.on("SIGINT", shutdown);
+process.on("SIGTERM", shutdown);
 //# sourceMappingURL=http.js.map

package/dist/http.js.map

@@ -1 +1 @@
-{"version":3,"file":"http.js","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,YAAY,EAA6C,MAAM,WAAW,CAAC;AACpF,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,6BAA6B,EAAE,MAAM,oDAAoD,CAAC;AACnG,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,gBAAgB,EAAyB,MAAM,kBAAkB,CAAC;AAExG,8EAA8E;AAC9E,yBAAyB;AACzB,EAAE;AACF,0EAA0E;AAC1E,yEAAyE;AACzE,wEAAwE;AACxE,gDAAgD;AAChD,8EAA8E;AAE9E,MAAM,eAAe,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AACvC,MAAM,kBAAkB,GAAG,GAAG,CAAC;AAE/B,MAAM,aAAa,GAAG,IAAI,GAAG,EAA0B,CAAC;AAExD,SAAS,WAAW,CAAC,GAAW;IAC9B,MAAM,IAAI,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC5D,IAAI,KAAK,GAAG,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACpC,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,KAAK,GAAG,IAAI,cAAc,CAAC,EAAE,KAAK,EAAE,eAAe,EAAE,CAAC,CAAC;QACvD,IAAI,aAAa,CAAC,IAAI,IAAI,kBAAkB,EAAE,CAAC;YAC7C,sEAAsE;YACtE,iEAAiE;YACjE,MAAM,MAAM,GAAG,aAAa,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC;YACjD,IAAI,MAAM,KAAK,SAAS;gBAAE,aAAa,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QACzD,CAAC;IACH,CAAC;SAAM,CAAC;QACN,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,qCAAqC;IACnE,CAAC;IACD,aAAa,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IAC/B,OAAO,KAAK,CAAC;AACf,CAAC;AAED,8EAA8E;AAC9E,oEAAoE;AACpE,8EAA8E;AAE9E,SAAS,aAAa,CAAC,GAAoB;IACzC,MAAM,SAAS,GAAG,GAAG,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IAC3C,IAAI,OAAO,SAAS,KAAK,QAAQ,IAAI,SAAS;QAAE,OAAO,SAAS,CAAC,IAAI,EAAE,CAAC;IACxE,MAAM,IAAI,GAAG,GAAG,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC;IAC1C,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QACzE,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAC9B,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,QAAQ,CAAC,GAAmB,EAAE,MAAc,EAAE,IAAa;IAClE,GAAG,CAAC,SAAS,CAAC,MAAM,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,CAAC,CAAC;IAC9D,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC;AAChC,CAAC;AAED,8EAA8E;AAC9E,mEAAmE;AACnE,8EAA8E;AAE9E,KAAK,UAAU,gBAAgB,CAAC,GAAoB,EAAE,GAAmB;IACvE,MAAM,GAAG,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC;IAC/B,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,QAAQ,CAAC,GAAG,EAAE,GAAG,EAAE;YACjB,MAAM,EAAE,kFAAkF;SAC3F,CAAC,CAAC;QACH,OAAO;IACT,CAAC;IACD,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;QAC3B,QAAQ,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,MAAM,EAAE,wDAAwD,EAAE,CAAC,CAAC;QACzF,OAAO;IACT,CAAC;IAED,MAAM,QAAQ,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;IAClC,MAAM,SAAS,GAAG,IAAI,6BAA6B,CAAC;QAClD,kBAAkB,EAAE,SAAS,EAAE,iBAAiB;KACjD,CAAC,CAAC;IACH,IAAI,MAAkD,CAAC;IACvD,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE;QACnB,KAAK,SAAS,CAAC,KAAK,EAAE,CAAC;QACvB,KAAK,MAAM,EAAE,KAAK,EAAE,CAAC;IACvB,CAAC,CAAC,CAAC;IAEH,wEAAwE;IACxE,uEAAuE;IACvE,MAAM,UAAU,CAAC,GAAG,EAAE,KAAK,IAAI,EAAE;QAC/B,MAAM,GAAG,WAAW,CAAC,QAAQ,EAAE,MAAM,gBAAgB,CAAC,QAAQ,CAAC,CAAC,CAAC;QACjE,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QAChC,MAAM,SAAS,CAAC,aAAa,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IAC1C,CAAC,CAAC,CAAC;AACL,CAAC;AAED,8EAA8E;AAC9E,cAAc;AACd,8EAA8E;AAE9E,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,SAAS,CAAC;IACjC,OAAO,EAAE;QACP,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,WAAW,EAAE;QAC9C,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE;KAC1C;CACF,CAAC,CAAC;AAEH,MAAM,UAAU,GAAG,YAAY,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE;IAC3C,MAAM,IAAI,GAAG,CAAC,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IAE5C,IAAI,GAAG,CAAC,MAAM,KAAK,KAAK,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QAC/C,QAAQ,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC,CAAC;QAChF,OAAO;IACT,CAAC;IAED,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;QACpB,gBAAgB,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;YACvC,OAAO,CAAC,KAAK,CAAC,qBAAqB,EAAE,GAAG,CAAC,CAAC;YAC1C,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC;gBACrB,QAAQ,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,MAAM,EAAE,uBAAuB,EAAE,CAAC,CAAC;YAC1D,CAAC;iBAAM,CAAC;gBACN,GAAG,CAAC,GAAG,EAAE,CAAC;YACZ,CAAC;QACH,CAAC,CAAC,CAAC;QACH,OAAO;IACT,CAAC;IAED,QAAQ,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC,CAAC;AAC9C,CAAC,CAAC,CAAC;AAEH,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC/B,UAAU,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,GAAG,EAAE;IACtC,OAAO,CAAC,GAAG,CACT,qDAAqD,IAAI,CAAC,IAAI,IAAI,IAAI,OAAO;QAC7E,aAAa,OAAO,CAAC,GAAG,CAAC,eAAe,IAAI,wBAAwB,GAAG,CACxE,CAAC;AACJ,CAAC,CAAC,CAAC;AAEH,8EAA8E;AAC9E,gBAAgB;AAChB,8EAA8E;AAE9E,4EAA4E;AAC5E,wEAAwE;AACxE,8EAA8E;AAC9E,yEAAyE;AACzE,2DAA2D;AAC3D,IAAI,QAAQ,GAAG,KAAK,CAAC;AACrB,SAAS,QAAQ,CAAC,MAAsB;IACtC,IAAI,QAAQ;QAAE,OAAO;IACrB,QAAQ,GAAG,IAAI,CAAC;IAChB,OAAO,CAAC,GAAG,CAAC,YAAY,MAAM,8CAA8C,CAAC,CAAC;IAC9E,UAAU,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IACxC,UAAU,CAAC,oBAAoB,EAAE,CAAC;IAClC,UAAU,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,KAAK,EAAE,CAAC;AACrD,CAAC;AACD,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;AAC/B,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC"}

package/dist/index.js

@@ -8,7 +8,7 @@
  */
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { applyConfig } from "./config.js";
-import { buildServer, CachedManifest } from "./server_core.js";
+import { buildServer, CachedManifest, loadInstructions } from "./server_core.js";
 applyConfig();
 // Single global manifest cache keyed by the env key, cached for the session.
 const manifest = new CachedManifest({
@@ -17,8 +17,8 @@ const manifest = new CachedManifest({
         : "SIGNAL4_API_KEY environment variable is not set. " +
             "Get your API key from Signal4 and set it in your MCP server config.",
 });
-const server = buildServer(manifest);
 async function main() {
+    const server = buildServer(manifest, await loadInstructions(manifest));
     const transport = new StdioServerTransport();
     await server.connect(transport);
     // Eagerly fetch manifest so tools/list is populated on first call.

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAE/D,WAAW,EAAE,CAAC;AAEd,6EAA6E;AAC7E,MAAM,QAAQ,GAAG,IAAI,cAAc,CAAC;IAClC,iBAAiB,EAAE,GAAG,EAAE,CACtB,OAAO,CAAC,GAAG,CAAC,eAAe;QACzB,CAAC,CAAC,IAAI;QACN,CAAC,CAAC,mDAAmD;YACnD,qEAAqE;CAC5E,CAAC,CAAC;AAEH,MAAM,MAAM,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC;AAErC,KAAK,UAAU,IAAI;IACjB,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAEhC,mEAAmE;IACnE,qEAAqE;IACrE,kCAAkC;IAClC,IAAI,CAAC;QACH,MAAM,QAAQ,CAAC,KAAK,EAAE,CAAC;QACvB,MAAM,CAAC,MAAM,CAAC,mBAAmB,EAAE,CAAC;IACtC,CAAC;IAAC,MAAM,CAAC;QACP,sCAAsC;IACxC,CAAC;AACH,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACnB,OAAO,CAAC,KAAK,CAAC,qCAAqC,EAAE,GAAG,CAAC,CAAC;IAC1D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEjF,WAAW,EAAE,CAAC;AAEd,6EAA6E;AAC7E,MAAM,QAAQ,GAAG,IAAI,cAAc,CAAC;IAClC,iBAAiB,EAAE,GAAG,EAAE,CACtB,OAAO,CAAC,GAAG,CAAC,eAAe;QACzB,CAAC,CAAC,IAAI;QACN,CAAC,CAAC,mDAAmD;YACnD,qEAAqE;CAC5E,CAAC,CAAC;AAEH,KAAK,UAAU,IAAI;IACjB,MAAM,MAAM,GAAG,WAAW,CAAC,QAAQ,EAAE,MAAM,gBAAgB,CAAC,QAAQ,CAAC,CAAC,CAAC;IACvE,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAEhC,mEAAmE;IACnE,qEAAqE;IACrE,kCAAkC;IAClC,IAAI,CAAC;QACH,MAAM,QAAQ,CAAC,KAAK,EAAE,CAAC;QACvB,MAAM,CAAC,MAAM,CAAC,mBAAmB,EAAE,CAAC;IACtC,CAAC;IAAC,MAAM,CAAC;QACP,sCAAsC;IACxC,CAAC;AACH,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACnB,OAAO,CAAC,KAAK,CAAC,qCAAqC,EAAE,GAAG,CAAC,CAAC;IAC1D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/provenance.d.ts

@@ -7,6 +7,7 @@
  * thin results inside a default window are indistinguishable from a thin
  * corpus otherwise.
  */
+import type { DateWindowEcho, SearchScope } from "./types.js";
 /** The concrete calendar window a days-based endpoint actually covered. */
 export declare function windowFromDays(days: number): {
     startDate: string;
@@ -14,8 +15,7 @@ export declare function windowFromDays(days: number): {
 };
 /**
  * One-line footer stating the date range a tool actually searched, in MCP
- * parameter vocabulary (`days` / `start_date`), matching the style of
- * format.ts's windowFooter.
+ * parameter vocabulary (`days` / `start_date`).
  */
 export declare function mcpWindowFooter(opts: {
     startDate?: string;
@@ -29,6 +29,16 @@ export declare function mcpWindowFooter(opts: {
     /** True for endpoints that only take `days` (no start_date parameter). */
     daysOnly?: boolean;
 }): string;
+/**
+ * Footer for a tool that takes `days` OR `start_date`/`end_date` (signal4#226).
+ * Explicit dates win and are stated as the backend echoed them (`echo`, inclusive
+ * end) when it did; otherwise the rolling `days` window is stated.
+ */
+export declare function dateWindowFooter(params: Record<string, unknown>, opts: {
+    days: number;
+    echo?: DateWindowEcho;
+    maxDays?: number;
+}): string;
 /** For endpoints with no time filter at all (e.g. entity_claims). */
 export declare function allTimeFooter(): string;
 /**
@@ -38,4 +48,21 @@ export declare function allTimeFooter(): string;
  * (i.e. the emptiness is about the topic/window, not the name).
  */
 export declare function speakerEmptyStateNote(name: string): Promise<string | undefined>;
+/**
+ * One-line footer stating the CORPUS SCOPE a tool actually searched.
+ *
+ * Sibling of `mcpWindowFooter`: that one bounds the search in time, this one
+ * bounds it in corpus. Both exist for the same reason — a thin result set is
+ * indistinguishable from a thin corpus unless the response says what it looked
+ * at. Until signal4-core#563 the MCP client sent `project="Big_Channels"` on
+ * nearly every search and said nothing about it, so a caller asking "who in
+ * American media discussed X" searched a curated subset of American media and
+ * had no way to find that out. Roughly three quarters of a recall gap an
+ * external client reported as a keyword-mode bug was this default.
+ *
+ * Prefer the API's own `scope` — it knows about dashboard aliases and API-key
+ * restrictions, which the client cannot see. `sentProject` is the fallback for
+ * a backend that predates the `scope` field.
+ */
+export declare function scopeFooter(scope?: SearchScope, sentProject?: string): string;
 //# sourceMappingURL=provenance.d.ts.map

package/dist/provenance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provenance.d.ts","sourceRoot":"","sources":["../src/provenance.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,2EAA2E;AAC3E,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAKnF;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE;IACpC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8EAA8E;IAC9E,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,GAAG,MAAM,CAUT;AAED,qEAAqE;AACrE,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED;;;;;GAKG;AACH,wBAAsB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAgBrF"}
+{"version":3,"file":"provenance.d.ts","sourceRoot":"","sources":["../src/provenance.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9D,2EAA2E;AAC3E,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAKnF;AAgBD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE;IACpC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8EAA8E;IAC9E,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,GAAG,MAAM,CAgBT;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,cAAc,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAC9D,MAAM,CASR;AAED,qEAAqE;AACrE,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED;;;;;GAKG;AACH,wBAAsB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAgBrF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CAAC,KAAK,CAAC,EAAE,WAAW,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,CAI7E"}

package/dist/provenance.js

@@ -15,10 +15,25 @@ export function windowFromDays(days) {
         endDate: new Date().toISOString().slice(0, 10),
     };
 }
+/**
+ * True when `days` genuinely describes the [startDate, endDate] span, so the
+ * footer may say "(N days)". One day of slack absorbs the caller's own
+ * `Date.now() - days * 86400000` rounding and any UTC-vs-local date boundary.
+ */
+function spanMatchesDays(startDate, endDate, days) {
+    if (days == null)
+        return false;
+    if (!startDate)
+        return true; // days is all we have; the span IS the days
+    const start = Date.parse(startDate);
+    const end = endDate ? Date.parse(endDate) : Date.now();
+    if (Number.isNaN(start) || Number.isNaN(end))
+        return false;
+    return Math.abs(Math.round((end - start) / 86400000) - days) <= 1;
+}
 /**
  * One-line footer stating the date range a tool actually searched, in MCP
- * parameter vocabulary (`days` / `start_date`), matching the style of
- * format.ts's windowFooter.
+ * parameter vocabulary (`days` / `start_date`).
  */
 export function mcpWindowFooter(opts) {
     if (opts.fullHistory)
@@ -26,13 +41,34 @@ export function mcpWindowFooter(opts) {
     let { startDate, endDate } = opts;
     if (!startDate && opts.days != null)
         ({ startDate, endDate } = windowFromDays(opts.days));
-    const daysStr = opts.days != null ? ` (${opts.days} days)` : "";
+    // "(N days)" is a claim about the window we searched, so only make it when N
+    // really is that window. Callers default `days` to 30 and then override the
+    // window with an explicit start_date; printing the default anyway put
+    // "(30 days)" under results spanning twenty months, which reads as "your
+    // dates were ignored" and cost a client re-runs of correct searches (#554).
+    // Checked here rather than in each caller so no future caller can lie either.
+    const daysStr = spanMatchesDays(startDate, endDate, opts.days) ? ` (${opts.days} days)` : "";
     const span = startDate ? `${startDate} → ${endDate ?? "today"}${daysStr}` : `last ${opts.days ?? 30} days`;
-    const hint = opts.defaultWindow ? ` (default ${opts.days ?? 30}d window)` : "";
+    const hint = opts.defaultWindow && daysStr ? ` (default ${opts.days ?? 30}d window)` : "";
     const max = opts.maxDays ?? 365;
     const widen = opts.daysOnly ? `widen with days (≤${max})` : `widen with days (≤${max}) or start_date YYYY-MM-DD`;
     return `\n_Searched ${span}${hint} — older content may exist; ${widen}._`;
 }
+/**
+ * Footer for a tool that takes `days` OR `start_date`/`end_date` (signal4#226).
+ * Explicit dates win and are stated as the backend echoed them (`echo`, inclusive
+ * end) when it did; otherwise the rolling `days` window is stated.
+ */
+export function dateWindowFooter(params, opts) {
+    if (params.start_date != null || params.end_date != null) {
+        return mcpWindowFooter({
+            startDate: opts.echo?.start_date ?? params.start_date,
+            endDate: opts.echo?.end_date ?? params.end_date,
+            maxDays: opts.maxDays,
+        });
+    }
+    return mcpWindowFooter({ days: opts.days, defaultWindow: params.days == null, maxDays: opts.maxDays });
+}
 /** For endpoints with no time filter at all (e.g. entity_claims). */
 export function allTimeFooter() {
     return "\n_Searched the full claim history — this tool has no time window._";
@@ -62,4 +98,27 @@ export async function speakerEmptyStateNote(name) {
         return undefined;
     return `No speaker matching "${name}" found in the corpus. Closest names: ${names.join(", ")}. Did you mean one of these? (Pass the canonical spelling as speaker.)`;
 }
+/**
+ * One-line footer stating the CORPUS SCOPE a tool actually searched.
+ *
+ * Sibling of `mcpWindowFooter`: that one bounds the search in time, this one
+ * bounds it in corpus. Both exist for the same reason — a thin result set is
+ * indistinguishable from a thin corpus unless the response says what it looked
+ * at. Until signal4-core#563 the MCP client sent `project="Big_Channels"` on
+ * nearly every search and said nothing about it, so a caller asking "who in
+ * American media discussed X" searched a curated subset of American media and
+ * had no way to find that out. Roughly three quarters of a recall gap an
+ * external client reported as a keyword-mode bug was this default.
+ *
+ * Prefer the API's own `scope` — it knows about dashboard aliases and API-key
+ * restrictions, which the client cannot see. `sentProject` is the fallback for
+ * a backend that predates the `scope` field.
+ */
+export function scopeFooter(scope, sentProject) {
+    if (scope?.description)
+        return `\n_Scope: ${scope.description}._`;
+    if (sentProject)
+        return `\n_Scope: collection ${sentProject} — the rest of the corpus was not searched._`;
+    return "\n_Scope: full corpus (no collection filter)._";
+}
 //# sourceMappingURL=provenance.js.map

package/dist/provenance.js.map

@@ -1 +1 @@
-{"version":3,"file":"provenance.js","sourceRoot":"","sources":["../src/provenance.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,MAAM,MAAM,aAAa,CAAC;AAEtC,2EAA2E;AAC3E,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,OAAO;QACL,SAAS,EAAE,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,GAAG,QAAQ,CAAC,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC;QAC5E,OAAO,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC;KAC/C,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,IAW/B;IACC,IAAI,IAAI,CAAC,WAAW;QAAE,OAAO,uCAAuC,CAAC;IACrE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAClC,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,IAAI,IAAI,IAAI;QAAE,CAAC,EAAE,SAAS,EAAE,OAAO,EAAE,GAAG,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IAC1F,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,IAAI,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;IAChE,MAAM,IAAI,GAAG,SAAS,CAAC,CAAC,CAAC,GAAG,SAAS,MAAM,OAAO,IAAI,OAAO,GAAG,OAAO,EAAE,CAAC,CAAC,CAAC,QAAQ,IAAI,CAAC,IAAI,IAAI,EAAE,OAAO,CAAC;IAC3G,MAAM,IAAI,GAAG,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,aAAa,IAAI,CAAC,IAAI,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC;IAC/E,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,IAAI,GAAG,CAAC;IAChC,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,qBAAqB,GAAG,GAAG,CAAC,CAAC,CAAC,qBAAqB,GAAG,4BAA4B,CAAC;IACjH,OAAO,eAAe,IAAI,GAAG,IAAI,+BAA+B,KAAK,IAAI,CAAC;AAC5E,CAAC;AAED,qEAAqE;AACrE,MAAM,UAAU,aAAa;IAC3B,OAAO,qEAAqE,CAAC;AAC/E,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAC,IAAY;IACtD,IAAI,OAAO,CAAC;IACZ,IAAI,CAAC;QACH,OAAO,GAAG,MAAM,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;IACjD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC,CAAC,sDAAsD;IAC1E,CAAC;IACD,MAAM,KAAK,GAAG,OAAO;SAClB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,YAAY,CAAC;SACpC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACnC,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;QAClB,OAAO,wBAAwB,IAAI,2EAA2E,CAAC;IACjH,CAAC;IACD,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,KAAK,IAAI,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC;IAC/E,IAAI,KAAK;QAAE,OAAO,SAAS,CAAC;IAC5B,OAAO,wBAAwB,IAAI,yCAAyC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,wEAAwE,CAAC;AACvK,CAAC"}
+{"version":3,"file":"provenance.js","sourceRoot":"","sources":["../src/provenance.ts"],"names":[],"mappings":"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"}

package/dist/server_core.d.ts

@@ -36,5 +36,12 @@ export declare class CachedManifest implements ManifestProvider {
     authError(): string | null;
     fetch(): Promise<ManifestResponse>;
 }
-export declare function buildServer(provider: ManifestProvider): McpServer;
+/** Appended to the server instructions, so an agent knows how to read the speed tags. */
+export declare const SPEED_NOTE: string;
+export declare const FALLBACK_INSTRUCTIONS: string;
+/** Fetch the manifest's instructions, giving up after `ms` so startup never hangs. */
+export declare function loadInstructions(provider: ManifestProvider, ms?: number): Promise<string | undefined>;
+/** Turn a FastAPI 422 body into "parameter <loc>: <msg>". */
+export declare function translate422(raw: string): string;
+export declare function buildServer(provider: ManifestProvider, instructions?: string): McpServer;
 //# sourceMappingURL=server_core.d.ts.map

package/dist/server_core.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server_core.d.ts","sourceRoot":"","sources":["../src/server_core.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAMpE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAGpD,eAAO,MAAM,iBAAiB,QAAS,CAAC;AAExC,MAAM,WAAW,gBAAgB;IAC/B,gEAAgE;IAChE,KAAK,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAAC;IACnC,sDAAsD;IACtD,SAAS,IAAI,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED;;;;GAIG;AACH,qBAAa,cAAe,YAAW,gBAAgB;IAOnD,OAAO,CAAC,QAAQ,CAAC,IAAI;IANvB,OAAO,CAAC,QAAQ,CAAiC;IACjD,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,UAAU,CAAuB;IACzC,OAAO,CAAC,YAAY,CAAK;gBAGN,IAAI,GAAE;QACrB,8DAA8D;QAC9D,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,wEAAwE;QACxE,iBAAiB,CAAC,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;KACpC;IAGR,SAAS,IAAI,MAAM,GAAG,IAAI;IAIpB,KAAK,IAAI,OAAO,CAAC,gBAAgB,CAAC;CA6BzC;AAkDD,wBAAgB,WAAW,CAAC,QAAQ,EAAE,gBAAgB,GAAG,SAAS,CA6EjE"}
+{"version":3,"file":"server_core.d.ts","sourceRoot":"","sources":["../src/server_core.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAMpE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAIpD,eAAO,MAAM,iBAAiB,QAAS,CAAC;AAExC,MAAM,WAAW,gBAAgB;IAC/B,gEAAgE;IAChE,KAAK,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAAC;IACnC,sDAAsD;IACtD,SAAS,IAAI,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED;;;;GAIG;AACH,qBAAa,cAAe,YAAW,gBAAgB;IAOnD,OAAO,CAAC,QAAQ,CAAC,IAAI;IANvB,OAAO,CAAC,QAAQ,CAAiC;IACjD,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,UAAU,CAAuB;IACzC,OAAO,CAAC,YAAY,CAAK;gBAGN,IAAI,GAAE;QACrB,8DAA8D;QAC9D,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,wEAAwE;QACxE,iBAAiB,CAAC,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;KACpC;IAGR,SAAS,IAAI,MAAM,GAAG,IAAI;IAIpB,KAAK,IAAI,OAAO,CAAC,gBAAgB,CAAC;CA6BzC;AA6CD,yFAAyF;AACzF,eAAO,MAAM,UAAU,QAK4C,CAAC;AAEpE,eAAO,MAAM,qBAAqB,QAI+E,CAAC;AAElH,sFAAsF;AACtF,wBAAsB,gBAAgB,CAAC,QAAQ,EAAE,gBAAgB,EAAE,EAAE,SAAO,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAazG;AAID,6DAA6D;AAC7D,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAkBhD;AAED,wBAAgB,WAAW,CAAC,QAAQ,EAAE,gBAAgB,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAuGxF"}

package/dist/server_core.js

@@ -12,6 +12,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { ListToolsRequestSchema, CallToolRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import * as client from "./client.js";
 import { HANDLERS } from "./handlers/registry.js";
+import { decorateDescription, elapsedFooter, estimate, startNotice } from "./speed.js";
 export const RETRY_COOLDOWN_MS = 60_000;
 /**
  * Manifest cache with the 60s auth-failure cooldown. One instance per key
@@ -95,10 +96,57 @@ function diagnosticToolResponse(provider) {
 // ---------------------------------------------------------------------------
 // Server construction
 // ---------------------------------------------------------------------------
-const FALLBACK_INSTRUCTIONS = "Signal4 media intelligence platform. Authenticating...";
+/** Appended to the server instructions, so an agent knows how to read the speed tags. */
+export const SPEED_NOTE = "\n\nSPEED: every tool description starts with its speed at default settings — instant (<0.5s), " +
+    "fast (0.5–2.5s) or slow (>2.5s) — and, for search, counts and timelines, how it grows with the " +
+    "window (\"12 months ~3–6s, all time ~5–10s\"). A call expected to take a while sends a progress " +
+    "notice with its estimate as it starts; an answer that took over 2.5s ends with \"Took Ns\". " +
+    "Prefer a narrower window or a keyword search when time matters.";
+export const FALLBACK_INSTRUCTIONS = "Signal4 media intelligence: searchable transcripts of podcasts, YouTube and broadcasts. " +
+    "Start here: list_collections (what you can scope to), then search_quotes (topic, optional speaker/channel/days), " +
+    "then get_segment or get_thread for context. Omit `collection` to search the whole corpus. " +
+    "Results show IDs like seg:123; pass those to get_segment. Analysis tools are slow and paid: use search first.";
+/** Fetch the manifest's instructions, giving up after `ms` so startup never hangs. */
+export async function loadInstructions(provider, ms = 3000) {
+    let timer;
+    try {
+        const m = await Promise.race([
+            provider.fetch(),
+            new Promise((_, rej) => { timer = setTimeout(() => rej(new Error("manifest timeout")), ms); }),
+        ]);
+        return m.instructions || undefined;
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
 const { version: PKG_VERSION } = createRequire(import.meta.url)("../package.json");
-export function buildServer(provider) {
-    const server = new McpServer({ name: "Signal4", version: PKG_VERSION }, { instructions: FALLBACK_INSTRUCTIONS });
+/** Turn a FastAPI 422 body into "parameter <loc>: <msg>". */
+export function translate422(raw) {
+    const i = raw.indexOf("[");
+    const j = raw.indexOf("{");
+    const at = i >= 0 && (j < 0 || i < j) ? i : j;
+    if (at >= 0) {
+        try {
+            const body = JSON.parse(raw.slice(at));
+            const items = Array.isArray(body) ? body : Array.isArray(body?.detail) ? body.detail : null;
+            if (items) {
+                return items.slice(0, 3).map((e) => {
+                    const loc = Array.isArray(e.loc) ? e.loc.filter((x) => x !== "body" && x !== "query").join(".") : "";
+                    return `parameter ${loc || "?"}: ${e.msg ?? "invalid"}`;
+                }).join("; ");
+            }
+        }
+        catch { /* fall through */ }
+    }
+    // A plain-text detail (e.g. a search that ran past its time limit) is the message.
+    return raw.replace(/^[\s\S]*?HTTP 422:?\s*/, "").slice(0, 400);
+}
+export function buildServer(provider, instructions) {
+    const server = new McpServer({ name: "Signal4", version: PKG_VERSION }, { instructions: (instructions || FALLBACK_INSTRUCTIONS) + SPEED_NOTE });
     // Register tool capabilities and custom handlers on the underlying Server
     // BEFORE any .tool() call — we own the tool protocol directly so we can
     // serve raw JSON Schema from the manifest without zod conversion.
@@ -109,7 +157,8 @@ export function buildServer(provider) {
             return {
                 tools: m.tools.map((t) => ({
                     name: t.name,
-                    description: t.description,
+                    // Every description starts with how long the call takes (speed.ts).
+                    description: decorateDescription(t.name, t.description),
                     inputSchema: t.inputSchema,
                 })),
             };
@@ -118,7 +167,7 @@ export function buildServer(provider) {
             return diagnosticToolList(provider);
         }
     });
-    server.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    server.server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
         try {
             const { name, arguments: args } = request.params;
             if (name === AUTH_DIAGNOSTIC_TOOL) {
@@ -140,19 +189,52 @@ export function buildServer(provider) {
                     isError: true,
                 };
             }
-            return await handler(args ?? {});
+            // A call expected to take more than a moment says so before it starts, to
+            // clients that asked for progress (an MCP progressToken).
+            const params = (args ?? {});
+            const expected = estimate(name, params);
+            const token = request.params._meta?.progressToken;
+            if (expected.tier !== "instant" && token !== undefined) {
+                await extra.sendNotification({
+                    method: "notifications/progress",
+                    params: { progressToken: token, progress: 0, message: startNotice(expected) },
+                }).catch(() => { });
+            }
+            const started = Date.now();
+            const result = await handler(params);
+            // A slow answer says how long it took, so an agent can plan the next call.
+            const footer = elapsedFooter(Date.now() - started);
+            const last = result.content[result.content.length - 1];
+            if (footer && last && !result.isError && params.response_format !== "json")
+                last.text += footer;
+            return result;
         }
         catch (err) {
             const raw = err instanceof Error ? err.message : String(err);
             let msg = raw;
-            if (/HTTP 40[13]/.test(raw)) {
+            if (/HTTP 401/.test(raw)) {
                 msg = "API key is invalid or expired. Check the SIGNAL4_API_KEY in your MCP server config.";
             }
+            else if (/HTTP 403/.test(raw)) {
+                const d = raw.replace(/^[\s\S]*?HTTP 403:?\s*/, "").trim();
+                msg = d ? `Forbidden: ${d.slice(0, 200)}` : "Forbidden: this key lacks access to that tool or collection.";
+            }
+            else if (/HTTP 400/.test(raw)) {
+                const d = raw.replace(/^[\s\S]*?HTTP 400:?\s*/, "").trim();
+                let detail = d;
+                try {
+                    const j = JSON.parse(d);
+                    if (typeof j.detail === "string")
+                        detail = j.detail;
+                }
+                catch { /* raw */ }
+                msg = detail.slice(0, 300);
+            }
             else if (/HTTP 404/.test(raw)) {
                 msg = "The requested resource was not found. Check that the ID came from a previous search or listing result.";
             }
             else if (/HTTP 422/.test(raw)) {
-                msg = raw + " Check the tool description for valid parameter types and formats.";
+                msg = translate422(raw);
             }
             else if (raw.includes("expand_query must be called before")) {
                 msg = "Analysis pipeline error — try workflow='simple_rag' or simplify your query.";

package/dist/server_core.js.map

@@ -1 +1 @@
-{"version":3,"file":"server_core.js","sourceRoot":"","sources":["../src/server_core.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"server_core.js","sourceRoot":"","sources":["../src/server_core.ts"],"names":[],"mappings":"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"}

package/dist/speed.d.ts

@@ -0,0 +1,40 @@
+/** How long a call should take — one source for tool descriptions, CLI help, the
+ * progress notice a slow call sends before it starts, and the "took Ns" footer.
+ *
+ * Tiers, by the typical time (geometric mean of the range):
+ *   instant  < 0.5s     fast  0.5–2.5s     slow  > 2.5s
+ *
+ * Every number is measured, not guessed: the 100-plan replay against the live API
+ * (2026-10-15/16, ~/logs/search_eval/replay-2026-10-15.jsonl — per-tool p50/p90) and the
+ * VPS before/after runs for the counting engine (signal4#292, #296). Semantic tools pay
+ * ~1s for the query embedding before they scan; a scan costs roughly 0.15–0.35s per
+ * month of window over the whole corpus. Update the table when a tool gets faster. */
+export type Tier = "instant" | "fast" | "slow";
+export interface Estimate {
+    tier: Tier;
+    /** seconds */
+    lo: number;
+    hi: number;
+    /** what drives the time, for the progress notice (e.g. "semantic scan over 12 months") */
+    why?: string;
+}
+/** Responses that took longer than this say how long. */
+export declare const REPORT_ELAPSED_OVER_S = 2.5;
+export declare function tierOf(lo: number, hi: number): Tier;
+/** Window length in months from days / start_date / end_date (YYYY, YYYY-MM, YYYY-MM-DD). */
+export declare function windowMonths(params: Record<string, unknown>, defaultDays?: number): number;
+/** The estimate for one call. Unknown tools are "fast" with a wide range. */
+export declare function estimate(tool: string, params?: Record<string, unknown>): Estimate;
+/** "instant" · "fast ~1–2s" · "slow ~3–8s". */
+export declare function label(e: Estimate): string;
+/** The speed line a tool description starts with, e.g. "[slow ~15–45s · paid LLM]".
+ * Tools whose time depends on the window carry a short scale ("…; 12 months ~3–6s"). */
+export declare function descriptionTag(tool: string, paid?: boolean): string;
+/** Replace the speed/price bracket a backend description starts with by ours,
+ * keeping the paid marker. */
+export declare function decorateDescription(tool: string, description: string): string;
+/** The notice a slow call sends before it starts (MCP progress, CLI stderr). */
+export declare function startNotice(e: Estimate): string;
+/** Footer for a response that took longer than REPORT_ELAPSED_OVER_S. */
+export declare function elapsedFooter(ms: number): string;
+//# sourceMappingURL=speed.d.ts.map

package/dist/speed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"speed.d.ts","sourceRoot":"","sources":["../src/speed.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;sFAUsF;AAEtF,MAAM,MAAM,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,MAAM,CAAC;AAE/C,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,IAAI,CAAC;IACX,cAAc;IACd,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,0FAA0F;IAC1F,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAID,yDAAyD;AACzD,eAAO,MAAM,qBAAqB,MAAM,CAAC;AAIzC,wBAAgB,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI,CAKnD;AA+CD,6FAA6F;AAC7F,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,SAAK,GAAG,MAAM,CAiBtF;AAoBD,6EAA6E;AAC7E,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,QAAQ,CA2DrF;AAQD,+CAA+C;AAC/C,wBAAgB,KAAK,CAAC,CAAC,EAAE,QAAQ,GAAG,MAAM,CAGzC;AAED;wFACwF;AACxF,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,UAAQ,GAAG,MAAM,CAWjE;AAED;8BAC8B;AAC9B,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAK7E;AAED,gFAAgF;AAChF,wBAAgB,WAAW,CAAC,CAAC,EAAE,QAAQ,GAAG,MAAM,CAE/C;AAED,yEAAyE;AACzE,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAEhD"}