@arnilo/prism-tools 0.0.0-stage → 0.13.1

package/work/src/documents/translate/xlsx.ts

@@ -0,0 +1,137 @@
+import {
+  type ColumnOptions,
+  generateWorkbookSync,
+  parseWorkbookSync as ooParseWorkbook,
+  type WorkbookOptions,
+  type WorksheetOptions,
+} from "@office-open/xlsx";
+import type { CellValue, SheetData, SheetModel } from "../types.js";
+
+/** Draft-07 DecimalCellValue pattern; requires a fractional part so years/ids stay strings. */
+const CANONICAL_DECIMAL = /^-?(?:0|[1-9]\d*)\.\d+$/;
+
+function mapCellValue(cell: CellValue) {
+  if (cell === null || cell === undefined) {
+    return { value: "" };
+  }
+  if (typeof cell === "string" || typeof cell === "number" || typeof cell === "boolean") {
+    return { value: cell };
+  }
+  if ("type" in cell) {
+    if (cell.type === "decimal") {
+      return { value: cell.value };
+    }
+    if (cell.type === "date" || cell.type === "datetime") {
+      return { value: cell.value };
+    }
+  }
+  if ("formula" in cell) {
+    const rawFormula = cell.formula.startsWith("=") ? cell.formula.slice(1) : cell.formula;
+    return {
+      formula: rawFormula,
+      value: cell.cachedValue !== undefined && cell.cachedValue !== null ? cell.cachedValue : undefined,
+    };
+  }
+  return { value: "" };
+}
+
+function sheetDataToWorksheet(data: SheetData): WorksheetOptions {
+  const rows = data.cells.map((row) => ({
+    cells: row.map(mapCellValue),
+  }));
+
+  const columns: ColumnOptions[] | undefined = data.columnWidths
+    ? data.columnWidths.map((cw) => ({
+        min: cw.column + 1,
+        max: cw.column + 1,
+        width: cw.width,
+      }))
+    : undefined;
+
+  const freezePanes = data.frozenPanes
+    ? {
+        row: data.frozenPanes.rows,
+        col: data.frozenPanes.columns,
+      }
+    : undefined;
+
+  return {
+    name: data.name,
+    columns,
+    freezePanes,
+    rows,
+  };
+}
+
+export function sheetModelToXlsxOptions(model: SheetModel): WorkbookOptions {
+  return {
+    worksheets: model.sheets.map(sheetDataToWorksheet),
+  };
+}
+
+export function generateXlsxBytes(model: SheetModel): Uint8Array {
+  const options = sheetModelToXlsxOptions(model);
+  const result = generateWorkbookSync(options);
+  return new Uint8Array(result);
+}
+
+export function parseXlsxBytes(bytes: Uint8Array): SheetModel {
+  const parsed = ooParseWorkbook(bytes);
+  const worksheets = parsed.worksheets ?? [];
+  const sheets: SheetData[] = [];
+
+  for (const ws of worksheets) {
+    const name = ws.name ?? "Sheet1";
+    const cells: CellValue[][] = [];
+
+    for (const row of ws.rows ?? []) {
+      const rowCells: CellValue[] = [];
+      for (const c of row.cells ?? []) {
+        if (c.formula && typeof c.formula === "object" && "formula" in c.formula && typeof c.formula.formula === "string") {
+          const raw = c.formula.formula;
+          const formulaStr = raw.startsWith("=") ? raw : `=${raw}`;
+          rowCells.push({
+            formula: formulaStr,
+            cachedValue: c.value !== undefined ? (c.value as string | number | boolean | null) : null,
+          });
+        } else if (typeof c.value === "number") {
+          rowCells.push(c.value);
+        } else if (typeof c.value === "string") {
+          rowCells.push(CANONICAL_DECIMAL.test(c.value) ? { type: "decimal", value: c.value } : c.value);
+        } else if (typeof c.value === "boolean") {
+          rowCells.push(c.value);
+        } else if (c.value === null || c.value === undefined) {
+          rowCells.push(null);
+        } else {
+          rowCells.push(String(c.value));
+        }
+      }
+      cells.push(rowCells);
+    }
+
+    const columnWidths = ws.columns?.map((cw, i) => ({
+      column: cw.min !== undefined ? cw.min - 1 : i,
+      width: cw.width ?? 10,
+    }));
+
+    const frozenPanes = ws.freezePanes
+      ? {
+          rows: ws.freezePanes.row,
+          columns: ws.freezePanes.col,
+        }
+      : undefined;
+
+    sheets.push({
+      name,
+      cells,
+      columnWidths,
+      frozenPanes,
+    });
+  }
+
+  return {
+    kind: "sheet",
+    modelVersion: 1,
+    sheets,
+  };
+}

