@signal4/s4 2.6.1 → 2.7.0

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;AA8CD,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,CA4CrF;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"}

package/dist/speed.js

@@ -0,0 +1,196 @@
+/** 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. */
+const INSTANT_MAX = 0.5;
+const FAST_MAX = 2.5;
+/** Responses that took longer than this say how long. */
+export const REPORT_ELAPSED_OVER_S = 2.5;
+const EMBED_S = 1.0;
+export function tierOf(lo, hi) {
+    const typical = Math.sqrt(Math.max(lo, 0.01) * Math.max(hi, 0.01));
+    if (typical < INSTANT_MAX)
+        return "instant";
+    if (typical <= FAST_MAX)
+        return "fast";
+    return "slow";
+}
+function est(lo, hi, why) {
+    return { tier: tierOf(lo, hi), lo, hi, why };
+}
+/** Fixed-cost tools: [lo, hi] seconds from the replay (p50-ish, p90). */
+const BASE = {
+    get_segment: [0.1, 0.2],
+    get_segment_sentences: [0.1, 0.3],
+    get_thread: [0.1, 0.4],
+    get_claim: [0.1, 0.4],
+    list_collections: [0.1, 0.3],
+    manage_bookmarks: [0.1, 0.4],
+    find_speakers: [0.2, 0.8],
+    get_platform_stats: [0.2, 1],
+    get_collection_stats: [0.2, 1],
+    get_project_stats: [0.2, 1],
+    get_speaker: [0.2, 2.5],
+    claim_graph: [0.3, 1.6],
+    get_channel: [0.3, 1.2],
+    get_episode: [0.5, 2],
+    channel_dossier: [0.5, 1.6],
+    compare_channels: [0.7, 1.5],
+    get_top_channels: [0.5, 2.5],
+    analyze_claims: [0.8, 2.3],
+    contradict_claims: [0.8, 4.4],
+    compare_claims: [0.8, 4],
+    check_channel_contradictions: [0.8, 4],
+    find_entities: [0.8, 3.2],
+    trend_claims: [1, 3.5],
+    get_top_speakers: [1.5, 3.5],
+    get_speaker_network: [1, 5],
+    get_ad_analytics: [0.5, 3],
+    entity_claims: [1.5, 10],
+    top_claims: [2, 8],
+    get_topics: [3, 19],
+    // Paid LLM pipelines (their own descriptions carry these ranges).
+    get_briefing: [2, 10],
+    analyze_topic: [15, 45],
+    compare_speakers: [15, 45],
+    build_dossier: [15, 45],
+    check_contradictions: [15, 45],
+    compare_frames: [30, 60],
+};
+/** Window length in months from days / start_date / end_date (YYYY, YYYY-MM, YYYY-MM-DD). */
+export function windowMonths(params, defaultDays = 30) {
+    const today = Date.now();
+    const parse = (v, edge) => {
+        if (typeof v !== "string" || !v)
+            return undefined;
+        const m = /^(\d{4})(?:-(\d{2}))?(?:-(\d{2}))?$/.exec(v.trim());
+        if (!m)
+            return undefined;
+        const y = Number(m[1]);
+        const mo = m[2] ? Number(m[2]) - 1 : edge === "start" ? 0 : 11;
+        const d = m[3] ? Number(m[3]) : edge === "start" ? 1 : 28;
+        return Date.UTC(y, mo, d);
+    };
+    const start = parse(params.start_date, "start");
+    const end = parse(params.end_date, "end") ?? today;
+    const days = start != null
+        ? (end - start) / 86400000
+        : Number(params.days ?? params.baseline_days ?? defaultDays) || defaultDays;
+    return Math.max(days / 30.4, 0.25);
+}
+/** Whole-corpus semantic scan cost for a window: ~0.2–0.35s per month up to two years,
+ * thin before that. Measured on the VPS: 1 month 0.2–0.7s, 12 months 2.4–3.6s, all time 5–8s. */
+function scanCost(months) {
+    const recent = Math.min(months, 24);
+    const older = Math.max(months - 24, 0);
+    const lo = 0.2 + 0.15 * recent;
+    // All time measured 4.7s warm, 7–8.5s just after cache churn (signal4#238).
+    const hi = Math.min(0.8 + 0.35 * recent + 0.02 * older, 9);
+    return [lo, hi];
+}
+function monthsLabel(months) {
+    if (months >= 120)
+        return "all time";
+    if (months >= 23)
+        return `${Math.round(months / 12)} years`;
+    if (months >= 1.5)
+        return `${Math.round(months)} months`;
+    return `${Math.max(1, Math.round(months * 30.4))} days`;
+}
+/** The estimate for one call. Unknown tools are "fast" with a wide range. */
+export function estimate(tool, params = {}) {
+    const speaker = params.speaker ?? params.speaker_name ?? params.speaker_id;
+    const keyword = params.mode === "keyword" || typeof params.keyword === "string";
+    switch (tool) {
+        case "search_quotes": {
+            if (params.full_history)
+                return est(2, 15, "exact scan of a speaker's whole history");
+            const m = windowMonths(params);
+            if (keyword) {
+                return est(0.3, speaker ? 4 : 1.5, `keyword search, newest first, ${monthsLabel(m)}`);
+            }
+            if (!params.topic)
+                return est(0.2, 2, "listing by speaker or channel");
+            const [lo, hi] = scanCost(m);
+            return est(EMBED_S + lo, EMBED_S + hi + 0.5 + (speaker ? 4 : 0), `semantic search over ${monthsLabel(m)}${speaker ? " for one speaker" : ""}`);
+        }
+        case "count_mentions": {
+            const m = windowMonths(params);
+            if (keyword) {
+                const hi = m <= 3 ? 2 : m <= 12 ? 6 : 15;
+                return est(0.3, hi + (speaker ? 6 : 0), `exact keyword count over ${monthsLabel(m)} (very common words take longest)`);
+            }
+            if (!params.topic && !params.topics)
+                return est(0.3, m <= 3 ? 2 : 8, `count of everything in scope over ${monthsLabel(m)}`);
+            const [lo, hi] = scanCost(m);
+            return est(EMBED_S + lo, EMBED_S + hi + (speaker ? 10 : 0), `semantic count over ${monthsLabel(m)}${speaker ? " for one speaker" : ""}`);
+        }
+        case "get_timeline":
+        case "detect_trend": {
+            const m = windowMonths(params, tool === "detect_trend" ? Number(params.baseline_days ?? 30) || 30 : 30);
+            const [lo, hi] = scanCost(m);
+            return est(EMBED_S + lo, EMBED_S + hi + (speaker ? 10 : 0), `semantic count over ${monthsLabel(m)}`);
+        }
+        case "search_claims": {
+            if (params.entity)
+                return est(5, 25, "claims search filtered by entity");
+            if (keyword)
+                return est(0.3, 2, "claims keyword search");
+            return est(1.5, 10, "semantic claims search");
+        }
+        default: {
+            const b = BASE[tool];
+            return b ? est(b[0], b[1]) : est(0.5, 5);
+        }
+    }
+}
+/** 0.1–0.9 to one decimal, 1–10 to the half second, then whole seconds. */
+function secs(n) {
+    if (n < 1)
+        return Math.max(n, 0.1).toFixed(1);
+    return n < 10 ? String(Math.round(n * 2) / 2) : String(Math.round(n));
+}
+/** "instant" · "fast ~1–2s" · "slow ~3–8s". */
+export function label(e) {
+    if (e.tier === "instant")
+        return "instant";
+    return `${e.tier} ~${secs(e.lo)}–${secs(e.hi)}s`;
+}
+/** 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 function descriptionTag(tool, paid = false) {
+    const windowed = ["search_quotes", "count_mentions", "get_timeline", "detect_trend"].includes(tool);
+    // The usual call: a topic, default (30-day) window, semantic.
+    const base = estimate(tool, windowed ? { topic: "x" } : {});
+    let scale = "";
+    if (windowed) {
+        const year = estimate(tool, { days: 365, topic: "x" });
+        const all = estimate(tool, { start_date: "2010", topic: "x" });
+        scale = `; 12 months ${label(year).replace(/^\w+ /, "")}, all time ${label(all).replace(/^\w+ /, "")}`;
+    }
+    return `[${label(base)}${scale}${paid ? " · paid LLM" : ""}]`;
+}
+/** Replace the speed/price bracket a backend description starts with by ours,
+ * keeping the paid marker. */
+export function decorateDescription(tool, description) {
+    const m = /^\[([^\]]*)\]\s*/.exec(description);
+    const paid = m ? /paid/i.test(m[1]) : false;
+    const rest = m ? description.slice(m[0].length) : description;
+    return `${descriptionTag(tool, paid)} ${rest}`;
+}
+/** The notice a slow call sends before it starts (MCP progress, CLI stderr). */
+export function startNotice(e) {
+    return `Estimated ${secs(e.lo)}–${secs(e.hi)}s${e.why ? `: ${e.why}` : ""}.`;
+}
+/** Footer for a response that took longer than REPORT_ELAPSED_OVER_S. */
+export function elapsedFooter(ms) {
+    return ms / 1000 > REPORT_ELAPSED_OVER_S ? `\n_Took ${(ms / 1000).toFixed(1)}s._` : "";
+}
+//# sourceMappingURL=speed.js.map

