@arnilo/prism-tools 0.0.0-stage → 0.13.0

package/openapi/src/types.ts

@@ -0,0 +1,61 @@
+import type { JsonObject, SecretRedactor, ToolExecutionContext } from "@arnilo/prism";
+import type { OpenApiLimits } from "./limits.js";
+
+export interface OpenApiCredentialInput {
+  readonly operationId: string;
+  readonly method: string;
+  readonly path: string;
+}
+
+/** Host-owned credential resolver. Never inline secrets in the document or options. */
+export type OpenApiCredentialResolver = (
+  input: OpenApiCredentialInput,
+  context: ToolExecutionContext,
+) =>
+  | { readonly headers?: Readonly<Record<string, string>>; readonly query?: Readonly<Record<string, string>> }
+  | undefined
+  | Promise<{ readonly headers?: Readonly<Record<string, string>>; readonly query?: Readonly<Record<string, string>> } | undefined>;
+
+/** Host policy check immediately before the request; throw to deny. */
+export type OpenApiPolicyCheck = (
+  input: OpenApiCredentialInput & { readonly args: JsonObject },
+  context: ToolExecutionContext,
+) => void | Promise<void>;
+
+/** Optional bounded cursor pagination. Applies only to operations whose compiled query parameters include `pageParam`. */
+export interface OpenApiPagination {
+  /** Query parameter name carrying the page token. */
+  readonly pageParam: string;
+  /** Optional query parameter name for the page size. */
+  readonly pageSizeParam?: string;
+  /** Page size sent with every page when `pageSizeParam` is set. */
+  readonly pageSize?: number;
+  /** Dot-path to the next-page token in the JSON response. Default probes `next` then `nextPageToken`. */
+  readonly nextPath?: string;
+  /** Dot-path to the items array in the JSON response. Default `items`. */
+  readonly itemsPath?: string;
+}
+
+export interface OpenApiToolsOptions {
+  /** OpenAPI 3.1 document as a JSON string or parsed object; byte-bounded by `maxDocumentBytes`. */
+  readonly document: string | JsonObject;
+  /** Allow-listed operationIds; only these compile into tools. */
+  readonly operations: readonly string[];
+  /** Pinned absolute base URL (https; http only for loopback hosts). Document/path/operation `servers` must share its origin. */
+  readonly server: string;
+  /** Host credential resolver; merged into request headers/query, never echoed into output. */
+  readonly credentials?: OpenApiCredentialResolver;
+  /** Prefix applied to every compiled tool name (for example `<specId>_`). The result name matches. */
+  readonly namePrefix?: string;
+  /** Host policy check before each request; throw to deny. */
+  readonly policy?: OpenApiPolicyCheck;
+  /** Applied to response text before it enters the tool result. */
+  readonly redactor?: SecretRedactor;
+  /** Optional bounded cursor pagination. */
+  readonly pagination?: OpenApiPagination;
+  /** Send `Idempotency-Key: <core idempotencyKey>` on mutating requests when the core provided one. Default false. */
+  readonly idempotencyKeyHeader?: boolean;
+  readonly limits?: OpenApiLimits;
+  /** Test seam; defaults to global fetch. */
+  readonly fetch?: typeof globalThis.fetch;
+}

package/package.json