package/work/src/documents/types.ts

@@ -0,0 +1,188 @@
+/**
+ * Core Prism Document Model types.
+ *
+ * All models are plain JSON-serializable structures with zero required class
+ * instantiation. Discriminated union on `kind` ("doc" | "sheet" | "deck") with
+ * stamped `modelVersion`.
+ */
+
+export type DocumentKind = "doc" | "sheet" | "deck";
+
+// --- Document Runs & Inline Elements ---
+
+export interface DocRun {
+  readonly text: string;
+  readonly bold?: boolean;
+  readonly italic?: boolean;
+  readonly underline?: boolean;
+  readonly strikethrough?: boolean;
+  readonly code?: boolean;
+  readonly link?: string;
+}
+
+export interface ListItem {
+  readonly text: string;
+  readonly runs?: readonly DocRun[];
+}
+
+// --- Cell Values (Document Tables & Sheets) ---
+
+export interface DecimalCellValue {
+  readonly type: "decimal";
+  /** Canonical decimal string (e.g. "1234.56", "-0.05", "42"). */
+  readonly value: string;
+}
+
+export interface DateCellValue {
+  readonly type: "date";
+  /** ISO-8601 date string (YYYY-MM-DD). */
+  readonly value: string;
+}
+
+export interface DateTimeCellValue {
+  readonly type: "datetime";
+  /** ISO-8601 datetime string (e.g. "2026-08-31T18:00:00Z"). */
+  readonly value: string;
+}
+
+export interface FormulaCellValue {
+  /** Formula expression starting with "=" (read-only, not evaluated by Prism). */
+  readonly formula: string;
+  /** Optional pre-computed or cached value. */
+  readonly cachedValue?: string | number | boolean | null;
+}
+
+export type CellValue = string | number | boolean | DecimalCellValue | DateCellValue | DateTimeCellValue | FormulaCellValue | null;
+
+// --- Chart Data ---
+
+export type ChartType = "bar" | "line" | "pie" | "scatter";
+
+export interface ChartSeries {
+  readonly name: string;
+  readonly values: readonly number[];
+}
+
+export interface ChartData {
+  readonly categories: readonly string[];
+  readonly series: readonly ChartSeries[];
+}
+
+// --- Document Blocks (DocModel) ---
+
+export interface HeadingBlock {
+  readonly type: "heading";
+  readonly level: 1 | 2 | 3 | 4 | 5 | 6;
+  readonly text: string;
+  readonly id?: string;
+}
+
+export interface ParagraphBlock {
+  readonly type: "paragraph";
+  readonly text?: string;
+  readonly runs?: readonly DocRun[];
+}
+
+export interface ListBlock {
+  readonly type: "list";
+  readonly ordered?: boolean;
+  readonly items: readonly (string | ListItem)[];
+}
+
+export interface TableBlock {
+  readonly type: "table";
+  readonly rows: number;
+  readonly columns: number;
+  readonly headers?: readonly string[];
+  readonly cells: readonly (readonly CellValue[])[];
+}
+
+export interface ImageBlock {
+  readonly type: "image";
+  /** Base64-encoded image data or empty when referencing via `ref`. */
+  readonly data?: string;
+  readonly mimeType?: string;
+  readonly alt?: string;
+  readonly width?: number;
+  readonly height?: number;
+  /** Host-supplied opaque asset reference. */
+  readonly ref?: string;
+}
+
+export interface PageBreakBlock {
+  readonly type: "page-break";
+}
+
+export interface ChartBlock {
+  readonly type: "chart";
+  readonly chartType: ChartType;
+  readonly title?: string;
+  readonly data: ChartData;
+  readonly alt?: string;
+  readonly width?: number;
+  readonly height?: number;
+}
+
+export type DocBlock = HeadingBlock | ParagraphBlock | ListBlock | TableBlock | ImageBlock | PageBreakBlock | ChartBlock;
+
+// --- Sheet Model Elements ---
+
+export interface ColumnWidth {
+  readonly column: number;
+  readonly width: number;
+}
+
+export interface FrozenPanes {
+  readonly rows?: number;
+  readonly columns?: number;
+}
+
+export interface SheetData {
+  readonly name: string;
+  readonly cells: readonly (readonly CellValue[])[];
+  readonly columnWidths?: readonly ColumnWidth[];
+  readonly frozenPanes?: FrozenPanes;
+  readonly numberFormats?: Readonly<Record<string, string>>;
+}
+
+// --- Presentation Slide Elements ---
+
+export type SlideLayout = "title" | "title-and-content" | "section-header" | "two-column" | "blank";
+
+export interface SlideData {
+  readonly layout: SlideLayout;
+  readonly title?: string;
+  readonly subtitle?: string;
+  readonly bullets?: readonly (string | ListItem)[];
+  readonly notes?: string;
+  readonly image?: ImageBlock;
+  readonly chart?: ChartBlock;
+}
+
+// --- Top-Level Document Models ---
+
+export interface DocModel {
+  readonly kind: "doc";
+  readonly modelVersion: number;
+  readonly title?: string;
+  readonly metadata?: Readonly<Record<string, unknown>>;
+  readonly blocks: readonly DocBlock[];
+}
+
+export interface SheetModel {
+  readonly kind: "sheet";
+  readonly modelVersion: number;
+  readonly title?: string;
+  readonly metadata?: Readonly<Record<string, unknown>>;
+  readonly sheets: readonly SheetData[];
+}
+
+export interface DeckModel {
+  readonly kind: "deck";
+  readonly modelVersion: number;
+  readonly title?: string;
+  readonly metadata?: Readonly<Record<string, unknown>>;
+  readonly slides: readonly SlideData[];
+}
+
+export type DocumentModel = DocModel | SheetModel | DeckModel;