package/dist/speed.js.map

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

package/dist/surface.d.ts

@@ -0,0 +1,7 @@
+/** Which front end is rendering: next-step hints use CLI or MCP call syntax. */
+export type Surface = "cli" | "mcp";
+export declare function setSurface(s: Surface): void;
+export declare function getSurface(): Surface;
+/** Rewrite an MCP-style call hint (`get_segment seg:42`, `offset:20`) to CLI syntax when running as the CLI. */
+export declare function hint(mcp: string): string;
+//# sourceMappingURL=surface.d.ts.map

package/dist/surface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"surface.d.ts","sourceRoot":"","sources":["../src/surface.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAEhF,MAAM,MAAM,OAAO,GAAG,KAAK,GAAG,KAAK,CAAC;AAIpC,wBAAgB,UAAU,CAAC,CAAC,EAAE,OAAO,GAAG,IAAI,CAAiB;AAC7D,wBAAgB,UAAU,IAAI,OAAO,CAAoB;AAEzD,gHAAgH;AAChH,wBAAgB,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAUxC"}

package/dist/surface.js

@@ -0,0 +1,18 @@
+/** Which front end is rendering: next-step hints use CLI or MCP call syntax. */
+let current = "mcp";
+export function setSurface(s) { current = s; }
+export function getSurface() { return current; }
+/** Rewrite an MCP-style call hint (`get_segment seg:42`, `offset:20`) to CLI syntax when running as the CLI. */
+export function hint(mcp) {
+    if (current !== "cli")
+        return mcp;
+    return mcp
+        .replace(/get_segment seg:(\d+)/g, "s4 segment $1")
+        .replace(/get_speaker speaker_id:(\d+)/g, "s4 speaker $1")
+        .replace(/get_claim claim:(\d+)( include_observations:true)?/g, (_m, id, o) => `s4 claim ${id}${o ? " --observations" : ""}`)
+        .replace(/get_thread segment_id:(\d+)( max_chars:0)?/g, "s4 thread $1")
+        .replace(/get_episode content_id:(\S+?)( include_transcript:true)?(?=$|[\s·\]])/g, (_m, id, t) => `s4 episode ${id}${t ? " --transcript" : ""}`)
+        .replace(/search_quotes topic:("[^"]*") start_date:(\S+)/g, "s4 search $1 --since $2")
+        .replace(/\boffset:(\d+)/g, "--offset $1");
+}
+//# sourceMappingURL=surface.js.map

