bookmark-research 0.5.0-beta.1

package/docs/wiki-quality.zh.md

@@ -0,0 +1,105 @@
+# 经审阅的 Wiki 与有标注的研究评测
+
+[English](wiki-quality.md) · **中文**
+
+宿主负责撰写、审阅知识页；插件保存证据和修订，核对完整性并检索整理后的正文。评测使用明确标注的输出，不调用模型，也不从文字匹配推断语义支持。
+
+## Wiki API
+
+`WikiStore(directory=None, settings=None, research_sessions=None)` 优先使用显式目录，其次 `settings.wiki.directory`，默认数据目录中的 `wiki/`。插件目录和画布包目录会被拒绝。研究证据仍保存在原研究档案中，位于输入包之外。
+
+```python
+from wiki import WikiStore
+
+wiki = WikiStore(research_sessions=sessions)
+page = {
+    "title": "可复用会话",
+    "kind": "topic",  # 也可为 entity
+    "sections": [{
+        "heading": "已确认行为",
+        "text": "宿主已审阅的综合说明，保留相关限制。",
+        "claims": [{"research_id": research_id, "claim_id": "c1"}],
+    }],
+    "links": [],
+    "review": {
+        "method": "model",  # 也可为 human
+        "reviewer": "真实模型及版本或人工审阅者",
+        "note": "说明实际检查的范围和证据支持。",
+    },
+}
+written = wiki.write("reusable-sessions", page, "整理已审阅结论", expected_revision=0)
+current = wiki.get("reusable-sessions")
+wiki.write("reusable-sessions", revised_page, "解释新增限制", expected_revision=current["revision"])
+```
+
+每节必须明确引用研究 claim。只有 claim 仍有效、所有来源均为 accepted、引文存在于已存正文且正文哈希一致时才接受。Wiki 快照保留 research ID、claim ID、source ID、原清单 ID、书签实例引用、原样引文、审阅、检索元数据和产物哈希。每页最多 24 个不同 claim，过大主题需拆分。
+
+审阅声明说明正文是否受支持、实体与范围是否正确、是否保留不确定性和反证。程序记录声明及 rubric，不能证明署名的人或模型实际做了判断。写入成功不是独立语义认可。
+
+导入的外部报告始终是二手证据，保留其 provenance 与报告原句；参考文献不会被扩充成声称已读的原始网页或覆盖来源。
+
+### 修订、链接与检查
+
+每次更新在 `revisions/<page_id>/` 写入不可变 JSON 和渲染 Markdown，再原子更新 `index.json`。索引是发布点。发布失败可能留下未引用文件，旧版仍可读取。expected_revision=0 用于创建；更新必须指定调用者实际读过的版本。写入中断后先检查当前 revision，再判断是否重试。
+
+交叉链接形如 `{"page_id":"existing-page","relation":"宿主对关系的解释"}`，目标页必须已存在。渲染链接指向写入时的目标版本，保留历史含义。目标后续变化会产生 lint 提示，宿主可明确修订关系。旧页版本可通过 `get(page_id, revision=N)` 读取。
+
+| 方法 | 返回 |
+| --- | --- |
+| `write(page_id, page, change_note, expected_revision=0)` | 修订元数据与绝对产物路径 |
+| `get(page_id, revision=None)` | 正文、证据快照、更新记录与当前 provenance 核验 |
+| `list(offset=0, limit=20)` | 当前页元数据的分页 |
+| `lint(page_id=None)` | 来源审阅、有效 claim、引文、哈希、链接和历史问题 |
+| `search(query, offset=0, limit=10)` | 匹配当前 Wiki 正文，排除已失效的页 |
+
+Lint 检测后续来源拒绝、结论撤回、来源／claim 变化和缺失／改动的产物。历史正文保留并标记过时，明确返回 `semantic_support:"not_scored"`。
+
+检索匹配标题、章节标题和整理后的正文，采用忽略大小写的字面词匹配（包含中文子串）及简单出现次数排序。仅保存 provider 摘录不会使它成为可检索的 Wiki 知识。没有 embedding 检索或语义重排，也不会未经实际问答评测就选择它们。
+
+## 质量评测输入
+
+`evaluation.evaluate(suite, runs, judgments=None)` 只计算传入数据。完整可运行输入为 [research-quality.json](https://github.com/Browser-bookmark-hub/Bookmark-Research/blob/main/tests/fixtures/research-quality.json)，源码和验证包也包含 `tests/fixtures/research-quality.json`。
+
+- **suite** 定义任务、原始来源／问题 ID、金标准和版本化 rubric。gold_answers:null 表示没有答案集合基准。rubric 定义答案身份匹配、引用支持和 0–4 分的报告维度。
+- **run** 记录 task、system、mode、repeat、最终报告、原子答案／claims／citations、覆盖 ID 和测量，并保留模型、工具、预算、输入快照／版本、时间窗口及宿主版本。引文按唯一 claim/source 对计算。
+- **judgment** 标识 rubric 版本与真实人工／模型评审者，给出预测答案到 gold ID 的匹配、supported/unsupported/uncertain 引用标签及理由、报告维度分数及理由。合成样例的评审必须自报 synthetic。
+
+答案匹配是标注任务。评审者必须阅读真实预测，核对身份与范围；错误实体用 gold_id:null。评分器不猜别名，也不把正则匹配当语义裁判。多个预测匹配同一 gold 实体时，集合 precision/recall 只计算一次；未匹配预测算假阳性，重复匹配另行报告。
+
+每条引用判断针对完整命题及来源上下文，包括身份、日期和范围。supported 表示文本支持命题；unsupported 与 uncertain 都留在完整准确率分母中。原句匹配不能代替支持性判断。
+
+### 指标与缺失信息
+
+| 输出 | 含义与边界 |
+| --- | --- |
+| 答案 precision、recall、F1 | 需要金标准与完整答案匹配，否则 null |
+| 语义引用准确率 | 完整标注时为 supported／全部引文；局部标注另行显示 |
+| 结论语义支持 | 全部引文已标注后，有 supported 引文的 claim／全部 claim |
+| 引用存在率 | 有任意引文的 claim／全部 claim，仅是结构指标 |
+| 报告质量 | 全部 rubric 维度已评分时，将提供的 0–4 分均值归一化 |
+| accounted/text/reviewed 覆盖 | 各自相对原始来源集合计算，失败来源仍留在分母 |
+| 问题覆盖 | 已记录回答的问题 ID／原始问题 ID，不判断答案真假 |
+| 成本与时延 | 提供的美元／秒，注明 observed、reported 或 synthetic；未知保持 null |
+| 重复运行波动 | 相同声明条件下的数量、均值、样本方差、样本标准差和极差 |
+
+覆盖必须满足 reviewed ⊆ text ⊆ accounted ⊆ original scope。报告的 ID 仍需证据审计，输入标签本身不证明实际阅读。插件无法取得的外部工具和模型用量保持未知。
+
+比较按同一任务分组。模型、工具、预算、输入版本、时间窗口、宿主、评审者或测量依据不同会被披露，并分开聚合。未知预算不能声称受控比较。只有一次观察时没有方差估计，缺失费用不会当 0 求均值。失败和未完成输出仍保留在运行集合中。
+
+输出固定 suite、run 和 judgment 哈希，保留评审者／rubric 身份及 null 分数原因。它不会生成 provider 排名、因果结论、RACE／FACT 分数或公共榜单分数。声称研究质量提高需要真实任务运行与可辩护的独立标注。
+
+## 重现离线演示
+
+以下命令需要源码或验证包；运行时导出带指南，但不含测试资料和验证脚本。
+
+```sh
+python3 -B scripts/verify_quality.py
+python3 -B -m unittest discover -s tests -p 'test_wiki.py'
+python3 -B -m unittest discover -s tests -p 'test_evaluation.py'
+```
+
+验证脚本在数据目录的新运行目录下写入 inputs.json、evaluation.json 和可读的 evaluation.md。`--output /absolute/external/directory` 可另选目录；`--fixture /path/input.json` 接受含 suite、runs、judgments 和可选已知样例期望的包装对象。
+
+示例包含四条虚构来源、两个 gold 实体和六份手写输出，标成 direct、workflow、professional。一个来源不可用，部分输出遗漏或虚构答案，一个引文范围不确定。费用和时长是合成值，其中一个费用故意未知。这些情况验证分母、语义标签完整性、重复方差及缺失测量，**不测量这三条路线或任何真实宿主／模型／服务**。
+
+Wiki 测试另覆盖不可变历史、索引发布失败、交叉链接、中文正文检索、来源拒绝／结论撤回、二手报告 provenance 及来源／包边界。真实宿主研究、专业服务比较和独立语义评审仍是另外的验证工作。

package/hosts/claude/runtime.js

@@ -0,0 +1,13 @@
+// Claude Dynamic Workflows supplies agent() and pipeline().
+const host = {
+  name: "claude_code",
+  async all(jobs) {
+    const values = await pipeline(jobs, job => agent(job.prompt, {
+      label: job.key, schema: job.schema,
+    }));
+    return jobs.map((job, index) => ({
+      key: job.key, ok: values[index] != null, data: values[index] ?? null,
+      error: values[index] == null ? "Native workflow child failed or returned no result" : null,
+    }));
+  },
+};

package/hosts/codex/delegate.md

@@ -0,0 +1,14 @@
+# Codex native research delegation
+
+Use the native subagent tools visible in the current Codex session. This file explicitly requests delegation for a multi-group research task. It does not define a JavaScript runner or require custom global agents. Inherit the current model, reasoning, permissions and tool access unless the user specifies otherwise.
+
+Resolve the output language from the user's explicit requirement, otherwise their actual task/conversation, with English as the fallback. Preserve it in the research brief and pass it to every reader, verifier and follow-up assignment. Use it for authored answers, report prose, review notes and Wiki titles/sections. Keep original quotations, URLs, IDs, code and technical field names unchanged; put translations outside quotations. This English instruction file does not select the answer language. The bilingual reading reference is in `docs/prompt-reference.en.md` and `docs/prompt-reference.md`.
+
+1. Read `research_status`. Resume an `incomplete` research explicitly with `research_record` kind `resume`; never reopen completed/cancelled research. Read every page of `research_inventory` without narrowing the frozen scope. The optional `python3 hosts/codex/prepare.py --research-id RID` helper calls the same shared MCP tools and emits exhaustive groups; it starts no agents. Keep every `u-` inventory ID and its original bookmark instances. A local package `source_id`, a `u-` inventory ID and an `sN` extracted source ID are different identifiers.
+2. Spawn one bounded reader per group within the native concurrency limit. Give each reader the research ID, exact assigned inventory IDs, method, relevant question IDs and a unique operation prefix. Readers call `research_inventory`, `research_fetch`/`research_search`, `research_source`, and `research_record`. Batch up to 8 needed URLs per fetch where applicable, respecting the existing `initial_fetch_plan` and budget. Require full relevant saved text, an explicit `source_review`, source-backed claims with exact quotes and a separate `inventory_review` for every assigned URL. Submit ready records through `research_record.entries` in batches of up to 50 with stable `batch_id` values under the reader's unique prefix. Place reviews before their claims; use returned claim IDs in subsequent inventory/answer batches. An invalid entry rejects the whole batch; identical retries reuse the batch ID. Return structured IDs, citations, judgments and failures. Failed fetches cannot become reviewed entries. Do not ask a child to create another scheduler.
+3. Wait for every reader through the native wait/agent controls. A pending thread or unread message is not completion. Preserve failed assignments and already-persisted progress. Then use separate, fresh verifier subagents for the same complete ID groups. Verifiers independently read claims and saved evidence, challenge unsupported conclusions and misleading freshness/completeness claims, and use retraction/gap/conflict/resolution records where justified. They must identify uncheckable items; a successful child turn is not proof of successful verification.
+4. Read `research_coverage` with `all`, `missing`, `unread` and `unreviewed`, following `next_offset` separately for every filter. Compare the complete inventory with every returned assignment, not just the first page or a count. Send the full difference plus failed verification IDs to another bounded reading and independent verification pass when needed. Use the host's current controls for child continuation or cancellation; no plugin lease or worker process exists.
+5. Save complete returned JSON with `research_record` kind `external_run`: include all inventory IDs, reader/verifier results, remaining IDs, actual observed states, and coverage metrics. Read the saved location from `recorded.result_path` and its digest from `recorded.result_sha256`. Use actual native run IDs when available. If only a caller correlation key is available, prefix it with `local:` and say it is not a native host run ID. Record only completed observations as completed; an unknown outcome is not cancellation.
+6. Synthesize answers with valid claim IDs and run coverage again. `research_finish` owns the completion gate. Unverified major conclusions, unexplained errors or remaining coverage gaps require an `incomplete` report. The parent must directly read `research_status` and every relevant `research_coverage` page after child reports settle, compare returned paths with actual `artifacts` and `external_runs`, and read the complete analysis artifact with its verified SHA-256. A child's success or claimed path is not confirmation. Link the verified report, full saved result and coverage, and retain excluded/blocked sources and their original bookmark context. Do not retry an unknown paid outcome automatically.
+
+If native subagent tools are disabled or unavailable, report the missing capability. The host may perform a bounded single-agent task under the same research rules; do not claim native delegation occurred. Native subagent threads and plugin research archives have separate lifecycles.

package/hosts/codex/prepare.py

@@ -0,0 +1,61 @@
+#!/usr/bin/env python3
+"""Prepare exhaustive native Codex assignments; this script never spawns agents."""
+
+import argparse
+import importlib.util
+import json
+from pathlib import Path
+import sys
+
+
+def main():
+    for stream in (sys.stdout, sys.stderr):  # Windows pipes default to the ANSI code page
+        if hasattr(stream, "reconfigure"):
+            stream.reconfigure(encoding="utf-8")
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--research-id", required=True)
+    parser.add_argument("--group-size", type=int, default=12)
+    parser.add_argument("--db")
+    parser.add_argument("--config")
+    options = parser.parse_args()
+    if not 1 <= options.group_size <= 50:
+        parser.error("group-size must be 1..50")
+    root = Path(__file__).resolve().parents[2]
+    spec = importlib.util.spec_from_file_location("research_call", root / "hosts/shared/research-call.py")
+    bridge = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(bridge)
+    items = []
+    offset = 0
+    seen_offsets = set()
+    total = None
+    try:
+        while offset is not None:
+            if offset in seen_offsets:
+                raise ValueError("Inventory pagination repeated an offset")
+            seen_offsets.add(offset)
+            response = bridge.call_tool({"name": "research_inventory", "arguments": {
+                "research_id": options.research_id, "offset": offset, "limit": 100}}, options.db, options.config)
+            if response["isError"]:
+                raise ValueError(json.dumps(response["result"], ensure_ascii=False))
+            page = response["result"]
+            if total is not None and total != page["total"]:
+                raise ValueError("Frozen inventory total changed while reading")
+            total = page["total"]
+            items.extend(page["items"])
+            offset = page["next_offset"]
+        ids = [row["id"] for row in items]
+        if len(ids) != total or len(set(ids)) != total:
+            raise ValueError("Inventory pages did not contain every unique source ID")
+        groups = [{"group": index // options.group_size, "inventory_ids": ids[index:index + options.group_size]}
+                  for index in range(0, len(ids), options.group_size)]
+        print(json.dumps({"research_id": options.research_id, "total": total, "inventory_ids": ids,
+                          "groups": groups, "instructions": str(root / "hosts/codex/delegate.md"),
+                          "agents_started": 0}, ensure_ascii=False, indent=2))
+    except (OSError, ValueError, RuntimeError, KeyError) as error:
+        print(json.dumps({"error": str(error)}, ensure_ascii=False), file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/hosts/dsh/plugin.js

@@ -0,0 +1,36 @@
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+
+export const name = "bookmark-research";
+export const inject = ["skills"];
+
+// The module travels with the Python runtime; no exporting machine's path is embedded.
+const root = fileURLToPath(new URL("../../", import.meta.url));
+const skillUrl = new URL("../../skills/bookmark-research/SKILL.md", import.meta.url);
+const resourceBase = { kind: "directory", path: fileURLToPath(new URL("./", skillUrl)) };
+const candidate = {
+  name,
+  description: "Research bookmark URLs or Bookmark Canvas packages with shared Python tools and retained evidence.",
+  invocation: { modelInvocable: true, userInvocable: true },
+  provider: name,
+  source: "bundled",
+  resourceBase,
+  path: fileURLToPath(skillUrl),
+  rank: 600,
+  locator: skillUrl,
+};
+
+export function apply(ctx) {
+  ctx.provide("bookmarkResearchPaths", {
+    root,
+    cli: fileURLToPath(new URL("../../src/cli.py", import.meta.url)),
+  });
+  ctx.skills.registerProvider(() => ({
+    name,
+    async list() { return [candidate]; },
+    async get() {
+      const content = (await readFile(skillUrl, "utf8")).replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n/, "");
+      return { ...candidate, content };
+    },
+  }));
+}

package/hosts/dsh/runtime.js

@@ -0,0 +1,14 @@
+// DSH supplies these hooks through its configured workflow engine.
+// Fatal hook/schema/cap errors propagate; ordinary child failures remain visible.
+const host = {
+  name: "dsh",
+  async all(jobs) {
+    const values = await pipeline(jobs, job => agent(job.prompt, {
+      label: job.key, schema: job.schema,
+    }));
+    return jobs.map((job, index) => ({
+      key: job.key, ok: values[index] != null, data: values[index] ?? null,
+      error: values[index] == null ? "Native workflow child failed or returned no result" : null,
+    }));
+  },
+};

package/hosts/dsh/workflow-call.py

@@ -0,0 +1,45 @@
+#!/usr/bin/env python3
+"""Print a complete DSH workflow tool call; never start the workflow here."""
+
+import argparse
+import json
+from pathlib import Path
+import sys
+
+
+def main():
+    for stream in (sys.stdout, sys.stderr):  # Windows pipes default to the ANSI code page
+        if hasattr(stream, "reconfigure"):
+            stream.reconfigure(encoding="utf-8")
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--research-id", required=True)
+    parser.add_argument("--run-key", required=True)
+    parser.add_argument("--group-size", type=int, default=12)
+    parser.add_argument("--max-gap-rounds", type=int, default=1)
+    parser.add_argument("--method", default="comparison")
+    parser.add_argument("--output-language", default="auto",
+                        help="Output language name/code; auto follows the brief/questions, with English as fallback")
+    options = parser.parse_args()
+    if not 1 <= options.group_size <= 50 or not 0 <= options.max_gap_rounds <= 4:
+        parser.error("group-size must be 1..50 and max-gap-rounds must be 0..4")
+    if (not options.output_language.strip() or len(options.output_language) > 80
+            or any(ord(char) < 32 or ord(char) == 127 for char in options.output_language)):
+        parser.error("output-language must be 1..80 characters without control characters")
+    options.output_language = options.output_language.strip()
+    root = Path(__file__).resolve().parents[2]
+    directory = root / "workflows/bookmark-research"
+    if directory.is_dir():
+        meta = json.loads((directory / "meta.json").read_text(encoding="utf-8"))
+        script = (directory / "script.js").read_text(encoding="utf-8")
+    else:
+        sys.path.insert(0, str(root / "scripts"))
+        from host_assets import build_workflow
+        definition, script = build_workflow(root, "dsh")
+        meta = definition["meta"]
+    args = vars(options)
+    args["bridge_path"] = str(root / "hosts/shared/research-call.py")
+    print(json.dumps({"meta": meta, "script": script, "args": args}, ensure_ascii=False, indent=2))
+
+
+if __name__ == "__main__":
+    main()

package/hosts/pi/register-workflow.py

@@ -0,0 +1,72 @@
+#!/usr/bin/env python3
+"""Register the saved workflow in one project, without changing Pi settings."""
+
+import argparse
+import json
+from pathlib import Path
+import sys
+import tempfile
+
+
+def register(project):
+    project = Path(project).expanduser().absolute()
+    if not project.is_dir() or project.is_symlink():
+        raise ValueError("Project must be an existing, nonsymlink directory")
+    project = project.resolve()
+    root = Path(__file__).resolve().parents[2]
+    source = root / "workflows/bookmark-research"
+    if source.is_dir():
+        manifest = json.loads((source / "workflow.json").read_text(encoding="utf-8"))
+        script = (source / "script.js").read_bytes()
+    else:
+        sys.path.insert(0, str(root / "scripts"))
+        from host_assets import build_workflow
+        definition, script = build_workflow(root, "pi")
+        manifest = {**definition["meta"], "parameters": definition["parameters"]}
+        script = script.encode("utf-8")
+    manifest["parameters"]["bridge_path"] = {
+        "type": "string", "default": str(root / "hosts/shared/research-call.py"),
+        "description": "Shared research tool bridge in this stable bundle location",
+    }
+    target = project / ".pi/subagent-workflows/bookmark-research"
+    current = project
+    for part in target.relative_to(project).parts:
+        current /= part
+        if current.is_symlink():
+            raise ValueError("Refusing a symlink registration path: " + str(current))
+    payload = {"workflow.json": (json.dumps(manifest, ensure_ascii=False, indent=2) + "\n").encode("utf-8"),
+               "script.js": script}
+    if target.exists():
+        same = target.is_dir() and {p.name for p in target.iterdir()} == set(payload) and all(
+            (target / name).is_file() and not (target / name).is_symlink() and
+            (target / name).read_bytes() == content for name, content in payload.items())
+        if not same:
+            raise ValueError("Existing workflow differs; preserve it and choose a clean project registration location")
+        return {"path": str(target), "changed": False, "extensions_installed": False}
+    target.parent.mkdir(parents=True, exist_ok=True)
+    with tempfile.TemporaryDirectory(prefix=".bookmark-workflow-", dir=target.parent) as temporary:
+        stage = Path(temporary) / "bookmark-research"
+        stage.mkdir()
+        for name, content in payload.items():
+            (stage / name).write_bytes(content)
+        stage.rename(target)
+    return {"path": str(target), "changed": True, "extensions_installed": False}
+
+
+def main():
+    for stream in (sys.stdout, sys.stderr):  # Windows pipes default to the ANSI code page
+        if hasattr(stream, "reconfigure"):
+            stream.reconfigure(encoding="utf-8")
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--project", required=True, help="Existing project whose .pi/subagent-workflows directory to use")
+    options = parser.parse_args()
+    try:
+        print(json.dumps(register(options.project), ensure_ascii=False, indent=2))
+    except (OSError, ValueError) as error:
+        print(json.dumps({"error": str(error)}, ensure_ascii=False), file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/hosts/pi/runtime.js

@@ -0,0 +1,18 @@
+// pi-subagents-workflows injects args/cwd; pi-subagents owns runs and lifecycle.
+const host = {
+  name: "pi",
+  all(jobs) {
+    return runs.all(jobs.map(job => ({
+      key: job.key, agent: "delegate", task: job.prompt, cwd,
+      context: "fresh", outputSchema: job.schema,
+    }))).then(values => jobs.map((job, index) => {
+      const run = values[index];
+      const ok = Boolean(run && !run.error && run.ok !== false && run.structuredOutput);
+      return {
+        key: job.key, ok, data: ok ? run.structuredOutput : null,
+        error: ok ? null : String(run?.error || "Missing structuredOutput or failed child"),
+        child_run_id: run?.runId || null,
+      };
+    }));
+  },
+};

package/hosts/shared/research-call.py

@@ -0,0 +1,76 @@
+#!/usr/bin/env python3
+"""Call one shared research MCP tool using JSON stdin and the bundled server."""
+
+import argparse
+import json
+from pathlib import Path
+import subprocess
+import sys
+
+
+def call_tool(request, db=None, config=None, timeout=600):
+    if not isinstance(request, dict) or set(request) != {"name", "arguments"}:
+        raise ValueError("Request must contain exactly name and arguments")
+    if not isinstance(request["name"], str) or not request["name"].startswith("research_"):
+        raise ValueError("This bridge calls research_* tools only")
+    if not isinstance(request["arguments"], dict):
+        raise ValueError("arguments must be a JSON object")
+    command = [sys.executable, "-B", str(Path(__file__).resolve().parents[2] / "src/cli.py")]
+    if db:
+        command.extend(["--db", str(db)])
+    if config:
+        command.extend(["--config", str(config)])
+    command.append("serve")
+    messages = [
+        {"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {
+            "protocolVersion": "2025-11-25", "capabilities": {},
+            "clientInfo": {"name": "bookmark-research-host-bridge", "version": "1"}}},
+        {"jsonrpc": "2.0", "method": "notifications/initialized"},
+        {"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": request},
+    ]
+    result = subprocess.run(command, input="\n".join(json.dumps(row) for row in messages) + "\n",
+                            text=True, encoding="utf-8", errors="replace", capture_output=True, timeout=timeout)
+    if result.returncode:
+        raise RuntimeError("Shared MCP process failed: " + result.stderr.strip()[:2000])
+    responses = [json.loads(line) for line in result.stdout.splitlines() if line.strip()]
+    response = next((row for row in responses if row.get("id") == 2), None)
+    if response is None:
+        raise RuntimeError("Shared MCP process returned no tool response")
+    if "error" in response:
+        return {"isError": True, "result": response["error"]}
+    tool_result = response["result"]
+    if "structuredContent" in tool_result:
+        value = tool_result["structuredContent"]
+    else:
+        text = "\n".join(item["text"] for item in tool_result.get("content", []) if item.get("type") == "text")
+        try:
+            value = json.loads(text)
+        except json.JSONDecodeError:
+            value = {"text": text}
+    return {"isError": bool(tool_result.get("isError")), "result": value}
+
+
+def main():
+    for stream in (sys.stdout, sys.stderr):  # Windows pipes default to the ANSI code page
+        if hasattr(stream, "reconfigure"):
+            stream.reconfigure(encoding="utf-8")
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--db")
+    parser.add_argument("--config")
+    parser.add_argument("--timeout", type=float, default=600)
+    options = parser.parse_args()
+    try:
+        if options.timeout <= 0:
+            raise ValueError("timeout must be positive")
+        result = call_tool(json.load(sys.stdin), options.db, options.config, options.timeout)
+    except subprocess.TimeoutExpired:
+        result = {"isError": True, "unknown_outcome": True,
+                  "result": {"error": "MCP call timed out. Inspect research_status before retrying; an operation may have reserved budget or saved a result."}}
+    except (OSError, ValueError, RuntimeError) as error:
+        result = {"isError": True, "result": {"error": str(error)}}
+    print(json.dumps(result, ensure_ascii=False))
+    return 1 if result["isError"] else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())