@@ -1,6 +1,173 @@
 {
   "name": "@arnilo/prism-tools",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.13.0",
+  "description": "Prism coding, web, browser, research, OpenAPI, computer-use and work tools. Import each package through its subpath.",
+  "type": "module",
+  "engines": {
+    "bun": ">=1.4.4"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ashiqrniloy/prism.git",
+    "directory": "packages/tools"
+  },
+  "bugs": {
+    "url": "https://github.com/ashiqrniloy/prism/issues"
+  },
+  "homepage": "https://github.com/ashiqrniloy/prism/tree/main/packages/tools#readme",
+  "keywords": [
+    "prism",
+    "work",
+    "connectors",
+    "office",
+    "documents",
+    "document-reader",
+    "sheets",
+    "diagrams",
+    "docx",
+    "xlsx",
+    "pptx",
+    "drawio"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    "./coding": "./coding/src/index.ts",
+    "./web": "./web/src/index.ts",
+    "./browser": "./browser/src/index.ts",
+    "./research": "./research/src/index.ts",
+    "./openapi": "./openapi/src/index.ts",
+    "./computer-use": "./computer-use/src/index.ts",
+    "./work": "./work/src/index.ts",
+    "./work/connectors": "./work/src/connectors/index.ts",
+    "./work/connectors/drafts": "./work/src/connectors/drafts.ts",
+    "./work/connectors/google-workspace": "./work/src/connectors/google-workspace.ts",
+    "./work/connectors/microsoft365": "./work/src/connectors/microsoft365.ts",
+    "./work/diagrams": "./work/src/diagrams/index.ts",
+    "./work/document-extraction": "./work/src/document-extraction/index.ts",
+    "./work/document-reader": "./work/src/document-reader/index.ts",
+    "./work/documents": "./work/src/documents/index.ts",
+    "./work/sandbox": "./work/src/sandbox/index.ts",
+    "./work/sheets": "./work/src/sheets/index.ts",
+    "./work/skills": "./work/src/skills/index.ts",
+    "./work/tools": "./work/src/tools/index.ts"
+  },
+  "files": [
+    "coding/src",
+    "!coding/src/**/__tests__",
+    "coding/README.md",
+    "web/src",
+    "!web/src/**/__tests__",
+    "web/skills",
+    "web/README.md",
+    "browser/src",
+    "!browser/src/**/__tests__",
+    "browser/skills",
+    "browser/README.md",
+    "research/src",
+    "!research/src/**/__tests__",
+    "research/skills",
+    "research/README.md",
+    "openapi/src",
+    "!openapi/src/**/__tests__",
+    "openapi/README.md",
+    "computer-use/src",
+    "!computer-use/src/**/__tests__",
+    "computer-use/skills",
+    "computer-use/README.md",
+    "work/src",
+    "!work/src/**/__tests__",
+    "work/docling",
+    "work/sandbox",
+    "work/vendor",
+    "work/vendor-lock.json",
+    "work/THIRD_PARTY_NOTICES",
+    "work/README.md",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "bun ../../scripts/with-build-lock.mjs --shared bun test --parallel=4 --timeout=0 coding/src web/src browser/src research/src openapi/src computer-use/src work/src",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test:office": "PRISM_TEST_LIBREOFFICE=1 bun ../../scripts/with-build-lock.mjs --shared bun test --timeout=0 work/src/documents/__tests__/golden.test.ts",
+    "pack:dry-run": "bun pm pack --dry-run"
+  },
+  "dependencies": {
+    "diff": "^9.0.0",
+    "@mozilla/readability": "0.6.0",
+    "linkedom": "0.18.14",
+    "turndown": "7.2.4"
+  },
+  "peerDependencies": {
+    "@arnilo/prism": ">=0.13.0 <1.0.0",
+    "@arnilo/prism-extensions": "^0.13.0",
+    "@office-open/docx": "0.14.5",
+    "@office-open/pptx": "0.14.5",
+    "@office-open/xlsx": "0.14.5",
+    "@office-open/xml": "0.14.5",
+    "ajv": "^8.17.1",
+    "fast-xml-parser": "5.11.1",
+    "e2b": "2.49.1",
+    "playwright-core": "1.63.0",
+    "@firecrawl/anydoc": "0.2.4",
+    "mammoth": "^1.8.0",
+    "pdf-parse": "^2.4.5"
+  },
+  "peerDependenciesMeta": {
+    "@office-open/docx": {
+      "optional": true
+    },
+    "@office-open/pptx": {
+      "optional": true
+    },
+    "@office-open/xlsx": {
+      "optional": true
+    },
+    "@office-open/xml": {
+      "optional": true
+    },
+    "ajv": {
+      "optional": true
+    },
+    "fast-xml-parser": {
+      "optional": true
+    },
+    "e2b": {
+      "optional": true
+    },
+    "playwright-core": {
+      "optional": true
+    },
+    "@firecrawl/anydoc": {
+      "optional": true
+    },
+    "mammoth": {
+      "optional": true
+    },
+    "pdf-parse": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/diff": "^7.0.2",
+    "@types/node": "^22.20.0",
+    "typescript": "^7.0.2",
+    "@arnilo/prism-extensions": "0.13.0",
+    "@types/turndown": "5.0.6",
+    "playwright-core": "1.63.0",
+    "@firecrawl/anydoc": "0.2.4",
+    "mammoth": "^1.8.0",
+    "pdf-parse": "^2.4.5",
+    "@office-open/docx": "0.14.5",
+    "@office-open/pptx": "0.14.5",
+    "@office-open/xlsx": "0.14.5",
+    "@office-open/xml": "0.14.5",
+    "ajv": "^8.17.1",
+    "fast-xml-parser": "5.11.1",
+    "@arnilo/prism-hosts": "0.13.0"
+  }
+}