package/dist/surface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"surface.js","sourceRoot":"","sources":["../src/surface.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAIhF,IAAI,OAAO,GAAY,KAAK,CAAC;AAE7B,MAAM,UAAU,UAAU,CAAC,CAAU,IAAU,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC;AAC7D,MAAM,UAAU,UAAU,KAAc,OAAO,OAAO,CAAC,CAAC,CAAC;AAEzD,gHAAgH;AAChH,MAAM,UAAU,IAAI,CAAC,GAAW;IAC9B,IAAI,OAAO,KAAK,KAAK;QAAE,OAAO,GAAG,CAAC;IAClC,OAAO,GAAG;SACP,OAAO,CAAC,wBAAwB,EAAE,eAAe,CAAC;SAClD,OAAO,CAAC,+BAA+B,EAAE,eAAe,CAAC;SACzD,OAAO,CAAC,qDAAqD,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,YAAY,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;SAC5H,OAAO,CAAC,6CAA6C,EAAE,cAAc,CAAC;SACtE,OAAO,CAAC,wEAAwE,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,cAAc,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;SAC/I,OAAO,CAAC,iDAAiD,EAAE,yBAAyB,CAAC;SACrF,OAAO,CAAC,iBAAiB,EAAE,aAAa,CAAC,CAAC;AAC/C,CAAC"}