@awak-app/simy-cli 0.2.3 → 0.3.3

package/src/local-task-scenario-packs.js

@@ -0,0 +1,681 @@
+import { createHash } from "node:crypto";
+import { lstat, readFile, realpath } from "node:fs/promises";
+import path from "node:path";
+import { inflateSync } from "node:zlib";
+
+import { PDFDocument } from "pdf-lib";
+import { PNG } from "pngjs";
+
+import { validateLocalTaskFile } from "./local-task-file-capabilities.js";
+
+export const LOCAL_TASK_SCENARIO_PACK_VERSION = "local_task_scenario_pack.v1";
+
+const OOXML_WORD =
+  "application/vnd.openxmlformats-officedocument.wordprocessingml.document";
+const OOXML_SHEET =
+  "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet";
+const OOXML_PRESENTATION =
+  "application/vnd.openxmlformats-officedocument.presentationml.presentation";
+const MAX_SCENARIO_PDF_BYTES = 25 * 1024 * 1024;
+const MAX_SCENARIO_PNG_DIMENSION = 16_384;
+const MAX_SCENARIO_PNG_PIXELS = 16_777_216;
+
+const PACKS = [
+  pack("research", {
+    title: "Cited research brief",
+    description:
+      "Inspect external sources and produce a reusable Markdown report with citations.",
+    inputRequirements: [
+      requirement("instruction", "instruction", { required: true }),
+    ],
+    sourcePolicy: {
+      external_sources: "required",
+      citation_policy: "required_for_external_claims",
+    },
+    expectedOutputs: [
+      output("research_report", "Research report", [".md"], ["text/markdown"]),
+    ],
+    acceptanceRules: [
+      rule("research_report_present", "research_report", "artifact_present"),
+      rule("research_report_type", "research_report", "extension_mime_match"),
+      rule("research_report_non_empty", "research_report", "non_empty"),
+      rule("research_report_citations", "research_report", "citations_present"),
+    ],
+  }),
+  pack("document", {
+    title: "Document",
+    description: "Create a reusable Word document from the request and optional source files.",
+    inputRequirements: [
+      requirement("instruction", "instruction", { required: true }),
+      requirement("source_files", "attachment", {
+        required: false,
+        acceptedFileCategories: ["text", "office", "pdf"],
+      }),
+    ],
+    sourcePolicy: {
+      external_sources: "allowed",
+      citation_policy: "cite_provided_sources",
+    },
+    expectedOutputs: [
+      output("document", "Word document", [".docx"], [OOXML_WORD]),
+    ],
+    acceptanceRules: [
+      rule("document_present", "document", "artifact_present"),
+      rule("document_type", "document", "extension_mime_match"),
+      rule("document_non_empty", "document", "non_empty"),
+    ],
+  }),
+  pack("spreadsheet", {
+    title: "Spreadsheet",
+    description: "Transform a supplied table or spreadsheet into a structured Excel workbook.",
+    inputRequirements: [
+      requirement("instruction", "instruction", { required: true }),
+      requirement("source_table", "attachment", {
+        required: true,
+        acceptedFileCategories: ["spreadsheet", "text"],
+        minCount: 1,
+        recoveryAction: "choose_supported_file",
+      }),
+    ],
+    sourcePolicy: {
+      external_sources: "forbidden",
+      citation_policy: "not_required",
+    },
+    expectedOutputs: [
+      output("workbook", "Excel workbook", [".xlsx"], [OOXML_SHEET]),
+    ],
+    acceptanceRules: [
+      rule("workbook_present", "workbook", "artifact_present"),
+      rule("workbook_type", "workbook", "extension_mime_match"),
+      rule("workbook_non_empty", "workbook", "non_empty"),
+      rule("workbook_structure", "workbook", "structured_workbook"),
+    ],
+  }),
+  pack("presentation_pdf", {
+    title: "Presentation and PDF",
+    description: "Create an editable presentation and its reviewable PDF export.",
+    inputRequirements: [
+      requirement("instruction", "instruction", { required: true }),
+      requirement("source_files", "attachment", {
+        required: false,
+        acceptedFileCategories: ["text", "office", "pdf", "image"],
+      }),
+    ],
+    sourcePolicy: {
+      external_sources: "allowed",
+      citation_policy: "cite_provided_sources",
+    },
+    expectedOutputs: [
+      output("presentation", "Presentation", [".pptx"], [OOXML_PRESENTATION]),
+      output("presentation_pdf", "Presentation PDF", [".pdf"], ["application/pdf"]),
+    ],
+    acceptanceRules: [
+      rule("presentation_present", "presentation", "artifact_present"),
+      rule("presentation_type", "presentation", "extension_mime_match"),
+      rule("presentation_non_empty", "presentation", "non_empty"),
+      rule("presentation_pdf_present", "presentation_pdf", "artifact_present"),
+      rule("presentation_pdf_type", "presentation_pdf", "extension_mime_match"),
+      rule("presentation_pdf_non_empty", "presentation_pdf", "non_empty"),
+      rule("presentation_pdf_pages", "presentation_pdf", "page_count", { min: 1 }),
+    ],
+  }),
+  pack("image", {
+    title: "Image asset",
+    description: "Create a reusable PNG image asset.",
+    inputRequirements: [
+      requirement("instruction", "instruction", { required: true }),
+      requirement("reference_image", "attachment", {
+        required: false,
+        acceptedFileCategories: ["image"],
+      }),
+    ],
+    sourcePolicy: {
+      external_sources: "forbidden",
+      citation_policy: "not_required",
+    },
+    expectedOutputs: [
+      output("image", "PNG image", [".png"], ["image/png"]),
+    ],
+    acceptanceRules: [
+      rule("image_present", "image", "artifact_present"),
+      rule("image_type", "image", "extension_mime_match"),
+      rule("image_non_empty", "image", "non_empty"),
+      rule("image_dimensions", "image", "image_dimensions", {
+        min_width: 256,
+        min_height: 256,
+      }),
+    ],
+  }),
+];
+
+const REGISTRY_WITHOUT_HASH = {
+  schema_version: LOCAL_TASK_SCENARIO_PACK_VERSION,
+  max_selected_packs: 1,
+  free_text_compatible: true,
+  packs: PACKS,
+};
+
+export const LOCAL_TASK_SCENARIO_PACK_REGISTRY = deepFreeze({
+  ...REGISTRY_WITHOUT_HASH,
+  contract_hash: createHash("sha256")
+    .update(JSON.stringify(REGISTRY_WITHOUT_HASH))
+    .digest("hex"),
+});
+
+const PACKS_BY_ID = new Map(PACKS.map((value) => [value.id, value]));
+const ALLOWED_SELECTIONS = new Set(["explicit", "inferred"]);
+const PACK_REFERENCE_FIELDS = new Set([
+  "schema_version",
+  "id",
+  "selection",
+  "contract_hash",
+]);
+
+export class LocalTaskScenarioPackError extends Error {
+  constructor(message, {
+    code = "local_task_scenario_pack_invalid",
+    recovery = null,
+    outputId = null,
+    ruleId = null,
+  } = {}) {
+    super(message);
+    this.name = "LocalTaskScenarioPackError";
+    this.code = code;
+    this.recovery = recovery;
+    this.output_id = outputId;
+    this.rule_id = ruleId;
+  }
+}
+
+export function localTaskScenarioPackMetadata() {
+  return structuredClone(LOCAL_TASK_SCENARIO_PACK_REGISTRY);
+}
+
+export function normalizeLocalTaskScenarioPack(value) {
+  if (value === null || value === undefined) return null;
+  if (!isRecord(value) || Object.keys(value).some((key) => !PACK_REFERENCE_FIELDS.has(key))) {
+    throw scenarioError("SIMY Web returned an invalid Local Task scenario pack.");
+  }
+  const id = String(value.id || "");
+  if (
+    value.schema_version !== LOCAL_TASK_SCENARIO_PACK_VERSION ||
+    !PACKS_BY_ID.has(id) ||
+    !ALLOWED_SELECTIONS.has(value.selection) ||
+    value.contract_hash !== LOCAL_TASK_SCENARIO_PACK_REGISTRY.contract_hash
+  ) {
+    throw scenarioError(
+      "Update SIMY CLI before running this Local Task scenario.",
+      "unsupported_local_task_scenario_pack",
+      "update_cli",
+    );
+  }
+  return {
+    schema_version: LOCAL_TASK_SCENARIO_PACK_VERSION,
+    id,
+    selection: value.selection,
+    contract_hash: LOCAL_TASK_SCENARIO_PACK_REGISTRY.contract_hash,
+  };
+}
+
+export function localTaskScenarioPackContract(value) {
+  const reference =
+    typeof value === "string"
+      ? { id: value }
+      : value;
+  const contract = PACKS_BY_ID.get(reference?.id);
+  if (!contract) {
+    throw scenarioError("The Local Task scenario is not supported.");
+  }
+  return structuredClone(contract);
+}
+
+export function localTaskScenarioExpectedOutputs(value) {
+  if (!value) return [];
+  return localTaskScenarioPackContract(value).expected_outputs.map((item) => ({
+    kind: item.id,
+    format: item.extensions.join(" or "),
+  }));
+}
+
+export function validateLocalTaskScenarioInputs(value, {
+  instruction,
+  attachments = [],
+} = {}) {
+  if (!value) return { categories: [] };
+  const contract = localTaskScenarioPackContract(value);
+  const normalizedInstruction = String(instruction || "").trim();
+  const categories = attachments.map((attachment) =>
+    validateLocalTaskFile(attachment, { direction: "input" }).category);
+
+  for (const requirementValue of contract.input_requirements) {
+    if (requirementValue.kind === "instruction" && requirementValue.required) {
+      if (!normalizedInstruction) {
+        throw scenarioError(
+          "Describe what you want SIMY to create.",
+          "local_task_scenario_instruction_required",
+          "revise_request",
+        );
+      }
+      continue;
+    }
+    if (requirementValue.kind !== "attachment") continue;
+    const count = categories.filter((category) =>
+      requirementValue.accepted_file_categories.includes(category)).length;
+    if (requirementValue.required && count < requirementValue.min_count) {
+      throw scenarioError(
+        "Attach a supported source file before running this scenario.",
+        "local_task_scenario_attachment_required",
+        requirementValue.recovery_action,
+      );
+    }
+    if (attachments.length > 0 && count !== attachments.length) {
+      throw scenarioError(
+        "Remove files that are not supported by this scenario, then try again.",
+        "local_task_scenario_attachment_unsupported",
+        requirementValue.recovery_action || "choose_supported_file",
+      );
+    }
+  }
+  return { categories };
+}
+
+export function localTaskScenarioInstruction(value) {
+  if (!value) return [];
+  const contract = localTaskScenarioPackContract(value);
+  const outputs = contract.expected_outputs.map((item) =>
+    `- ${item.label}: ${item.extensions.join(" or ")} (${item.mime_types.join(" or ")})`);
+  const rules = contract.acceptance_rules.map((item) =>
+    `- ${acceptanceInstruction(item)}`);
+  const sourceInstruction = {
+    required:
+      "Inspect external sources yourself. Cite only sources you actually inspected, and use Markdown links for factual external claims.",
+    allowed:
+      "External sources are optional. If you use or rely on supplied sources, cite them in the deliverable.",
+    forbidden:
+      "Do not use external sources for this scenario; work only from the request and verified attachments.",
+  }[contract.source_policy.external_sources];
+  return [
+    `Scenario pack: ${contract.title} (${contract.id}).`,
+    contract.description,
+    sourceInstruction,
+    "Required scenario outputs:",
+    ...outputs,
+    "Acceptance rules:",
+    ...rules,
+  ];
+}
+
+export async function validateLocalTaskScenarioArtifacts(value, artifacts, {
+  outputsRoot,
+} = {}) {
+  if (!value) return { matched_outputs: {}, checks: [] };
+  const contract = localTaskScenarioPackContract(value);
+  const remaining = [...(Array.isArray(artifacts) ? artifacts : [])];
+  const matched = {};
+
+  for (const expected of contract.expected_outputs) {
+    const index = remaining.findIndex((artifact) => {
+      const extension = path.extname(String(artifact?.name || "")).toLowerCase();
+      return expected.extensions.includes(extension) &&
+        expected.mime_types.includes(artifact?.mime_type);
+    });
+    if (index < 0) {
+      throw scenarioError(
+        `The ${contract.title} scenario did not produce the required ${expected.label}.`,
+        "local_task_scenario_artifact_missing",
+        null,
+        expected.id,
+      );
+    }
+    matched[expected.id] = remaining.splice(index, 1)[0];
+  }
+
+  const checks = [];
+  for (const acceptance of contract.acceptance_rules) {
+    const artifact = matched[acceptance.output_id];
+    await validateAcceptanceRule(acceptance, artifact, outputsRoot);
+    checks.push({ id: acceptance.id, passed: true });
+  }
+  return {
+    matched_outputs: Object.fromEntries(
+      Object.entries(matched).map(([id, artifact]) => [id, artifact.id])),
+    checks,
+  };
+}
+
+function pack(id, {
+  title,
+  description,
+  inputRequirements,
+  sourcePolicy,
+  expectedOutputs,
+  acceptanceRules,
+}) {
+  return {
+    id,
+    title,
+    description,
+    input_requirements: inputRequirements,
+    source_policy: sourcePolicy,
+    expected_outputs: expectedOutputs,
+    acceptance_rules: acceptanceRules,
+  };
+}
+
+function requirement(id, kind, {
+  required,
+  acceptedFileCategories = [],
+  minCount = required ? 1 : 0,
+  recoveryAction = null,
+}) {
+  return {
+    id,
+    kind,
+    required,
+    accepted_file_categories: acceptedFileCategories,
+    min_count: minCount,
+    recovery_action: recoveryAction,
+  };
+}
+
+function output(id, label, extensions, mimeTypes) {
+  return {
+    id,
+    label,
+    required: true,
+    extensions,
+    mime_types: mimeTypes,
+  };
+}
+
+function rule(id, outputId, kind, config = {}) {
+  return { id, output_id: outputId, kind, config };
+}
+
+async function validateAcceptanceRule(acceptance, artifact, outputsRoot) {
+  if (!artifact) {
+    throw acceptanceError(acceptance, "The required scenario output is missing.");
+  }
+  if (acceptance.kind === "artifact_present" || acceptance.kind === "extension_mime_match") {
+    return;
+  }
+  if (acceptance.kind === "non_empty") {
+    if (!Number.isSafeInteger(artifact.size_bytes) || artifact.size_bytes < 1) {
+      throw acceptanceError(acceptance, `${artifact.name} is empty.`);
+    }
+    return;
+  }
+
+  const bytes = await readArtifactBytes(artifact, outputsRoot);
+  if (acceptance.kind === "citations_present") {
+    const text = bytes.toString("utf8");
+    const markdownLinks = text.match(/\[[^\]\n]+\]\(https?:\/\/[^)\s]+\)/gi) || [];
+    if (markdownLinks.length === 0) {
+      throw acceptanceError(
+        acceptance,
+        "The research report must cite at least one inspected source with a Markdown link.",
+      );
+    }
+    return;
+  }
+  if (acceptance.kind === "structured_workbook") {
+    // The shared file capability gate has already verified an OOXML workbook root,
+    // content type, central directory limits, MIME, extension, size, and digest.
+    if (artifact.mime_type !== OOXML_SHEET) {
+      throw acceptanceError(acceptance, "The workbook is not a verified Excel file.");
+    }
+    return;
+  }
+  if (acceptance.kind === "page_count") {
+    const pages = await validatedPdfPageCount(bytes, acceptance);
+    if (pages < Number(acceptance.config.min || 1)) {
+      throw acceptanceError(acceptance, "The PDF does not contain a reviewable page.");
+    }
+    return;
+  }
+  if (acceptance.kind === "image_dimensions") {
+    const { width, height } = validatedPngDimensions(bytes, acceptance);
+    if (
+      width < Number(acceptance.config.min_width || 1) ||
+      height < Number(acceptance.config.min_height || 1)
+    ) {
+      throw acceptanceError(
+        acceptance,
+        `The image must be at least ${acceptance.config.min_width}×${acceptance.config.min_height}px.`,
+      );
+    }
+    return;
+  }
+  throw acceptanceError(acceptance, "The scenario contains an unsupported acceptance rule.");
+}
+
+async function validatedPdfPageCount(bytes, acceptance) {
+  if (bytes.length < 8 || bytes.length > MAX_SCENARIO_PDF_BYTES) {
+    throw acceptanceError(acceptance, "The PDF is empty, incomplete, or too large to inspect.");
+  }
+  try {
+    const document = await PDFDocument.load(bytes, {
+      ignoreEncryption: false,
+      updateMetadata: false,
+      throwOnInvalidObject: true,
+    });
+    const pages = document.getPageCount();
+    if (!Number.isSafeInteger(pages) || pages < 0) {
+      throw new Error("invalid page count");
+    }
+    return pages;
+  } catch {
+    throw acceptanceError(
+      acceptance,
+      "The PDF could not be parsed into a usable catalog and page tree.",
+    );
+  }
+}
+
+function validatedPngDimensions(bytes, acceptance) {
+  if (bytes.length < 57 || bytes.subarray(0, 8).toString("hex") !== "89504e470d0a1a0a") {
+    throw acceptanceError(acceptance, "The image is not a complete PNG.");
+  }
+  const headerLength = bytes.readUInt32BE(8);
+  const headerType = bytes.subarray(12, 16).toString("ascii");
+  const width = bytes.readUInt32BE(16);
+  const height = bytes.readUInt32BE(20);
+  const bitDepth = bytes[24];
+  const colorType = bytes[25];
+  const compression = bytes[26];
+  const filterMethod = bytes[27];
+  const interlace = bytes[28];
+  const pixels = width * height;
+  const supportedDepths = {
+    0: [1, 2, 4, 8, 16],
+    2: [8, 16],
+    3: [1, 2, 4, 8],
+    4: [8, 16],
+    6: [8, 16],
+  };
+  if (
+    headerLength !== 13 ||
+    headerType !== "IHDR" ||
+    width < 1 ||
+    height < 1 ||
+    width > MAX_SCENARIO_PNG_DIMENSION ||
+    height > MAX_SCENARIO_PNG_DIMENSION ||
+    !Number.isSafeInteger(pixels) ||
+    pixels > MAX_SCENARIO_PNG_PIXELS ||
+    !supportedDepths[colorType]?.includes(bitDepth) ||
+    compression !== 0 ||
+    filterMethod !== 0 ||
+    ![0, 1].includes(interlace)
+  ) {
+    throw acceptanceError(acceptance, "The PNG header or decoded canvas size is invalid.");
+  }
+  try {
+    const idat = collectPngImageData(bytes);
+    const scanlines = pngScanlineLengths(width, height, bitDepth, colorType, interlace);
+    const expectedLength = scanlines.reduce(
+      (total, { rows, rowBytes }) => total + rows * (rowBytes + 1),
+      0,
+    );
+    const inflated = inflateSync(Buffer.concat(idat), {
+      maxOutputLength: expectedLength + 1,
+    });
+    if (inflated.length !== expectedLength) {
+      throw new Error("decoded scanline length mismatch");
+    }
+    let scanlineOffset = 0;
+    for (const { rows, rowBytes } of scanlines) {
+      for (let row = 0; row < rows; row += 1) {
+        if (inflated[scanlineOffset] > 4) throw new Error("invalid PNG filter");
+        scanlineOffset += rowBytes + 1;
+      }
+    }
+    const decoded = PNG.sync.read(bytes, { checkCRC: true });
+    if (
+      decoded.width !== width ||
+      decoded.height !== height ||
+      !Buffer.isBuffer(decoded.data) ||
+      decoded.data.length !== pixels * 4
+    ) {
+      throw new Error("decoded canvas mismatch");
+    }
+  } catch {
+    throw acceptanceError(
+      acceptance,
+      "The PNG image data could not be decoded into a complete pixel canvas.",
+    );
+  }
+  return { width, height };
+}
+
+function collectPngImageData(bytes) {
+  const chunks = [];
+  let offset = 8;
+  let ended = false;
+  while (offset < bytes.length) {
+    if (offset + 12 > bytes.length) throw new Error("truncated PNG chunk");
+    const length = bytes.readUInt32BE(offset);
+    const dataStart = offset + 8;
+    const dataEnd = dataStart + length;
+    const chunkEnd = dataEnd + 4;
+    if (chunkEnd > bytes.length) throw new Error("truncated PNG chunk data");
+    const type = bytes.subarray(offset + 4, dataStart).toString("ascii");
+    if (type === "IDAT") chunks.push(bytes.subarray(dataStart, dataEnd));
+    if (type === "IEND") {
+      if (length !== 0 || chunkEnd !== bytes.length) throw new Error("invalid PNG end");
+      ended = true;
+    }
+    offset = chunkEnd;
+  }
+  if (!ended || chunks.length === 0) throw new Error("missing PNG image data");
+  return chunks;
+}
+
+function pngScanlineLengths(width, height, bitDepth, colorType, interlace) {
+  const channels = { 0: 1, 2: 3, 3: 1, 4: 2, 6: 4 }[colorType];
+  const rowBytes = (passWidth) => Math.ceil((passWidth * channels * bitDepth) / 8);
+  if (interlace === 0) return [{ rows: height, rowBytes: rowBytes(width) }];
+  const passes = [
+    [0, 0, 8, 8],
+    [4, 0, 8, 8],
+    [0, 4, 4, 8],
+    [2, 0, 4, 4],
+    [0, 2, 2, 4],
+    [1, 0, 2, 2],
+    [0, 1, 1, 2],
+  ];
+  return passes.flatMap(([xStart, yStart, xStep, yStep]) => {
+    const passWidth = width > xStart ? Math.ceil((width - xStart) / xStep) : 0;
+    const rows = height > yStart ? Math.ceil((height - yStart) / yStep) : 0;
+    return passWidth > 0 && rows > 0 ? [{ rows, rowBytes: rowBytes(passWidth) }] : [];
+  });
+}
+
+async function readArtifactBytes(artifact, outputsRoot) {
+  const root = path.resolve(String(outputsRoot || ""));
+  const target = path.resolve(root, String(artifact.relative_path || ""));
+  if (!root || !target.startsWith(`${root}${path.sep}`)) {
+    throw scenarioError(
+      "The scenario output is outside the managed output directory.",
+      "local_task_scenario_artifact_unsafe",
+    );
+  }
+  const [resolvedRoot, resolvedTarget, details] = await Promise.all([
+    realpath(root),
+    realpath(target),
+    lstat(target),
+  ]);
+  if (
+    !details.isFile() ||
+    details.isSymbolicLink() ||
+    !resolvedTarget.startsWith(`${resolvedRoot}${path.sep}`)
+  ) {
+    throw scenarioError(
+      "The scenario output failed SIMY's managed-file safety check.",
+      "local_task_scenario_artifact_unsafe",
+    );
+  }
+  const bytes = await readFile(resolvedTarget);
+  const digest = createHash("sha256").update(bytes).digest("hex");
+  if (
+    bytes.length !== artifact.size_bytes ||
+    digest !== String(artifact.sha256 || "").toLowerCase()
+  ) {
+    throw scenarioError(
+      "The scenario output changed after verification.",
+      "local_task_scenario_artifact_changed",
+    );
+  }
+  return bytes;
+}
+
+function acceptanceInstruction(value) {
+  if (value.kind === "citations_present") {
+    return "The research report must contain Markdown links to sources actually inspected.";
+  }
+  if (value.kind === "structured_workbook") {
+    return "The workbook must be a valid, structured .xlsx file.";
+  }
+  if (value.kind === "page_count") {
+    return `The PDF must contain at least ${value.config.min} page.`;
+  }
+  if (value.kind === "image_dimensions") {
+    return `The PNG must be at least ${value.config.min_width}×${value.config.min_height}px.`;
+  }
+  return `${value.output_id} must pass ${value.kind.replaceAll("_", " ")}.`;
+}
+
+function acceptanceError(value, message) {
+  return scenarioError(
+    message,
+    "local_task_scenario_acceptance_failed",
+    null,
+    value.output_id,
+    value.id,
+  );
+}
+
+function scenarioError(
+  message,
+  code = "local_task_scenario_pack_invalid",
+  recovery = null,
+  outputId = null,
+  ruleId = null,
+) {
+  return new LocalTaskScenarioPackError(message, {
+    code,
+    recovery,
+    outputId,
+    ruleId,
+  });
+}
+
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function deepFreeze(value) {
+  if (!value || typeof value !== "object" || Object.isFrozen(value)) return value;
+  Object.freeze(value);
+  for (const child of Object.values(value)) deepFreeze(child);
+  return value;
+}