package/research/README.md

@@ -0,0 +1,72 @@
+# @arnilo/prism-tools/research
+
+Installing this package gives an agent four research skills, a per-session source ledger, a read-only `cite` tool, and a citation check at the end of a run.
+
+## Install
+
+```bash
+prism add @arnilo/prism-tools/research
+```
+
+```jsonc
+{
+  "packages": {
+    "@arnilo/prism-tools/research": {}
+  }
+}
+```
+
+Every config field has a default. Set `maxRepairs` or `requireCitations` only when the defaults are wrong.
+
+## Configuration
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `sourceTools` | `string[]` | `web_fetch`, `web_search`, `web_extract`, `browser_observe`, `rag_search` | Tool names whose results are ledger sources. A name that is never registered is allowed and noted once. |
+| `maxRepairs` | integer `0`–`3` | `1` | Extra model turns used to repair unresolved citations. `0` spends none. |
+| `maxSources` | integer `1`–`5000` | `500` | Ledger size at which recording stops. |
+| `requireCitations` | boolean | `false` | A report with no `[[cite:<id>]]` markers counts as unresolved. |
+| `redactQuery` | `string[]` | `key`, `token`, `api_key`, `access_token`, `sig`, `signature` | Query parameter names stripped before a URL is stored. |
+
+Unknown keys are rejected. `maxRepairs` above 3 and `maxSources` above 5000 are rejected.
+
+## What it changes
+
+- Tools: `cite` (`effects: []`). `cite({ id, quote? })` returns `[[cite:<id>]]` when `id` is in the ledger, or an error result `unknown_source` when it is not. `quote` is not stored.
+- Skills: `research-scoping`, `source-triage`, `research-synthesis`, `research-report`, loaded from this package and progressive by default. The report skill tells the model to cite with markers from `cite`, and declares `requiresTools: cite`, so a request without that tool does not list it. Each description opens with when to use the skill (`scripts/package-skills-conformance.mjs` holds them to the package-skill contract in [Packages](../../../docs/packages.md#writing-a-package-skill)).
+- Command: `research.verify` → `{ verdict, unresolved, ledgerSize }` for the given session. `verdict` is `pending` until a run ends, then `passed` or `failed`. With no session it returns `pending` and does not throw.
+- Hooks: `tool.result` (transform, id `ledger`) and `run.end` (decide, id `citations`). A new source appends `ledger: S<n>` to the tool result. The transcript keeps `value` and drops text content when `value` is set, so the same line is also `value.ledger`.
+- Events: `research.citations.unresolved` with `{ unresolved: string[] }` when the check fails after the repair bound.
+- Session state: ledger entries `{ id, url | docId, title?, tool, toolCallId, fetchedAt }`. Ids are `S1`, `S2`, … and the same URL reuses its id. One package-state write per new source.
+
+The ledger reads tool results by name. It does not import `tools-web`, `tools-browser`, or `memory-rag`.
+
+## Capabilities
+
+`session-state` — the ledger and the verdict live in per-session package state.
+
+## Cost, security, and failure behavior
+
+Each repair is one extra model turn, bounded by `maxRepairs` (default 1). `maxRepairs: 0` avoids it. The kernel also caps continuations (`limits.maxContinuations`, default 1). Set that ceiling at least as high as `maxRepairs`, or a repair request is dropped and the verdict stays `pending`.
+
+`run.end` continues while repairs remain and a marker does not resolve. The first continue wins, so do not list another `run.end` package (such as `hooks-json`) on the same agent. After the bound, the verdict is `failed` and the package emits `research.citations.unresolved`. It does not throw.
+
+A ledger at `maxSources` stops recording and writes one `warn` status note. A configured source tool that is not registered writes one `info` note. Neither throws.
+
+Ledger entries store the URL, title, tool name, and ids only. Userinfo and the `redactQuery` parameters are stripped. Result bodies and tool arguments are not stored.
+
+## Example
+
+```ts
+import { createAgent } from "@arnilo/prism";
+import { mockProvider } from "@arnilo/prism/testing";
+import toolsResearch from "@arnilo/prism-tools/research";
+
+const agent = await createAgent({
+  model: { provider: "mock", model: "m" },
+  packages: [mockProvider(), toolsResearch({ maxRepairs: 0, requireCitations: true })],
+});
+const session = await agent.session({ id: "report", create: true });
+await agent.commands.run("research.verify", {}, { session });
+// → { verdict: "pending", unresolved: [], ledgerSize: 0 }
+```

package/research/skills/research-report/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: research-report
+description: Use when writing the report. Every factual claim cites a ledger id with a marker from the cite tool.
+metadata:
+  prism-requires-tools: cite
+---
+
+# Research report
+
+1. Call `cite` with a ledger id. It returns `[[cite:<id>]]` when that id was fetched, and `unknown_source` otherwise.
+2. Put that marker next to the claim. Do not invent a marker or an id.
+3. A marker the ledger does not hold fails the citation check.

package/research/skills/research-scoping/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: research-scoping
+description: Use before any fetch. Turns a research question into a bounded question, inclusion rules, and the sources worth fetching.
+---
+
+# Research scoping
+
+1. Restate the question in one sentence.
+2. List what would count as a source and what to ignore.
+3. Name the searches to run. Do not fetch yet.

package/research/skills/research-synthesis/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: research-synthesis
+description: Use after triage and before the report. Groups the kept sources into claims, each tied to ledger ids.
+---
+
+# Research synthesis
+
+1. One claim per cluster of ledger ids.
+2. A claim with no ledger id is not ready to report.
+3. Do not invent an id. Only ids printed as `ledger: S<n>` exist.

package/research/skills/source-triage/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: source-triage
+description: Use after ledger lines appear on tool results. Decides which fetched sources belong in the report.
+---
+
+# Source triage
+
+1. Read each `ledger: S<n>` line. That id is the only handle for the source.
+2. Keep a source only when it bears on the scoped question.
+3. Drop duplicates. The same URL keeps one id.

package/research/src/check.ts

@@ -0,0 +1,71 @@
+import { UNTRUSTED_EXTERNAL_TRUST, type Message, type ToolResult } from "@arnilo/prism";
+
+import type { LedgerEntry, ResearchState } from "./ledger.js";
+
+const MARKER = /\[\[cite:([A-Za-z0-9_-]+)\]\]/g;
+export const NO_CITATIONS = "<no-citations>";
+
+export function lastAssistantText(history: readonly Message[]): string {
+  for (let i = history.length - 1; i >= 0; i -= 1) {
+    const message = history[i];
+    if (message?.role !== "assistant") continue;
+    return message.content.flatMap((part) => (part.type === "text" ? [part.text] : [])).join("");
+  }
+  return "";
+}
+
+export function citationIds(text: string): readonly string[] {
+  const ids: string[] = [];
+  for (const match of text.matchAll(MARKER)) {
+    const id = match[1];
+    if (id !== undefined && !ids.includes(id)) ids.push(id);
+  }
+  return ids;
+}
+
+export function unresolvedIds(ids: readonly string[], entries: readonly LedgerEntry[], requireCitations: boolean): readonly string[] {
+  const known = new Set(entries.map((entry) => entry.id));
+  const missing = ids.filter((id) => !known.has(id));
+  if (missing.length === 0 && ids.length === 0 && requireCitations) return [NO_CITATIONS];
+  return missing;
+}
+
+export function citationDecision(
+  state: ResearchState,
+  unresolved: readonly string[],
+  maxRepairs: number,
+): { readonly state: ResearchState; readonly continueReason?: string } {
+  if (unresolved.length === 0) {
+    return { state: { ...state, verdict: "passed", unresolved: [] } };
+  }
+  if (state.repairs < maxRepairs) {
+    return {
+      state: { ...state, repairs: state.repairs + 1, unresolved },
+      continueReason: `Unresolved citations: ${unresolved.join(", ")}. Cite only ledger ids from ledger: S<n> lines, using cite.`,
+    };
+  }
+  return { state: { ...state, verdict: "failed", unresolved } };
+}
+
+export function withLedgerLine(result: ToolResult, line: string): ToolResult {
+  const note = { type: "text" as const, text: line };
+  // Untrusted results reach the model as their text content (the kernel envelope), so the line rides
+  // the text. Trusted results still drop text when `value` is set, so they keep the copy in `value`.
+  const untrusted = result.metadata?.trust === UNTRUSTED_EXTERNAL_TRUST;
+  const value =
+    !untrusted && typeof result.value === "object" && result.value !== null && !Array.isArray(result.value)
+      ? { ...result.value, ledger: line }
+      : result.value;
+  return {
+    toolCallId: result.toolCallId,
+    name: result.name,
+    content: [...(result.content ?? []), note],
+    ...(value === undefined ? {} : { value }),
+    ...(result.error === undefined ? {} : { error: result.error }),
+    ...(result.metadata === undefined ? {} : { metadata: result.metadata }),
+  };
+}
+
+export function citeMarker(id: string): string {
+  return `[[cite:${id}]]`;
+}

package/research/src/config.ts

@@ -0,0 +1,41 @@
+import type { JsonSchema } from "@arnilo/prism";
+
+/** Tools whose results are ledger sources. A name that is never registered is noted, not rejected. */
+export const DEFAULT_SOURCE_TOOLS = ["web_fetch", "web_search", "web_extract", "browser_observe", "rag_search"] as const;
+
+/** Query parameter names stripped before a URL is stored. */
+export const DEFAULT_REDACT_QUERY = ["key", "token", "api_key", "access_token", "sig", "signature"] as const;
+
+export const DEFAULT_MAX_REPAIRS = 1;
+export const HARD_MAX_REPAIRS = 3;
+export const DEFAULT_MAX_SOURCES = 500;
+export const HARD_MAX_SOURCES = 5_000;
+
+export interface ToolsResearchConfig {
+  readonly sourceTools?: readonly string[];
+  /** Extra model turns spent repairing unresolved citations. `0` spends none. */
+  readonly maxRepairs?: number;
+  /** Ledger size at which recording stops. */
+  readonly maxSources?: number;
+  /** A report with no `[[cite:<id>]]` markers counts as unresolved. Default false. */
+  readonly requireCitations?: boolean;
+  readonly redactQuery?: readonly string[];
+}
+
+const stringList = (maxItems: number): JsonSchema => ({
+  type: "array",
+  maxItems,
+  items: { type: "string", minLength: 1, maxLength: 64 },
+});
+
+export const toolsResearchConfigSchema: JsonSchema = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    sourceTools: { ...stringList(32), default: [...DEFAULT_SOURCE_TOOLS] },
+    maxRepairs: { type: "integer", minimum: 0, maximum: HARD_MAX_REPAIRS, default: DEFAULT_MAX_REPAIRS },
+    maxSources: { type: "integer", minimum: 1, maximum: HARD_MAX_SOURCES, default: DEFAULT_MAX_SOURCES },
+    requireCitations: { type: "boolean", default: false },
+    redactQuery: { ...stringList(32), default: [...DEFAULT_REDACT_QUERY] },
+  },
+};

