screenpipe-mcp 0.20.2 → 0.20.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "screenpipe-mcp",
-  "version": "0.20.2",
+  "version": "0.20.3",
   "mcpName": "io.github.screenpipe/screenpipe-mcp",
   "description": "MCP server for screenpipe - search your screen recordings and audio transcriptions",
   "main": "dist/index.js",

package/scripts/build.mjs

@@ -6,6 +6,8 @@ import { rmSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import path from "node:path";
 
+await import("./gen-bundled-skills.mjs");
+
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const outdir = path.join(packageRoot, "dist");
 

package/scripts/gen-bundled-skills.mjs

@@ -0,0 +1,17 @@
+// screenpipe — AI that knows everything you've seen, said, or heard
+// https://screenpipe.com
+
+import { mkdir, writeFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+import { readBundledSkill, readStarterSkills } from "../../../scripts/lib/skill-bundle.mjs";
+
+const repoRoot = fileURLToPath(new URL("../../../", import.meta.url));
+const skills = [
+  await readBundledSkill(repoRoot, "screenpipe-api"),
+  await readBundledSkill(repoRoot, "screenpipe-cli"),
+  ...await readStarterSkills(repoRoot),
+];
+const output = path.join(repoRoot, "packages/screenpipe-mcp/src/generated/bundled-skills.ts");
+await mkdir(path.dirname(output), { recursive: true });
+await writeFile(output, `// GENERATED FILE - do not edit by hand.\n// Source: crates/screenpipe-core/assets/skills and src/starter_skills.rs\n// Regenerate: bun scripts/gen-bundled-skills.mjs\n\nexport const BUNDLED_SKILLS = ${JSON.stringify(skills, null, 2)} as const;\n`);

package/scripts/hermes-smoke.py

@@ -0,0 +1,55 @@
+# screenpipe — AI that knows everything you've seen, said, or heard
+# https://screenpipe.com
+
+"""Run with Hermes's Python: hermes-smoke.py HERMES_REPO GENERATED_CONFIG.
+Uses an isolated profile and synthetic authenticated API; no model or recording access.
+"""
+import os, sys, tempfile, threading, json
+from pathlib import Path
+from http.server import ThreadingHTTPServer, BaseHTTPRequestHandler
+from urllib.parse import urlparse, parse_qs
+root = Path(tempfile.mkdtemp(prefix='screenpipe-hermes-smoke-'))
+os.environ['HERMES_HOME'] = str(root)
+os.environ['SCREENPIPE_LOCAL_API_KEY'] = 'sp-fixture-only'
+requests = []
+reject = False
+class API(BaseHTTPRequestHandler):
+    def log_message(self, *args): pass
+    def do_GET(self):
+        requests.append({'path': self.path, 'authorized': self.headers.get('Authorization') == 'Bearer sp-fixture-only'})
+        if reject or not requests[-1]['authorized']:
+            self.send_response(401); self.end_headers(); self.wfile.write(b'{"error":"fixture authorization required"}'); return
+        self.send_response(200); self.send_header('Content-Type','application/json'); self.end_headers()
+        self.wfile.write(json.dumps({'data':[{'type':'OCR','content':{'frame_id':42,'text':'Synthetic Hermes integration acceptance','timestamp':'2026-10-02T12:30:00Z','app_name':'Fixture','window_name':'Acceptance'}}], 'pagination':{'limit':1,'offset':0,'total':1}}).encode())
+    def do_POST(self):
+        self.send_response(200); self.end_headers(); self.wfile.write(b'{}')
+api = ThreadingHTTPServer(('127.0.0.1',0), API)
+threading.Thread(target=api.serve_forever,daemon=True).start()
+os.environ['SCREENPIPE_API_URL'] = f'http://127.0.0.1:{api.server_port}'
+sys.path.insert(0, sys.argv[1])
+from tools import mcp_tool
+import yaml, shutil
+config = yaml.safe_load(Path(sys.argv[2]).read_text())['mcp_servers']
+config = {'screenpipe': config['screenpipe']}
+# Exercise the generated entry with this checkout's MCP build and a fixture API.
+# Only the executable/package location and API address differ from desktop setup.
+config['screenpipe']['command'] = shutil.which('bun')
+config['screenpipe']['args'] = [str(Path(__file__).resolve().parents[1]/'dist/cli.js')]
+config['screenpipe']['env']['SCREENPIPE_API_URL'] = os.environ['SCREENPIPE_API_URL']
+
+try:
+    names=mcp_tool.register_mcp_servers(config)
+    assert any(n.endswith('search_content') for n in names), names
+    from tools.registry import registry
+    result=registry.dispatch(next(n for n in names if n.endswith('search_content')),{'start_time':'2026-10-02T12:00:00Z','end_time':'2026-10-02T13:00:00Z','limit':1})
+    assert 'Synthetic Hermes integration acceptance' in str(result), result
+    assert '2026-10-02T12:30:00Z' in str(result), result
+    req=next(r for r in requests if '/search?' in r['path'])
+    query=parse_qs(urlparse(req['path']).query)
+    assert req['authorized'] and query['start_time']==['2026-10-02T12:00:00Z'] and query['end_time']==['2026-10-02T13:00:00Z']
+    reject = True
+    denied = registry.dispatch(next(n for n in names if n.endswith('search_content')), {'limit':1})
+    assert '401' in str(denied), denied
+    print(json.dumps({'passed':True,'tools_discovered':len(names),'authenticated_bounded_search':True,'timestamped_source_returned':True,'auth_failure_reported':True,'data':'synthetic','profile':str(root)}))
+finally:
+    mcp_tool.shutdown_mcp_servers(); api.shutdown()

package/scripts/openclaw-smoke.mjs

@@ -0,0 +1,59 @@
+// screenpipe — AI that knows everything you've seen, said, or heard
+// https://screenpipe.com
+// Run with Node >=22: node scripts/openclaw-smoke.mjs OPENCLAW_PACKAGE GENERATED_CONFIG
+// Uses OpenClaw's actual runtime, synthetic HTTP data, and an isolated state directory.
+import assert from 'node:assert/strict';
+import { createServer } from 'node:http';
+import { mkdtemp, readFile, writeFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { resolve, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { execFileSync } from 'node:child_process';
+const [openclawPackage, configPath] = process.argv.slice(2);
+assert(openclawPackage && configPath, 'provide OpenClaw package and generated config paths');
+const state = await mkdtemp(join(tmpdir(), 'screenpipe-openclaw-'));
+process.env.OPENCLAW_STATE_DIR = state;
+process.env.OPENCLAW_CONFIG_PATH = join(state, 'openclaw.json');
+let requests = [];
+const api = createServer((req, res) => {
+  if (req.headers.authorization !== 'Bearer sp-fixture-only') {
+    res.writeHead(401); res.end('unauthorized'); return;
+  }
+  const url = new URL(req.url, 'http://localhost');
+  requests.push(url);
+  res.setHeader('content-type', 'application/json');
+  res.end(JSON.stringify({ data: [{ type: 'OCR', content: { text: 'openclaw-fixture-result', timestamp: '2026-10-01T12:00:00Z', frame_id: 1 } }], pagination: { limit: 5, offset: 0, total: 1 } }));
+});
+await new Promise(resolve => api.listen(0, '127.0.0.1', resolve));
+let runtime;
+try {
+  const cfg = JSON.parse(await readFile(configPath, 'utf8'));
+  assert(!cfg.mcpServers, 'legacy root config must be absent');
+  const server = cfg.mcp.servers.screenpipe;
+  assert.equal(server.transport, 'stdio');
+  assert.equal(server.env.SCREENPIPE_MCP_CLIENT, 'openclaw');
+  server.command = execFileSync('which', ['bun'], { encoding: 'utf8' }).trim();
+  server.args = [fileURLToPath(new URL('../dist/index.js', import.meta.url))];
+  server.env = { ...server.env, SCREENPIPE_LOCAL_API_KEY: 'sp-fixture-only', SCREENPIPE_LOCAL_API_URL: `http://127.0.0.1:${api.address().port}`, SCREENPIPE_DISABLE_TELEMETRY: 'true' };
+  await writeFile(process.env.OPENCLAW_CONFIG_PATH, JSON.stringify(cfg));
+  const cli = resolve(openclawPackage, 'openclaw.mjs');
+  const validation = JSON.parse(execFileSync(process.execPath, [cli, 'config', 'validate', '--json'], { encoding: 'utf8', env: process.env }));
+  assert.equal(validation.valid, true);
+  const { createSessionMcpRuntime } = await import(pathToFileURL(resolve(openclawPackage, 'dist/agents/agent-bundle-mcp-runtime.js')));
+  runtime = createSessionMcpRuntime({ cfg, workspaceDir: state, agentDir: state, sessionId: 'screenpipe-smoke' });
+  const catalog = await runtime.getCatalog();
+  assert(catalog.tools.some(t => t.originalName === 'search-content' || t.name === 'search-content' || t.toolName === 'search-content'), 'search-content must be advertised');
+  const result = await runtime.callTool('screenpipe', 'search-content', { q: 'fixture', start_time: '2026-10-01T00:00:00Z', end_time: '2026-10-02T00:00:00Z', limit: 5 });
+  assert(JSON.stringify(result).includes('openclaw-fixture-result'), JSON.stringify(result));
+  assert(requests.some(url => url.pathname === '/search' && url.searchParams.get('start_time') === '2026-10-01T00:00:00Z' && url.searchParams.get('limit') === '5'));
+  server.env.SCREENPIPE_LOCAL_API_KEY = 'sp-invalid-fixture';
+  await runtime.dispose(); await runtime.joinCleanup();
+  runtime = createSessionMcpRuntime({ cfg, workspaceDir: state, agentDir: state, sessionId: 'screenpipe-smoke-invalid-key' });
+  const denied = await runtime.callTool('screenpipe', 'search-content', { q: 'fixture', limit: 1 });
+  assert(JSON.stringify(denied).includes('401'), JSON.stringify(denied));
+  console.log(JSON.stringify({ configValid: true, tools: catalog.tools.length, boundedSearch: true, authFailureVisible: true }));
+} finally {
+  if (runtime) { await runtime.dispose(); await runtime.joinCleanup(); }
+  await new Promise(resolve => api.close(resolve));
+  await rm(state, { recursive: true, force: true });
+}

package/server.json

@@ -8,13 +8,13 @@
     "source": "github",
     "subfolder": "packages/screenpipe-mcp"
   },
-  "version": "0.20.2",
+  "version": "0.20.3",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "screenpipe-mcp",
-      "version": "0.20.2",
+      "version": "0.20.3",
       "transport": {
         "type": "stdio"
       }

package/src/activity-summary-format.ts

@@ -5,6 +5,8 @@
 import * as os from "os";
 
 export type ActivitySummaryPayload = {
+  starred_sessions?: Array<{ id: string; start: string; end: string; has_audio: boolean }>;
+  starred_sessions_has_more?: boolean;
   time_range?: { start?: string; end?: string };
   data_status?: string;
   query_status?: string;
@@ -215,6 +217,13 @@ export function formatActivitySummary(
         ]
       : []),
     "",
+    ...(data.starred_sessions === undefined ? [] : [
+      "Starred intervals (user intent; not proof of capture, completion or effort):",
+      ...data.starred_sessions.slice(0, 10).map((s) => `  ${s.start} to ${s.end} | id=${s.id} | has_audio=${s.has_audio}`),
+      ...(data.starred_sessions.length ? [] : ["  (none in this range)"]),
+      ...(data.starred_sessions_has_more ? ["  More intervals exist; narrow the time range for the complete list. starred_only search covers the requested range independently of this list."] : []),
+      "",
+    ]),
     "Apps:",
     ...(appsLines.length ? appsLines : ["  (none)"]),
     "",

package/src/activity-summary-tool.test.ts

@@ -39,6 +39,25 @@ function summaryPayload() {
 }
 
 describe("activity-summary tool orchestration", () => {
+  it("returns bounded starred metadata in the existing summary call, including empty sessions", async () => {
+    const endpoints: string[] = [];
+    const result = await buildActivitySummaryResult(
+      { start_time: "2026-10-02T00:00:00Z", end_time: "2026-10-03T00:00:00Z" },
+      async endpoint => {
+        endpoints.push(endpoint);
+        return jsonResponse({ ...summaryPayload(), starred_sessions: [
+          { id: "empty-session", start: "2026-10-02T10:00:00Z", end: "2026-10-02T10:15:00Z", has_audio: false },
+        ], starred_sessions_has_more: true });
+      },
+    );
+    expect(endpoints).toHaveLength(1);
+    expect(endpoints[0]).toContain("/activity-summary?");
+    expect(result.text).toContain("empty-session");
+    expect(result.text).toContain("has_audio=false");
+    expect(result.text).toContain("More intervals exist");
+    expect(result.text).toContain("Authoritative active time: 120 min");
+  });
+
   it("returns authoritative time, paths, and bounded parsed context", async () => {
     const endpoints: string[] = [];
     const result = await buildActivitySummaryResult(

package/src/bundled-skills-transport.test.ts

@@ -0,0 +1,52 @@
+// screenpipe — AI that knows everything you've seen, said, or heard
+// https://screenpipe.com
+
+import { beforeAll, it, expect } from "vitest";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, cpSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { buildHttpServer } from "./http-server";
+import { BUNDLED_SKILLS } from "./generated/bundled-skills";
+
+const root = path.resolve(__dirname, "..");
+beforeAll(() => execFileSync("bun", ["run", "build"], { cwd: root, stdio: "pipe", timeout: 120000 }), 120000);
+
+async function checkCatalog(client: Client) {
+  expect((await client.listTools()).tools.map(tool => tool.name)).toContain("screenpipe-skills");
+  const listed = await client.callTool({ name: "screenpipe-skills" });
+  expect(listed.isError).not.toBe(true);
+  const catalog = JSON.parse((listed.content as { text: string }[])[0].text);
+  expect(catalog.skills.map((skill: { name: string }) => skill.name)).toEqual(BUNDLED_SKILLS.map(skill => skill.name));
+  for (const skill of BUNDLED_SKILLS) {
+    const result = await client.callTool({ name: "screenpipe-skills", arguments: { name: skill.name } });
+    expect(result.isError).not.toBe(true);
+    expect((result.content as { text: string }[])[0].text).toBe(skill.markdown);
+  }
+  expect((await client.callTool({ name: "screenpipe-skills", arguments: { name: "screenpipe-learned-private" } })).isError).toBe(true);
+}
+
+it("serves every skill from the isolated built stdio artifact with no source tree or engine", async () => {
+  const temp = mkdtempSync(path.join(tmpdir(), "screenpipe-skills-"));
+  cpSync(path.join(root, "dist/cli.js"), path.join(temp, "cli.js"));
+  const client = new Client({ name: "bundled-skills-test", version: "1.0" });
+  const transport = new StdioClientTransport({ command: process.execPath, args: [path.join(temp, "cli.js")], cwd: temp, env: {
+    PATH: process.env.PATH || "", HOME: temp, USERPROFILE: temp, SCREENPIPE_LOCAL_API_KEY: "fixture-key", SCREENPIPE_DISABLE_TELEMETRY: "1",
+  }, stderr: "pipe" });
+  try { await client.connect(transport); await checkCatalog(client); }
+  finally { await client.close(); await transport.close(); rmSync(temp, { recursive: true, force: true }); }
+}, 15000);
+
+it("serves the same catalog over HTTP without the engine", async () => {
+  const server = buildHttpServer({ mcpPort: 0, screenpipePort: 1, host: "127.0.0.1" });
+  await new Promise<void>(resolve => server.listen(0, "127.0.0.1", resolve));
+  const address = server.address();
+  if (!address || typeof address === "string") throw new Error("Missing fixture port");
+  const client = new Client({ name: "bundled-skills-http-test", version: "1.0" });
+  const transport = new StreamableHTTPClientTransport(new URL(`http://127.0.0.1:${address.port}/mcp`));
+  try { await client.connect(transport); await checkCatalog(client); await transport.terminateSession(); }
+  finally { await client.close(); await transport.close(); await new Promise<void>(resolve => server.close(() => resolve())); }
+}, 15000);

package/src/bundled-skills.test.ts

@@ -0,0 +1,39 @@
+// screenpipe — AI that knows everything you've seen, said, or heard
+// https://screenpipe.com
+
+import { describe, it, expect } from "vitest";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { BUNDLED_SKILLS } from "./generated/bundled-skills";
+import { BUNDLED_SKILLS_TOOL, readBundledSkills } from "./bundled-skills";
+
+const root = path.resolve(__dirname, "../../..");
+const registry = readFileSync(path.join(root, "crates/screenpipe-core/src/starter_skills.rs"), "utf8");
+const starters = [...registry.matchAll(/"(screenpipe-[^"]+)",\s*include_str!\(/g)].map(match => match[1]).sort();
+
+describe("public bundled skill access", () => {
+  it("lists every native starter and both API guides without loading their bodies", () => {
+    expect(BUNDLED_SKILLS.map(skill => skill.name)).toEqual(["screenpipe-api", "screenpipe-cli", ...starters]);
+    const result = readBundledSkills();
+    const catalog = JSON.parse(result.content[0].text);
+    expect(catalog.skills).toEqual(BUNDLED_SKILLS.map(({ name, description }) => ({ name, description })));
+    expect(catalog.skills.every((skill: object) => !("markdown" in skill))).toBe(true);
+    expect(BUNDLED_SKILLS_TOOL.annotations?.readOnlyHint).toBe(true);
+  });
+
+  it("reads the complete canonical files, including newly bundled handoff guidance", () => {
+    expect(starters).toContain("screenpipe-project-handoff");
+    for (const skill of BUNDLED_SKILLS) {
+      const canonical = readFileSync(path.join(root, "crates/screenpipe-core/assets/skills", skill.name, "SKILL.md"), "utf8");
+      expect(readBundledSkills({ name: skill.name }).content[0].text).toBe(canonical);
+    }
+  });
+
+  it.each(["../private", "/Users/example/.codex/skills/private/SKILL.md", "screenpipe-learned-private", "toString", "__proto__", ""])("does not read private or arbitrary paths: %s", name => {
+    expect(readBundledSkills({ name }).isError).toBe(true);
+  });
+
+  it.each([{ name: 7 }, { query: "private" }, { name: null }])("rejects invalid arguments", args => {
+    expect(readBundledSkills(args).isError).toBe(true);
+  });
+});

package/src/bundled-skills.ts

@@ -0,0 +1,34 @@
+// screenpipe — AI that knows everything you've seen, said, or heard
+// https://screenpipe.com
+
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import { BUNDLED_SKILLS } from "./generated/bundled-skills";
+
+export const BUNDLED_SKILLS_TOOL: Tool = {
+  name: "screenpipe-skills",
+  description: "List Screenpipe's bundled workflow skills, or read one by exact name before using it. Covers recall, meetings, project handoffs, decisions, customer context, bug reports, and process guides. Available without filesystem access. Only public bundled instructions are returned; personal and learned skills are not exported.",
+  annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+  inputSchema: {
+    type: "object",
+    properties: {
+      name: { type: "string", description: "Exact skill name from the catalog. Omit to list names and descriptions." },
+    },
+    additionalProperties: false,
+  },
+};
+
+export function readBundledSkills(args: Record<string, unknown> = {}) {
+  if (Object.keys(args).some(key => key !== "name") || (args.name !== undefined && typeof args.name !== "string")) {
+    return { isError: true, content: [{ type: "text" as const, text: "Provide an exact skill name or omit name to list bundled skills." }] };
+  }
+  if (args.name === undefined) {
+    return { content: [{ type: "text" as const, text: JSON.stringify({
+      skills: BUNDLED_SKILLS.map(({ name, description }) => ({ name, description })),
+      usage: "Read the closest matching skill by name. Use your available Screenpipe tools or read screenpipe-api for API access. Loading a skill does not grant new permissions or establish that a task succeeded.",
+    }) }] };
+  }
+  const skill = BUNDLED_SKILLS.find(skill => skill.name === args.name);
+  return skill
+    ? { content: [{ type: "text" as const, text: skill.markdown }] }
+    : { isError: true, content: [{ type: "text" as const, text: "Unknown bundled skill. Omit name to list the public catalog." }] };
+}

package/src/call-observation.test.ts

@@ -0,0 +1,49 @@
+// screenpipe — AI that knows everything you've seen, said, or heard
+// https://screenpipe.com
+import { afterEach, expect, it, vi } from "vitest";
+import { createCallObserver, currentMcpRequestId, observeSearchResult, observeMcpError, type CallObservation } from "./call-observation";
+const tick = () => new Promise(resolve => setImmediate(resolve));
+afterEach(() => vi.useRealTimers());
+function fixture(send?: (p: CallObservation, s: AbortSignal) => Promise<unknown>, enabled = true) {
+  const sent: CallObservation[] = [];
+  const observe = createCallObserver({ tools: ["search-content"], transport: "stdio", client: () => "codex", enabled: () => enabled,
+    send: send || (async p => { sent.push(p); }) });
+  return { sent, observe };
+}
+it("isolates concurrent calls and keeps raw content out of diagnostics", async () => {
+  const { sent, observe } = fixture();
+  const results = await Promise.all([0, 2].map(count => observe("search-content", async () => {
+    const id = currentMcpRequestId(); await tick(); expect(currentMcpRequestId()).toBe(id);
+    observeSearchResult(count, count > 0); return {content:[{type:"text",text:"private query and answer"}]};
+  })));
+  await tick();
+  expect(new Set(sent.map(p => p.request_id)).size).toBe(2);
+  expect(sent.map(p => p.status)).toEqual(["empty", "ok"]);
+  expect(results.map(r => r._meta?.["screenpipe/request_id"])).toEqual(sent.map(p => p.request_id));
+  expect(JSON.stringify(sent)).not.toContain("private"); expect(currentMcpRequestId()).toBeUndefined();
+});
+it("records returned and thrown errors without their text or unknown tool names", async () => {
+  const { sent, observe } = fixture();
+  await observe("private-tool-name", async () => { observeMcpError({status:401}); return {isError:true,content:[]}; });
+  await expect(observe("search-content", async () => { throw Object.assign(new Error("private"), {status:503}); })).rejects.toThrow("private");
+  await tick();
+  expect(sent.map(p => [p.tool, p.status, p.error_kind])).toEqual([["unknown","error","auth"],["search-content","error","backend"]]);
+  expect(sent[0].result_count).toBeUndefined(); expect(JSON.stringify(sent)).not.toContain("private");
+});
+it("does no reporting when disabled and retains the tool result if reporting throws", async () => {
+  const send = vi.fn().mockRejectedValue(new Error("offline"));
+  await fixture(send, false).observe("search-content", async () => ({content:[]}));
+  expect(send).not.toHaveBeenCalled();
+  const result = await fixture(send).observe("search-content", async () => ({content:[{text:"answer"}]}));
+  await tick(); expect(result.content[0].text).toBe("answer");
+});
+it("bounds outstanding reports, expires hung adapters, and reports the loss later", async () => {
+  vi.useFakeTimers(); const sent: CallObservation[] = [];
+  let hang = true;
+  const {observe} = fixture(async p => {sent.push(p); if(hang) await new Promise(() => {});});
+  for(let i=0;i<12;i++) await observe("search-content",async()=>({content:[]}));
+  expect(sent).toHaveLength(8);
+  await vi.advanceTimersByTimeAsync(1001); hang = false;
+  await observe("search-content",async()=>({content:[]})); await vi.advanceTimersByTimeAsync(1);
+  expect(sent).toHaveLength(9); expect(sent[8].dropped_reports).toBe(12);
+});

package/src/call-observation.ts

@@ -0,0 +1,109 @@
+// screenpipe — AI that knows everything you've seen, said, or heard
+// https://screenpipe.com
+
+import { AsyncLocalStorage } from "node:async_hooks";
+import { randomUUID } from "node:crypto";
+import { PKG_VERSION } from "./version";
+import { safeMcpClient, type McpClient } from "./qualified-value";
+
+export type ErrorKind = "none" | "auth" | "invalid_request" | "not_found" | "rate_limited" | "backend" | "unavailable" | "cancelled" | "unknown";
+type Observation = {
+  request_id: string;
+  error_kind: ErrorKind;
+  result_count?: number;
+  truncated?: boolean;
+};
+const context = new AsyncLocalStorage<Observation>();
+export const currentMcpRequestId = () => context.getStore()?.request_id;
+
+export function observeSearchResult(count: number, truncated: boolean): void {
+  const state = context.getStore();
+  if (state) { state.result_count = Math.max(0, Math.floor(count)); state.truncated = truncated; }
+}
+
+export function observeMcpError(error: unknown): void {
+  const state = context.getStore();
+  if (!state) return;
+  const e = error as { status?: number; name?: string } | null;
+  state.error_kind = e?.name === "AbortError" ? "cancelled"
+    : e?.name === "BackendDownError" ? "unavailable"
+    : e?.status === 401 || e?.status === 403 ? "auth"
+    : e?.status === 400 || e?.status === 422 ? "invalid_request"
+    : e?.status === 404 ? "not_found"
+    : e?.status === 429 ? "rate_limited"
+    : e?.status && e.status >= 500 ? "backend" : "unknown";
+}
+
+export type CallObservation = {
+  schema_version: 1;
+  request_id: string;
+  mcp_version: string;
+  client: McpClient;
+  transport: "stdio" | "http";
+  tool: string;
+  status: "ok" | "empty" | "error";
+  error_kind: ErrorKind;
+  duration_ms: number;
+  response_bytes: number;
+  result_count?: number;
+  truncated?: boolean;
+  dropped_reports: number;
+};
+
+const disabled = () => ["SCREENPIPE_DISABLE_TELEMETRY", "SCREENPIPE_TELEMETRY_DISABLED", "CI", "GITHUB_ACTIONS"]
+  .some(key => /^(1|true|yes|on)$/i.test(process.env[key] || ""));
+
+/** A bounded best-effort reporter. It never records arguments, results or errors. */
+export function createCallObserver(options: {
+  tools: readonly string[];
+  transport: "stdio" | "http";
+  client: () => McpClient;
+  send: (payload: CallObservation, signal: AbortSignal) => Promise<unknown>;
+  enabled?: () => boolean;
+}) {
+  const knownTools = new Set(options.tools);
+  let pending = 0, dropped = 0;
+  function report(payload: Omit<CallObservation, "dropped_reports">) {
+    if (!(options.enabled?.() ?? !disabled())) return;
+    if (pending >= 8) { dropped++; return; }
+    pending++;
+    const previousDrops = dropped;
+    dropped = 0;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 1000);
+    timer.unref();
+    // Resolve on timeout even if an adapter ignores its signal.
+    const timeout = new Promise<never>((_, reject) => controller.signal.addEventListener("abort", () => reject(new Error("telemetry timeout")), { once: true }));
+    void Promise.race([Promise.resolve().then(() => options.send({ ...payload, dropped_reports: previousDrops }, controller.signal)), timeout])
+      .catch(() => { dropped += previousDrops + 1; })
+      .finally(() => { clearTimeout(timer); pending--; });
+  }
+  return async function observe<T extends { content?: unknown; isError?: boolean; _meta?: Record<string, unknown> }>(name: string, run: () => Promise<T>): Promise<T & { _meta: Record<string, unknown> }> {
+    const state: Observation = { request_id: randomUUID(), error_kind: "none" };
+    const start = performance.now();
+    return context.run(state, async () => {
+      let result: T | undefined;
+      try {
+        result = await run();
+        return { ...result, _meta: { ...result._meta, "screenpipe/request_id": state.request_id } };
+      } catch (error) {
+        observeMcpError(error);
+        throw error;
+      } finally {
+        const failed = !result || result.isError === true;
+        // Count content size without serializing or retaining a second copy.
+        const bytes = Array.isArray(result?.content) ? result.content.reduce((sum, item) =>
+          sum + (typeof item?.text === "string" ? Buffer.byteLength(item.text) : typeof item?.data === "string" ? Buffer.byteLength(item.data) : 0), 0) : 0;
+        try { report({ schema_version: 1, request_id: state.request_id, mcp_version: PKG_VERSION,
+          client: safeMcpClient(options.client()), transport: options.transport,
+          tool: knownTools.has(name) ? name : "unknown",
+          status: failed ? "error" : state.result_count === 0 ? "empty" : "ok",
+          error_kind: failed ? state.error_kind === "none" ? "unknown" : state.error_kind : "none",
+          duration_ms: Math.max(0, Math.round(performance.now() - start)), response_bytes: bytes,
+          ...(state.result_count === undefined ? {} : { result_count: state.result_count }),
+          ...(state.truncated === undefined ? {} : { truncated: state.truncated }),
+        }); } catch { /* Diagnostics must never change the tool result. */ }
+      }
+    });
+  };
+}