@arnilo/prism-tools 0.0.0-stage → 0.13.1

package/web/src/transport.ts

@@ -0,0 +1,310 @@
+import { type JsonValue, redactSecrets } from "@arnilo/prism";
+import { isLoopbackHostname } from "@arnilo/prism/net";
+import { resolveWebLimits } from "./limits.js";
+import type { ResolvedWebLimits, WebAdapterOptions, WebProvider, WebProviderMetadata } from "./types.js";
+
+export class WebToolError extends Error {
+  readonly code: string;
+  constructor(code: string, message: string) {
+    super(message);
+    this.name = "WebToolError";
+    this.code = code;
+  }
+}
+
+/**
+ * How a request may be retried, chosen by what a provider bills:
+ * - `idempotent`: a GET — retry a connection failure and any 429/5xx.
+ * - `safe-post`: a POST that creates or bills nothing twice on a 429 retry — retry a connection
+ *   failure and a 429, never a 5xx (the request may already have been accepted).
+ * - `never`: retry nothing, so a paid job is never submitted twice.
+ */
+export type WebRetryMode = "idempotent" | "safe-post" | "never";
+
+export interface WebTransport {
+  readonly limits: ResolvedWebLimits;
+  run<T>(signal: AbortSignal | undefined, operation: (signal: AbortSignal) => Promise<T>): Promise<T>;
+  json(
+    provider: WebProvider,
+    credentialName: string,
+    url: URL,
+    init: RequestInit,
+    signal: AbortSignal,
+    options?: { readonly retry?: WebRetryMode },
+  ): Promise<{ value: unknown; metadata?: WebProviderMetadata }>;
+}
+
+/** How a transport authenticates and whether it may reach a plaintext loopback origin. */
+export interface WebTransportOptions {
+  /** Accept an `http://` origin only when its hostname is loopback (SearXNG on the same machine). */
+  readonly allowLoopback?: boolean;
+  /** `bearer` (default), `bot` (`Authorization: Bot <key>`, Kagi v1), or `none` (a keyless backend). */
+  readonly auth?: "bearer" | "bot" | "none";
+}
+
+export function createWebTransport(
+  provider: WebProvider,
+  apiOrigin: string,
+  options: WebAdapterOptions,
+  transport: WebTransportOptions = {},
+): WebTransport {
+  const limits = resolveWebLimits(options.limits),
+    origin = new URL(apiOrigin).origin;
+  const allowed = (options.allowedOrigins ?? [origin]).map((value) => {
+    let parsed: URL;
+    try {
+      parsed = new URL(value);
+    } catch {
+      throw new WebToolError("ERR_PRISM_WEB_ORIGIN", "Provider API origin is invalid");
+    }
+    // Plaintext is allowed only where it cannot leave the machine: an explicitly opted-in loopback origin.
+    const loopback = parsed.protocol === "http:" && transport.allowLoopback === true && isLoopbackHostname(parsed.hostname);
+    if (
+      (!loopback && parsed.protocol !== "https:") ||
+      parsed.username ||
+      parsed.password ||
+      parsed.pathname !== "/" ||
+      parsed.search ||
+      parsed.hash ||
+      value !== parsed.origin
+    )
+      throw new WebToolError(
+        "ERR_PRISM_WEB_ORIGIN",
+        "Provider API origins must be exact HTTPS origins (loopback HTTP only with allowLoopback)",
+      );
+    return parsed.origin;
+  });
+  if (!allowed.includes(origin)) throw new WebToolError("ERR_PRISM_WEB_ORIGIN", `Required ${provider} API origin is not allowed`);
+  let active = 0;
+  const waiters: Array<() => void> = [];
+  const acquire = async (signal: AbortSignal) => {
+    if (active < limits.maxConcurrency) {
+      active++;
+      return;
+    }
+    // Past the queue bound a call fails; up to it, a call waits for the next free slot.
+    if (waiters.length >= limits.maxQueued) throw new WebToolError("ERR_PRISM_WEB_LIMIT", "Web operation queue is full");
+    await new Promise<void>((resolve, reject) => {
+      const start = () => {
+        signal.removeEventListener("abort", abort);
+        active++;
+        resolve();
+      };
+      const abort = () => {
+        const i = waiters.indexOf(start);
+        if (i >= 0) waiters.splice(i, 1);
+        reject(signal.reason);
+      };
+      waiters.push(start);
+      signal.addEventListener("abort", abort, { once: true });
+    });
+  };
+  const release = () => {
+    active--;
+    waiters.shift()?.();
+  };
+  const sleep =
+    options.sleep ??
+    ((ms: number, signal: AbortSignal) =>
+      new Promise<void>((resolve, reject) => {
+        try {
+          signal.throwIfAborted();
+        } catch (error) {
+          reject(error);
+          return;
+        }
+        const timer = setTimeout(done, ms);
+        function done() {
+          cleanup();
+          resolve();
+        }
+        function abort() {
+          clearTimeout(timer);
+          cleanup();
+          reject(signal.reason);
+        }
+        function cleanup() {
+          signal.removeEventListener("abort", abort);
+        }
+        signal.addEventListener("abort", abort, { once: true });
+      }));
+  const fetcher = options.fetch ?? globalThis.fetch;
+  return {
+    limits,
+    async run(signal, operation) {
+      const timeout = AbortSignal.timeout(limits.timeoutMs);
+      const combined = signal ? AbortSignal.any([signal, timeout]) : timeout;
+      let acquired = false;
+      try {
+        combined.throwIfAborted();
+        await acquire(combined);
+        acquired = true;
+        return await operation(combined);
+      } catch (error) {
+        if (combined.aborted)
+          throw new WebToolError("ERR_PRISM_WEB_ABORTED", signal?.aborted ? "Web operation aborted" : "Web operation timed out");
+        throw error;
+      } finally {
+        if (acquired) release();
+      }
+    },
+    async json(_provider, _credentialName, url, init, signal, request = {}) {
+      const retry = request.retry ?? "idempotent";
+      const mayRetryStatus = (status: number) =>
+        retry === "idempotent" ? status === 429 || status >= 500 : retry === "safe-post" ? status === 429 : false;
+      if (url.origin !== origin) throw new WebToolError("ERR_PRISM_WEB_ORIGIN", `${provider} request origin is not allowed`);
+      let credential: string | undefined;
+      if (transport.auth !== "none") {
+        try {
+          credential = await options.credentials();
+        } catch {
+          throw new WebToolError("ERR_PRISM_WEB_CREDENTIAL", `${provider} credential resolution failed`);
+        }
+        if (!credential) throw new WebToolError("ERR_PRISM_WEB_CREDENTIAL", `${provider} credential is unavailable`);
+      }
+      const requestBytes = typeof init.body === "string" ? Buffer.byteLength(init.body) : 0;
+      if (requestBytes > limits.maxRequestBytes) throw new WebToolError("ERR_PRISM_WEB_LIMIT", "Web request exceeds byte limit");
+      for (let attempt = 0; ; attempt++) {
+        let response: Response;
+        try {
+          response = await fetcher(url, {
+            ...init,
+            redirect: "error",
+            signal,
+            headers: {
+              "content-type": "application/json",
+              ...init.headers,
+              ...(credential === undefined
+                ? {}
+                : transport.auth === "bot"
+                  ? { authorization: `Bot ${credential}` }
+                  : provider === "brave"
+                    ? { "x-subscription-token": credential }
+                    : { authorization: `Bearer ${credential}` }),
+            },
+          });
+        } catch (error) {
+          if (signal.aborted) throw error;
+          // A connection failure produced no response, so no retry mode rules it out except `never`.
+          if (retry === "never" || attempt >= limits.maxRetries)
+            throw new WebToolError("ERR_PRISM_WEB_REQUEST", `${provider} request failed`);
+          await sleep(Math.min(250 * 2 ** attempt, limits.maxRateLimitDelayMs), signal);
+          continue;
+        }
+        const metadata = responseMetadata(response);
+        if (mayRetryStatus(response.status) && attempt < limits.maxRetries) {
+          await response.body?.cancel();
+          await sleep(Math.min(metadata?.rate?.retryAfterMs ?? 250 * 2 ** attempt, limits.maxRateLimitDelayMs), signal);
+          continue;
+        }
+        if (!response.ok) {
+          await response.body?.cancel();
+          throw new WebToolError("ERR_PRISM_WEB_RESPONSE", `${provider} request failed with status ${response.status}`);
+        }
+        const text = await readBoundedText(response, limits.maxResponseBytes, signal);
+        try {
+          const value: unknown = redactSecrets(JSON.parse(text), credential === undefined ? [] : [credential]);
+          assertBoundedJson(value, limits.maxJsonDepth, limits.maxJsonProperties, limits.maxResponseBytes);
+          return { value, metadata };
+        } catch (error) {
+          if (error instanceof WebToolError) throw error;
+          throw new WebToolError("ERR_PRISM_WEB_RESPONSE", `${provider} returned invalid JSON`);
+        }
+      }
+    },
+  };
+}
+
+export function boundedJson<T>(value: T, maxDepth: number, maxProperties: number, maxBytes: number): T {
+  let clone: T;
+  try {
+    // Deliberate JSON round-trip, not structuredClone: normalizes the value to its wire shape (drops undefined keys) before bounds validation.
+    clone = JSON.parse(JSON.stringify(value)) as T;
+  } catch {
+    throw new WebToolError("ERR_PRISM_WEB_JSON", "JSON value is cyclic or unserializable");
+  }
+  assertBoundedJson(clone, maxDepth, maxProperties, maxBytes);
+  return clone;
+}
+
+export function assertBoundedJson(value: unknown, maxDepth: number, maxProperties: number, maxBytes: number): asserts value is JsonValue {
+  let properties = 0,
+    bytes: number;
+  try {
+    bytes = Buffer.byteLength(JSON.stringify(value));
+  } catch {
+    throw new WebToolError("ERR_PRISM_WEB_JSON", "JSON value is cyclic or unserializable");
+  }
+  if (bytes > maxBytes) throw new WebToolError("ERR_PRISM_WEB_LIMIT", "JSON value exceeds byte limit");
+  const stack: Array<[unknown, number]> = [[value, 0]];
+  while (stack.length) {
+    const [entry, depth] = stack.pop()!;
+    if (depth > maxDepth) throw new WebToolError("ERR_PRISM_WEB_LIMIT", "JSON value exceeds depth limit");
+    if (entry === null || typeof entry === "string" || typeof entry === "boolean") continue;
+    if (typeof entry === "number") {
+      if (!Number.isFinite(entry)) throw new WebToolError("ERR_PRISM_WEB_JSON", "JSON number must be finite");
+      continue;
+    }
+    if (typeof entry !== "object") throw new WebToolError("ERR_PRISM_WEB_JSON", "Value is not JSON");
+    const values = Array.isArray(entry) ? entry : Object.values(entry);
+    if (!Array.isArray(entry)) {
+      for (const key of Object.keys(entry))
+        if (["__proto__", "prototype", "constructor"].includes(key))
+          throw new WebToolError("ERR_PRISM_WEB_JSON", "JSON contains forbidden key");
+      properties += values.length;
+      if (properties > maxProperties) throw new WebToolError("ERR_PRISM_WEB_LIMIT", "JSON value exceeds property limit");
+    }
+    for (const child of values) stack.push([child, depth + 1]);
+  }
+}
+
+async function readBoundedText(response: Response, maxBytes: number, signal: AbortSignal): Promise<string> {
+  if (!response.body) return "";
+  const reader = response.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  try {
+    for (;;) {
+      signal.throwIfAborted();
+      const { done, value } = await reader.read();
+      if (done) break;
+      total += value.byteLength;
+      if (total > maxBytes) throw new WebToolError("ERR_PRISM_WEB_LIMIT", "Web response exceeds byte limit");
+      chunks.push(value);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  const bytes = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+}
+/** `Retry-After` is either delay-seconds or an HTTP date (RFC 9110 §10.2.3); both become a delay from now. */
+function retryAfterDelayMs(header: string | null): number | undefined {
+  if (!header) return undefined;
+  if (/^\d+(?:\.\d+)?$/u.test(header)) return Number(header) * 1000;
+  const at = Date.parse(header);
+  return Number.isNaN(at) ? undefined : Math.max(0, at - Date.now());
+}
+
+function responseMetadata(response: Response): WebProviderMetadata | undefined {
+  const number = (name: string) => {
+    const value = response.headers.get(name);
+    return value && /^\d+$/u.test(value) ? Number(value) : undefined;
+  };
+  const retryAfterMs = retryAfterDelayMs(response.headers.get("retry-after"));
+  const metadata = {
+    requestId: response.headers.get("x-request-id") ?? undefined,
+    rate: {
+      limit: number("x-ratelimit-limit"),
+      remaining: number("x-ratelimit-remaining"),
+      reset: response.headers.get("x-ratelimit-reset") ?? undefined,
+      retryAfterMs,
+    },
+  };
+  return metadata.requestId || Object.values(metadata.rate).some((v) => v !== undefined) ? metadata : undefined;
+}

package/web/src/types.ts

@@ -0,0 +1,199 @@
+import type { JsonObject, JsonValue, SsrfPolicy, ToolArgumentValidator, ToolDefinition, Usage } from "@arnilo/prism";
+
+import type { DomainPolicy } from "./domains.js";
+
+export type WebProvider = "brave" | "exa" | "firecrawl" | "native" | "obscura" | "searxng" | "tavily" | "kagi";
+/** The backends that answer `web_search` (the others are fetch/extract only). */
+export type WebSearchProvider = "brave" | "exa" | "searxng" | "tavily" | "kagi";
+export interface WebRateMetadata {
+  readonly limit?: number;
+  readonly remaining?: number;
+  readonly reset?: string;
+  readonly retryAfterMs?: number;
+}
+export interface WebProviderMetadata {
+  readonly requestId?: string;
+  readonly cost?: JsonValue;
+  readonly rate?: WebRateMetadata;
+}
+export interface WebCitation {
+  readonly citationId: string;
+  readonly provider: WebProvider;
+  readonly sourceId?: string;
+  readonly url: string;
+}
+export interface WebSearchResult extends WebCitation {
+  readonly title?: string;
+  readonly snippet?: string;
+  readonly highlights?: readonly string[];
+  readonly publishedAt?: string;
+  readonly retrievedAt: string;
+}
+export interface WebSearchResponse {
+  readonly provider: WebSearchProvider;
+  readonly query: string;
+  readonly results: readonly WebSearchResult[];
+  /** Results dropped by the host domain policy. */
+  readonly filtered?: number;
+  readonly metadata?: WebProviderMetadata;
+  readonly untrusted: true;
+}
+export interface WebDocument extends WebCitation {
+  readonly title?: string;
+  readonly markdown: string;
+  /** The page was longer than the fetch limit; `markdown` keeps its head only. */
+  readonly sourceTruncated?: boolean;
+  /** Targets followed, in order; `url` is the final one. Only the `native` backend reports them. */
+  readonly redirects?: readonly string[];
+  readonly retrievedAt: string;
+  /** Served from the session cache; `cachedAgeMs` is how old the stored copy is. Only with `cache` config. */
+  readonly cached?: true;
+  readonly cachedAgeMs?: number;
+  readonly metadata?: WebProviderMetadata;
+  readonly untrusted: true;
+}
+export interface WebExtraction {
+  readonly provider: "firecrawl";
+  readonly urls: readonly string[];
+  readonly data: JsonValue;
+  readonly retrievedAt: string;
+  readonly metadata?: WebProviderMetadata;
+  readonly untrusted: true;
+}
+
+export interface WebLimits {
+  readonly maxQueryBytes?: number;
+  readonly maxResults?: number;
+  readonly maxUrls?: number;
+  readonly maxRequestBytes?: number;
+  readonly maxResponseBytes?: number;
+  readonly maxMarkdownBytes?: number;
+  readonly maxExtractBytes?: number;
+  readonly maxSchemaBytes?: number;
+  readonly maxAggregateBytes?: number;
+  readonly maxJsonDepth?: number;
+  readonly maxJsonProperties?: number;
+  readonly maxRetries?: number;
+  readonly maxRateLimitDelayMs?: number;
+  readonly maxConcurrency?: number;
+  /** Calls waiting for a slot; only past this many does the transport refuse a new one. */
+  readonly maxQueued?: number;
+  readonly maxPollingAttempts?: number;
+  readonly pollingDelayMs?: number;
+  readonly timeoutMs?: number;
+}
+export type ResolvedWebLimits = Required<WebLimits>;
+/** A lazily resolved key (the kit's `SecretSource` shape); the package builds it from an `env:`/`keyring:` ref. A literal string does not type-check. */
+export type WebCredentialSource = () => Promise<string | undefined>;
+export interface WebAdapterOptions {
+  readonly credentials: WebCredentialSource;
+  readonly allowedOrigins?: readonly string[];
+  readonly fetch?: typeof globalThis.fetch;
+  readonly limits?: WebLimits;
+  readonly sleep?: (ms: number, signal: AbortSignal) => Promise<void>;
+}
+export type SearchFreshness = "day" | "week" | "month" | "year";
+/** Structured search controls: the tool schema exposes only what a backend supports. */
+export interface SearchControls {
+  readonly freshness?: SearchFreshness;
+  readonly includeDomains?: readonly string[];
+  readonly excludeDomains?: readonly string[];
+  readonly country?: string;
+  readonly language?: string;
+  readonly offset?: number;
+}
+export type SearchControl = keyof SearchControls;
+/** Narrowed value sets for a control a backend supports only partly (the tool schema follows them). */
+export interface WebSearchControlValues {
+  readonly freshness?: readonly SearchFreshness[];
+}
+export interface WebSearchCall extends SearchControls {
+  readonly count?: number;
+  readonly signal?: AbortSignal;
+}
+export interface WebSearchAdapter {
+  readonly provider: WebSearchProvider;
+  /** Resolved limits, so `web_search` can state the real `count` maximum. */
+  readonly limits?: WebLimits;
+  /** One table per adapter, read by the tool builder and by the adapter's own validation. */
+  readonly supports: ReadonlySet<SearchControl>;
+  /** The values a backend accepts for a supported control, when it accepts only some (e.g. no `week`). */
+  readonly controlValues?: WebSearchControlValues;
+  search(query: string, options?: WebSearchCall): Promise<WebSearchResponse>;
+}
+/** One fetch request. `sessionId` opts into the per-session cache; `refresh` bypasses a cached page. */
+export interface WebFetchOptions {
+  readonly signal?: AbortSignal;
+  /** Lowers the Markdown kept (`maxMarkdownBytes` is the ceiling) and flags the truncation. */
+  readonly maxBytes?: number;
+  /** The session the page belongs to. Without it the cache is not consulted and nothing is stored. */
+  readonly sessionId?: string;
+  /** Fetch again even when the session has a fresh cached page. */
+  readonly refresh?: boolean;
+}
+export interface WebFetchAdapter {
+  readonly provider: "firecrawl" | "native";
+  fetch(url: string, options?: WebFetchOptions): Promise<WebDocument>;
+}
+export interface WebExtractAdapter {
+  readonly provider: "firecrawl";
+  extract(urls: readonly string[], options?: { readonly signal?: AbortSignal }): Promise<WebExtraction>;
+}
+export interface FirecrawlTargetPolicy {
+  readonly ssrf?: SsrfPolicy;
+  readonly validateUrl?: (url: URL, signal?: AbortSignal) => void | Promise<void>;
+}
+export interface FirecrawlExtractOptions extends WebAdapterOptions, FirecrawlTargetPolicy {
+  readonly schema: JsonObject;
+  readonly validator: ToolArgumentValidator;
+}
+export interface FirecrawlFetchOptions extends WebAdapterOptions, FirecrawlTargetPolicy {}
+/** A page and how long ago it was fetched, as the cache returns it. */
+export interface CachedPage {
+  readonly document: WebDocument;
+  readonly ageMs: number;
+}
+/**
+ * A session-scoped page cache. `annotated` marks entries with `cached`/`cachedAgeMs` and adds the
+ * model's `refresh` argument; the fixed memo Prism keeps without `cache` config is anonymous.
+ */
+export interface FetchCache {
+  readonly annotated: boolean;
+  /** Keyed by session id plus canonical URL; `undefined` never matches and never stores. */
+  read(sessionId: string | undefined, url: string, now?: number): CachedPage | undefined;
+  write(sessionId: string | undefined, url: string, document: WebDocument): void;
+  /** Drops one session's pages; called from the `session.closed` hook. */
+  dropSession(sessionId: string): void;
+}
+/** The answer to a `web_fetch` question, plus what the sub-call cost (outside the run's budget). */
+export interface PromptAnswer {
+  readonly answer: string;
+  readonly inputChars: number;
+  readonly sourceTruncated: boolean;
+  readonly usage?: Usage;
+}
+/** Opt-in `fetch.prompt` support: one bounded, tool-free model call over the page. */
+export interface PromptFetch {
+  answer(page: WebDocument, question: string, options?: { readonly signal?: AbortSignal }): Promise<PromptAnswer>;
+}
+export interface WebToolsOptions {
+  readonly search?: WebSearchAdapter;
+  readonly fetch?: WebFetchAdapter;
+  readonly extract?: WebExtractAdapter;
+  /** Host-owned permission: filters search rows and refuses non-permitted fetch/extract targets. */
+  readonly domains?: DomainPolicy;
+  /** Per-session page cache; without it `web_fetch` uses the short anonymous paging memo. */
+  readonly cache?: FetchCache;
+  /** Adds the `web_fetch` `prompt` argument: one model call answers a question from the page. */
+  readonly prompt?: PromptFetch;
+}
+
+/** The `web.fetch` service `@arnilo/prism-tools/web` provides when a fetch backend is configured. */
+export interface WebFetchService {
+  fetch(url: string, options?: WebFetchOptions): Promise<WebDocument>;
+}
+/**
+ * @deprecated No replacement: nothing reads it since the 0.13 split. Kept for the deprecation
+ * wave and removed at the next breaking cut (docs/_evidence/dead-export-verification-2026-09-03.md).
+ */
+export type WebToolSet = readonly ToolDefinition[];

package/work/README.md

@@ -0,0 +1,77 @@
+# @arnilo/prism-tools/work
+
+First-party work tools for Prism: Office documents, spreadsheets, diagrams, M365/Google connectors, and a bounded document reader, as one package with a `definePackage` entry and the 0.12 family subpaths kept for direct imports.
+
+```ts
+import toolsWork from "@arnilo/prism-tools/work";
+import { createAgent } from "@arnilo/prism";
+
+const agent = await createAgent({
+  model,
+  packages: [toolsWork({ root: process.cwd() })],
+});
+```
+
+## What it registers
+
+| Group | Tools | Effects | Enabled by |
+| --- | --- | --- | --- |
+| Office documents | `office_parse`, `office_import`, `office_diff`, `office_preview` | `read` | `office.enabled` (default `true`) |
+| Office documents | `office_generate`, `office_patch` | `write` | `office.enabled` (default `true`) |
+| Sandbox exec | `work_exec` | `execute` | `work.enabled` (default `true`) plus a host `work.sandbox` service |
+| Connectors | `m365_*` / `gws_*` | `network` (reads) or `network` + `external` (drafts/writes) | a resolvable `connectors.*.credential` ref |
+
+`office_parse` / `office_import` return results tagged `trust: "untrusted_external"`, which the kernel
+wraps in its envelope (`docs/tools.md`). `work_exec` runs an argv command inside the host-injected `WorkSandbox`; without that service the package notes why and registers the rest.
+
+The bounded document reader is **not** a tool: it is provided as the `work.reader` service so `@arnilo/prism-tools/coding`'s `read` tool can consume it.
+
+The vendored Hermes MIT skills (`docx`, `xlsx`, `powerpoint`, `pdf`) are registered by `loadWorkSkills()` from `vendor/hermes-agent/skills/productivity`, each declaring `requiresTools: work_exec` (`WORK_SKILL_REQUIRES_TOOLS`). They teach `python`, `openpyxl`, `python-docx`, `pypdf` and `soffice` run through the sandbox and never name an `office_*` tool, so a request without `work_exec` (no `work.sandbox` service) hides them. The vendored bytes are unchanged and pinned by `vendor-lock.json`; their 9.6-12.5 KB bodies are the one recorded size exception to the package-skill body cap.
+
+## Config
+
+| Field | Default | Notes |
+| --- | --- | --- |
+| `root` | — | **Required.** Absolute workspace root the file-touching tools stay inside. |
+| `office.enabled` | `true` | `false` registers no `office_*` tool. |
+| `office.maxBytes` | document cap default | OOXML byte cap. |
+| `work.enabled` | `true` | `false` drops `work_exec`. |
+| `reader.formats` | all four | `["pdf", "docx", "xlsx", "pptx"]` subset. A format whose optional peer is missing is dropped with one warn note. |
+| `reader.maxBytes` / `maxPages` / `maxTextBytes` | reader defaults | Hard caps. |
+| `reader.ocr` | off | `{ provider: "mistral", apiKey: "env:MISTRAL_API_KEY" }`; **one external call per page**. |
+| `connectors.microsoft365` | none | `{ credential: "keyring:m365", binary?, configDir, identity, allowedOps? }`. |
+| `connectors.google` | none | `{ credential: "keyring:gws", binary?, configDir, identity, allowedOps? }`. |
+| `env` | `{}` | Non-token env for the sandbox. `M365_*` / `GOOGLE_*` names are refused. |
+
+`connectors.*.credential` and `reader.ocr.apiKey` are ref-only (`env:NAME` or `keyring:NAME`) and resolved through `prism.credentials.resolve`; a literal fails config validation and a resolved value is redacted from events, notes, logs, errors, and tool results. A credential that resolves to a JSON object is injected as the connector's token env map; any other value becomes the provider's default access-token variable.
+
+## Optional peers
+
+| Peer | Unlocks | Missing |
+| --- | --- | --- |
+| `mammoth` | `docx` reader format | that format is dropped with a note |
+| `pdf-parse` | `pdf` reader format | that format is dropped with a note |
+| `@firecrawl/anydoc` | `/document-extraction` local Markdown conversion | `createDocumentExtractor()` throws at call time |
+
+## Direct subpath imports
+
+The family shares type names (`validateByteCap`, `CellValue`) across libraries, so a single flat barrel cannot re-export them unambiguously. The root entry holds the `definePackage` surface; the libraries stay importable as subpaths:
+
+`@arnilo/prism-tools/work/{connectors,connectors/drafts,connectors/google-workspace,connectors/microsoft365,documents,sheets,diagrams,document-extraction,document-reader,sandbox,skills,tools}`
+
+## Install
+
+```bash
+bun add @arnilo/prism @arnilo/prism-tools
+```
+
+## Security and cost
+
+- File tools stay inside `root`; paths are resolved and contained before any read or write.
+- Connector credentials and the OCR key are ref-only and redacted everywhere after resolution.
+- The worker pool starts lazily and is closed in `onDispose`.
+- OCR is off by default and costs one external Mistral call per page when enabled.
+
+## Optional Office peers
+
+Install `@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` and `fast-xml-parser@5.11.1` for Office tools and OOXML reading. Missing peers produce a status note and disable Office tools; connectors and skills still register. Direct documents, sheets and diagrams library imports require their peers. See the [bundle footprint](../README.md#dependencies-and-footprint).

package/work/THIRD_PARTY_NOTICES

@@ -0,0 +1,24 @@
+Hermes Agent productivity skills (docx, xlsx, powerpoint, pdf)
+Source: https://github.com/NousResearch/hermes-agent
+Commit: bbaf7af5c83546d19f8060f4097d3bb25cd1a3c3
+License: MIT
+
+Copyright (c) 2025 Nous Research
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.