package/research/src/index.ts

@@ -0,0 +1,147 @@
+/**
+ * `@arnilo/prism-tools/research` — research skills, a source ledger, and a citation check.
+ *
+ * `tool.result` records sources from the configured tool names. `cite` returns a `[[cite:<id>]]`
+ * marker for a ledger id. `run.end` continues while repairs remain, then records a failed verdict.
+ * `maxRepairs: 0` spends no extra model turn.
+ */
+
+import { fileURLToPath } from "node:url";
+import { definePackage, type JsonValue, type PackageInstance, type SessionContext, type ToolResult } from "@arnilo/prism";
+import manifest from "../../package.json" with { type: "json" };
+
+import { citationDecision, citationIds, citeMarker, lastAssistantText, unresolvedIds, withLedgerLine } from "./check.js";
+import { type ToolsResearchConfig, toolsResearchConfigSchema } from "./config.js";
+import { EMPTY_STATE, ledgerLine, type ResearchState, recordSources, sourcesIn } from "./ledger.js";
+
+const PACKAGE = "@arnilo/prism-tools/research";
+
+interface Flags {
+  readonly missingNoted: boolean;
+  readonly capNoted: boolean;
+}
+
+const EMPTY_FLAGS: Flags = { missingNoted: false, capNoted: false };
+
+const definition = definePackage<ToolsResearchConfig>({
+  name: PACKAGE,
+  version: manifest.version,
+  description: "Research skills, a per-session source ledger, cite, and a bounded citation check.",
+  requires: { api: 1 },
+  capabilities: ["session-state"],
+  config: toolsResearchConfigSchema,
+  setup(prism) {
+    // Session state stores JSON. ResearchState is that object; it has no index signature.
+    const research = prism.state.session("research", EMPTY_STATE as unknown as JsonValue);
+    const flags = prism.state.agent("flags", EMPTY_FLAGS);
+    const sourceTools = new Set(prism.config.sourceTools ?? []);
+
+    const noteMissing = (): void => {
+      const current = flags.get();
+      if (current.missingNoted) return;
+      const registered = new Set(prism.tools.list().map((tool) => tool.name));
+      const missing = [...sourceTools].filter((name) => !registered.has(name));
+      if (missing.length === 0) return;
+      prism.status.note("info", `source tools not registered: ${missing.join(", ")}`);
+      flags.set({ ...flags.get(), missingNoted: true });
+    };
+
+    const read = (session: SessionContext): ResearchState => (research.get(session) as unknown as ResearchState | undefined) ?? EMPTY_STATE;
+
+    prism.hooks.on(
+      "tool.result",
+      (result, context) => {
+        noteMissing();
+        if (!sourceTools.has(result.name) || result.error !== undefined || context.session === undefined) return undefined;
+        const before = read(context.session);
+        const recorded = recordSources(before, sourcesIn(result.name, result.value, prism.config.redactQuery ?? []), {
+          tool: result.name,
+          toolCallId: result.toolCallId,
+          fetchedAt: new Date().toISOString(),
+          maxSources: prism.config.maxSources ?? 500,
+        });
+        if (recorded.cappedNow && !flags.get().capNoted) {
+          prism.status.note("warn", `ledger reached maxSources (${prism.config.maxSources}); further sources are not recorded`);
+          flags.set({ ...flags.get(), capNoted: true });
+        }
+        if (recorded.state === before) return undefined;
+        research.set(context.session, recorded.state as unknown as JsonValue);
+        return recorded.added.length === 0 ? undefined : withLedgerLine(result, ledgerLine(recorded.added));
+      },
+      { id: "ledger" },
+    );
+
+    prism.hooks.on(
+      "run.end",
+      (payload, context) => {
+        noteMissing();
+        if (context.session === undefined) return undefined;
+        const current = read(context.session);
+        const decision = citationDecision(
+          current,
+          unresolvedIds(citationIds(lastAssistantText(payload.history)), current.entries, prism.config.requireCitations === true),
+          prism.config.maxRepairs ?? 1,
+        );
+        research.set(context.session, decision.state as unknown as JsonValue);
+        if (decision.state.verdict === "failed") {
+          context.emit("research.citations.unresolved", { unresolved: [...decision.state.unresolved] });
+        }
+        return decision.continueReason === undefined ? undefined : { continue: { reason: decision.continueReason } };
+      },
+      { id: "citations" },
+    );
+
+    prism.tools.register({
+      name: "cite",
+      description:
+        "Return a [[cite:<id>]] marker for a source already in this session's ledger. Fails with unknown_source when the id was not fetched.",
+      effects: [],
+      parameters: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          id: { type: "string", minLength: 1, maxLength: 64 },
+          quote: { type: "string", maxLength: 500 },
+        },
+        required: ["id"],
+      },
+      execute(args, context): ToolResult {
+        const id = typeof args.id === "string" ? args.id : "";
+        const known = context.session !== undefined && read(context.session).entries.some((entry) => entry.id === id);
+        if (!known) {
+          return {
+            toolCallId: context.toolCallId,
+            name: "cite",
+            error: { code: "unknown_source", message: `unknown source ${id}` },
+            content: [{ type: "text", text: `unknown_source: ${id}` }],
+          };
+        }
+        return {
+          toolCallId: context.toolCallId,
+          name: "cite",
+          value: { id },
+          content: [{ type: "text", text: citeMarker(id) }],
+        };
+      },
+    });
+
+    prism.commands.register({
+      name: "research.verify",
+      description: "Return the citation verdict, unresolved ids, and ledger size for a session.",
+      run(_args, context) {
+        if (context.session === undefined) return { verdict: "pending", unresolved: [], ledgerSize: 0 };
+        const state = read(context.session);
+        return { verdict: state.verdict, unresolved: [...state.unresolved], ledgerSize: state.entries.length };
+      },
+    });
+
+    prism.skills.addDir(fileURLToPath(new URL("../skills", import.meta.url)));
+  },
+});
+
+export default definition;
+
+/** The package with config baked in, for `packages: [toolsResearch({ maxRepairs: 0 })]`. */
+export function toolsResearch(config: ToolsResearchConfig = {}): PackageInstance {
+  return definition(config);
+}