package/work/src/index.ts

@@ -0,0 +1,311 @@
+/**
+ * `@arnilo/prism-tools/work` — the first-party work tools as a package.
+ *
+ * The default export registers the `office_*` document tools, `work_exec` inside the host-injected
+ * `work.sandbox` service, and the `m365_*` / `gws_*` connector tools when a ref-only credential
+ * resolves. The bounded document reader is provided as the `work.reader` service, and the vendored
+ * Hermes productivity skills are added from `vendor/`. A missing optional parser, an unresolved
+ * connector credential, or a missing sandbox writes a `warn` status note and registers less.
+ *
+ * The document, spreadsheet, diagram, reader, extraction, connector, sandbox, skill, and tool
+ * libraries stay importable as subpaths (`@arnilo/prism-tools/work/documents`, `/sheets`,
+ * `/connectors`, …) because the family shares type names (`validateByteCap`, `CellValue`) that a
+ * single flat barrel cannot re-export unambiguously. The 0.12 factory names stay exported.
+ *
+ * ```ts
+ * import toolsWork from "@arnilo/prism-tools/work";
+ * import { createAgent } from "@arnilo/prism";
+ *
+ * const agent = await createAgent({
+ *   model,
+ *   packages: [toolsWork({ root: process.cwd(), connectors: { microsoft365: { credential: "keyring:m365", configDir, identity } } })],
+ * });
+ * ```
+ */
+
+import { isAbsolute } from "node:path";
+import { definePackage, type JsonObject, type PackageAPI, type PackageInstance, type Secret, type ToolDefinition } from "@arnilo/prism";
+import manifest from "../../package.json" with { type: "json" };
+import { resolveCommand } from "./command.js";
+import { type ToolsWorkConfig, toolsWorkConfigSchema } from "./config.js";
+import { createGoogleWorkspaceCliAdapter } from "./connectors/google-workspace.js";
+import { type AgentIdentity } from "./connectors/identity.js";
+import { createMicrosoft365CliAdapter } from "./connectors/microsoft365.js";
+import { createWorkTools } from "./connectors/tools.js";
+import type {
+  GoogleWorkspaceAdapter,
+  GoogleWorkspaceOp,
+  Microsoft365Adapter,
+  Microsoft365Op,
+  WorkTokenProvider,
+  WorkToolsOptions,
+} from "./connectors/types.js";
+import {
+  createDocumentReader,
+  createDocxParser,
+  createOoxmlParser,
+  createPdfParser,
+  type DocumentParser,
+  type DocumentReader,
+} from "./document-reader/index.js";
+import { createMistralOcrParser } from "./document-reader/mistral-ocr.js";
+import { closeWorkerPool } from "./runtime/worker-pool.js";
+import { createWorkComposition, type WorkSandbox } from "./sandbox/composition.js";
+import { loadWorkSkills } from "./skills/index.js";
+import { createLocalWorkFilesystem } from "./tools/local-filesystem.js";
+import { createOfficeTools } from "./tools/office.js";
+
+export type {
+  ToolsWorkConfig,
+  ToolsWorkConnectorConfig,
+  ToolsWorkConnectorsConfig,
+  ToolsWorkOfficeConfig,
+  ToolsWorkReaderConfig,
+} from "./config.js";
+export { toolsWorkConfigSchema } from "./config.js";
+export { createWorkTools, WORK_MUTATING_TOOL_NAMES } from "./connectors/tools.js";
+export { createDocumentReader, type DocumentReader } from "./document-reader/index.js";
+// A curated flat surface; the group libraries stay behind their subpaths (see the file doc comment).
+export { createWorkComposition, type WorkComposition, type WorkSandbox } from "./sandbox/composition.js";
+export { loadWorkSkills, type WorkSkillName } from "./skills/index.js";
+export { createLocalWorkFilesystem } from "./tools/local-filesystem.js";
+export { createOfficeTools, type OfficeToolsOptions } from "./tools/office.js";
+
+const READER_FORMATS = ["pdf", "docx", "xlsx", "pptx"] as const;
+
+function identityFrom(json: JsonObject): AgentIdentity {
+  return { ...json, verified: true } as unknown as AgentIdentity;
+}
+
+/**
+ * The token provider for a connector credential. A JSON object value is treated as the env map to
+ * inject; any other value becomes the provider's default access-token variable. The value is never
+ * logged, returned, or placed in argv.
+ */
+function tokenProviderFrom(provider: "microsoft365" | "google-workspace", secret: Secret): WorkTokenProvider {
+  const fallback = provider === "microsoft365" ? "M365_ACCESSTOKEN" : "GOOGLE_ACCESS_TOKEN";
+  return {
+    tokenEnv: () => {
+      try {
+        const parsed: unknown = JSON.parse(secret.value);
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+          const out: Record<string, string> = {};
+          for (const [key, value] of Object.entries(parsed)) if (typeof value === "string") out[key] = value;
+          if (Object.keys(out).length > 0) return out;
+        }
+      } catch {
+        // Not JSON: fall through to the provider's default variable.
+      }
+      return { [fallback]: secret.value };
+    },
+  };
+}
+
+/** Build the reader service. A missing optional peer drops only its formats, with one note. */
+async function buildReader(prism: PackageAPI<ToolsWorkConfig>): Promise<DocumentReader | undefined> {
+  const config = prism.config.reader;
+  if (config === undefined) return undefined;
+  const formats = new Set(config.formats ?? READER_FORMATS);
+  const parsers: DocumentParser[] = [];
+  const dropped: string[] = [];
+
+  if (formats.has("pdf")) {
+    if (config.ocr) {
+      const secret = await prism.credentials.resolve(config.ocr.apiKey);
+      if (secret) {
+        parsers.push(
+          createMistralOcrParser({
+            apiKey: secret.value,
+            ...(config.ocr.baseUrl ? { baseUrl: config.ocr.baseUrl } : {}),
+            ...(config.ocr.model ? { model: config.ocr.model } : {}),
+          }),
+        );
+      } else {
+        dropped.push("pdf (ocr credential unresolved)");
+      }
+    } else {
+      try {
+        parsers.push(await createPdfParser());
+      } catch {
+        dropped.push("pdf (pdf-parse)");
+      }
+    }
+  }
+  if (formats.has("docx")) {
+    try {
+      parsers.push(await createDocxParser());
+    } catch {
+      dropped.push("docx (mammoth)");
+    }
+  }
+  for (const [format, kind, part] of [
+    ["xlsx", "sheet", "xl/workbook.xml"],
+    ["pptx", "deck", "ppt/presentation.xml"],
+  ] as const) {
+    if (!formats.has(format)) continue;
+    try {
+      await import("./documents/parse.js");
+      parsers.push(createOoxmlParser(format, kind, part));
+    } catch {
+      dropped.push(`${format} (install @office-open/docx, @office-open/pptx, @office-open/xlsx, @office-open/xml and ajv)`);
+    }
+  }
+
+  if (dropped.length > 0) {
+    prism.status.note("warn", `work: dropped reader formats: ${dropped.join(", ")}`);
+  }
+  if (parsers.length === 0) return undefined;
+  return await createDocumentReader({
+    parsers,
+    ...(config.maxBytes !== undefined ? { maxBytes: config.maxBytes } : {}),
+    ...(config.maxPages !== undefined ? { maxPages: config.maxPages } : {}),
+    ...(config.maxTextBytes !== undefined ? { maxTextBytes: config.maxTextBytes } : {}),
+  });
+}
+
+/** Build the connector adapters. A provider registers only when its credential resolves. */
+async function buildConnectors(prism: PackageAPI<ToolsWorkConfig>): Promise<WorkToolsOptions | undefined> {
+  const config = prism.config.connectors;
+  if (config === undefined) return undefined;
+
+  let microsoft365: Microsoft365Adapter | undefined;
+  let googleWorkspace: GoogleWorkspaceAdapter | undefined;
+
+  const m365 = config.microsoft365;
+  if (m365) {
+    const secret = await prism.credentials.resolve(m365.credential);
+    if (!secret) {
+      prism.status.note("warn", "work: microsoft365 credential did not resolve; registering no microsoft365 tools");
+    } else if (!m365.configDir || !m365.identity) {
+      prism.status.note("warn", "work: microsoft365 needs configDir and identity; registering no microsoft365 tools");
+    } else {
+      const binary = resolveCommand(m365.binary ?? "m365");
+      if (!binary) {
+        prism.status.note(
+          "warn",
+          `work: microsoft365 binary "${m365.binary ?? "m365"}" not found on PATH; registering no microsoft365 tools`,
+        );
+      } else {
+        microsoft365 = createMicrosoft365CliAdapter({
+          binary,
+          configDir: m365.configDir,
+          identity: identityFrom(m365.identity),
+          ...(m365.allowedOps ? { allowedOps: m365.allowedOps as readonly Microsoft365Op[] } : {}),
+          tokenProvider: tokenProviderFrom("microsoft365", secret),
+        });
+      }
+    }
+  }
+
+  const google = config.google;
+  if (google) {
+    const secret = await prism.credentials.resolve(google.credential);
+    if (!secret) {
+      prism.status.note("warn", "work: google credential did not resolve; registering no google tools");
+    } else if (!google.configDir || !google.identity) {
+      prism.status.note("warn", "work: google needs configDir and identity; registering no google tools");
+    } else {
+      const binary = resolveCommand(google.binary ?? "gws");
+      if (!binary) {
+        prism.status.note("warn", `work: google binary "${google.binary ?? "gws"}" not found on PATH; registering no google tools`);
+      } else {
+        googleWorkspace = createGoogleWorkspaceCliAdapter({
+          binary,
+          configDir: google.configDir,
+          identity: identityFrom(google.identity),
+          ...(google.allowedOps ? { allowedOps: google.allowedOps as readonly GoogleWorkspaceOp[] } : {}),
+          tokenProvider: tokenProviderFrom("google-workspace", secret),
+        });
+      }
+    }
+  }
+
+  if (!microsoft365 && !googleWorkspace) return undefined;
+  return {
+    ...(microsoft365 ? { microsoft365 } : {}),
+    ...(googleWorkspace ? { googleWorkspace } : {}),
+  };
+}
+
+const definition = definePackage<ToolsWorkConfig>({
+  name: "@arnilo/prism-tools/work",
+  version: manifest.version,
+  description:
+    "Office document, spreadsheet, diagram, connector, and bounded reader tools with declared effects, ref-only credentials, and an injected work sandbox.",
+  requires: { api: 1 },
+  capabilities: ["credentials"],
+  config: toolsWorkConfigSchema,
+  setup: async (prism) => {
+    const root = prism.config.root;
+    if (typeof root !== "string" || root.length === 0) {
+      throw new Error("prism-tools-work: config needs root (the absolute workspace root the file tools operate in)");
+    }
+    if (!isAbsolute(root)) {
+      throw new Error("prism-tools-work: root must be an absolute path");
+    }
+
+    const filesystem = createLocalWorkFilesystem(root);
+    const officeConfig = prism.config.office;
+    const officeOptions = {
+      filesystem,
+      ...(officeConfig?.maxBytes !== undefined ? { caps: { maxBytes: officeConfig.maxBytes } } : {}),
+    };
+
+    const reader = await buildReader(prism);
+    if (reader) prism.services.provide("work.reader", reader);
+
+    const connectors = await buildConnectors(prism);
+    let officeEnabled = officeConfig?.enabled !== false;
+    const officePeers = ["@office-open/docx", "@office-open/pptx", "@office-open/xlsx", "@office-open/xml", "ajv", "fast-xml-parser"];
+    const missingPeers = officePeers.filter((peer) => {
+      try {
+        import.meta.resolve(peer);
+        return false;
+      } catch {
+        return true;
+      }
+    });
+    if (missingPeers.length > 0) {
+      prism.status.note(
+        "warn",
+        `work: optional peers missing: ${missingPeers.join(", ")}; install them to enable Office tools and OOXML reading`,
+      );
+      officeEnabled = false;
+    }
+    const workEnabled = prism.config.work?.enabled !== false;
+    const sandbox = prism.services.consume<WorkSandbox>("work.sandbox");
+
+    const tools: ToolDefinition[] = [];
+    if (sandbox && workEnabled) {
+      const composed = createWorkComposition({
+        sandbox,
+        ...(officeEnabled ? { office: officeOptions } : {}),
+        ...(connectors ? { connectors } : {}),
+        ...(reader ? { reader } : {}),
+        filesystem,
+        ...(prism.config.env ? { env: prism.config.env } : {}),
+      });
+      tools.push(...composed.tools.filter((tool) => officeEnabled || !tool.name.startsWith("office_")));
+    } else {
+      if (officeEnabled) tools.push(...createOfficeTools(officeOptions));
+      if (connectors) tools.push(...createWorkTools({ ...connectors, filesystem }));
+      if (workEnabled && !sandbox) {
+        prism.status.note("warn", "work: work_exec needs the host work.sandbox service; registering office and connector tools only");
+      }
+    }
+
+    for (const tool of tools) prism.tools.register(tool);
+
+    for (const skill of loadWorkSkills()) prism.skills.register(skill);
+
+    prism.onDispose(() => closeWorkerPool());
+  },
+});
+
+/** The package definition. Pass config through `packageConfig` or use {@link toolsWork}. */
+export default definition;
+
+/** The package with config baked in, for `packages: [toolsWork({ root })]`. */
+export function toolsWork(config: ToolsWorkConfig): PackageInstance {
+  return definition(config);
+}