tinker-agent 1.0.65 → 1.2.0

package/src/image/image-asset-store.ts

@@ -0,0 +1,319 @@
+import { constants } from "node:fs";
+import {
+  chmod,
+  link,
+  lstat,
+  mkdir,
+  open,
+  readdir,
+  realpath,
+  rm,
+  stat,
+} from "node:fs/promises";
+import path from "node:path";
+import { createUuidV7 } from "../ids/uuid-v7";
+import { IMAGE_INPUT_POLICY } from "./image-input-policy";
+import { probeImageBytes } from "./image-probe";
+import {
+  normalizeOriginalImageName,
+  parseImageAssetId,
+  validateImageAssetRef,
+  type ImageAssetId,
+  type ImageAssetRef,
+} from "./image-types";
+
+const STAGING_MAX_AGE_MS = 24 * 60 * 60 * 1_000;
+const STAGING_PATTERN =
+  /^\.staging-image-[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+
+export type ImportedImageAsset = {
+  readonly asset: ImageAssetRef;
+  readonly originalName: string;
+};
+
+export class ImageAssetStore {
+  readonly workspaceRoot: string;
+  readonly root: string;
+
+  private constructor(
+    workspaceRoot: string,
+    root: string,
+    private readonly onWarning?: (message: string) => void,
+  ) {
+    this.workspaceRoot = workspaceRoot;
+    this.root = root;
+  }
+
+  static async open(input: {
+    workspaceRoot: string;
+    onWarning?: (message: string) => void;
+  }): Promise<ImageAssetStore> {
+    const workspaceRoot = await realpath(input.workspaceRoot);
+    const workspaceStat = await stat(workspaceRoot);
+    if (!workspaceStat.isDirectory()) {
+      throw new Error(`Workspace root is not a directory: ${workspaceRoot}.`);
+    }
+    const root = await ensureAssetRoot(workspaceRoot);
+    const store = new ImageAssetStore(workspaceRoot, root, input.onWarning);
+    await store.cleanupStagingFiles();
+    return store;
+  }
+
+  pathFor(assetId: ImageAssetId): string {
+    parseImageAssetId(assetId);
+    return path.join(this.root, assetId);
+  }
+
+  async importWorkspaceFile(
+    sourcePath: string,
+    options: {
+      signal?: AbortSignal;
+      accept?: (asset: ImageAssetRef) => void;
+    } = {},
+  ): Promise<ImportedImageAsset> {
+    throwIfAborted(options.signal);
+    const candidate = path.isAbsolute(sourcePath)
+      ? path.normalize(sourcePath)
+      : path.resolve(this.workspaceRoot, sourcePath);
+    assertContained(this.workspaceRoot, candidate, "Image source path");
+    const pathStat = await lstat(candidate);
+    if (pathStat.isSymbolicLink() || !pathStat.isFile()) {
+      throw new Error("Image source must be a regular non-symlink file.");
+    }
+    const canonicalSource = await realpath(candidate);
+    assertContained(this.workspaceRoot, canonicalSource, "Image source realpath");
+
+    const handle = await open(canonicalSource, constants.O_RDONLY | noFollowFlag());
+    let bytes: Buffer;
+    try {
+      const handleStat = await handle.stat();
+      if (
+        !handleStat.isFile() ||
+        handleStat.dev !== pathStat.dev ||
+        handleStat.ino !== pathStat.ino
+      ) {
+        throw new Error("Image source changed between path validation and open.");
+      }
+      if (handleStat.size < 1) {
+        throw new Error("Image source is empty.");
+      }
+      if (handleStat.size > IMAGE_INPUT_POLICY.maxBytesPerImage) {
+        throw new Error(
+          `Image is ${handleStat.size} bytes; maximum is ${IMAGE_INPUT_POLICY.maxBytesPerImage}.`,
+        );
+      }
+      bytes = await handle.readFile();
+    } finally {
+      await handle.close();
+    }
+    throwIfAborted(options.signal);
+
+    const asset = await probeImageBytes(bytes, {
+      fullDecode: true,
+      sourceName: path.basename(canonicalSource),
+    });
+    options.accept?.(asset);
+    throwIfAborted(options.signal);
+    await this.publish(asset, bytes, options.signal);
+    return Object.freeze({
+      asset,
+      originalName: normalizeOriginalImageName(path.basename(canonicalSource)),
+    });
+  }
+
+  async readVerified(
+    expected: ImageAssetRef,
+    options: { signal?: AbortSignal } = {},
+  ): Promise<Buffer> {
+    validateImageAssetRef(expected);
+    throwIfAborted(options.signal);
+    const assetPath = this.pathFor(expected.assetId);
+    const fileStat = await lstat(assetPath);
+    if (fileStat.isSymbolicLink() || !fileStat.isFile()) {
+      throw new Error(`Image asset ${shortAssetId(expected.assetId)} is not regular.`);
+    }
+    if (fileStat.size !== expected.byteLength) {
+      throw new Error(`Image asset ${shortAssetId(expected.assetId)} length changed.`);
+    }
+    const handle = await open(assetPath, constants.O_RDONLY | noFollowFlag());
+    let bytes: Buffer;
+    try {
+      const openedStat = await handle.stat();
+      if (
+        !openedStat.isFile() ||
+        openedStat.dev !== fileStat.dev ||
+        openedStat.ino !== fileStat.ino
+      ) {
+        throw new Error(`Image asset ${shortAssetId(expected.assetId)} changed.`);
+      }
+      bytes = await handle.readFile();
+    } finally {
+      await handle.close();
+    }
+    throwIfAborted(options.signal);
+    const actual = await probeImageBytes(bytes, { fullDecode: false });
+    if (
+      actual.assetId !== expected.assetId ||
+      actual.mimeType !== expected.mimeType ||
+      actual.byteLength !== expected.byteLength ||
+      actual.width !== expected.width ||
+      actual.height !== expected.height
+    ) {
+      throw new Error(
+        `Image asset ${shortAssetId(expected.assetId)} failed integrity validation.`,
+      );
+    }
+    return bytes;
+  }
+
+  async verify(expected: ImageAssetRef): Promise<void> {
+    await this.readVerified(expected);
+  }
+
+  private async publish(
+    asset: ImageAssetRef,
+    bytes: Buffer,
+    signal?: AbortSignal,
+  ): Promise<void> {
+    const target = this.pathFor(asset.assetId);
+    const staging = path.join(this.root, `.staging-image-${createUuidV7()}`);
+    let stagingExists = false;
+    try {
+      const stagingHandle = await open(staging, "wx", 0o600);
+      stagingExists = true;
+      try {
+        await stagingHandle.writeFile(bytes);
+        await stagingHandle.sync();
+      } finally {
+        await stagingHandle.close();
+      }
+      throwIfAborted(signal);
+      try {
+        await link(staging, target);
+      } catch (error) {
+        if (!hasCode(error, "EEXIST")) {
+          throw error;
+        }
+        await this.verify(asset);
+        return;
+      }
+      await chmod(target, 0o600);
+      await syncDirectory(this.root);
+    } finally {
+      if (stagingExists) {
+        await rm(staging).catch((error) => {
+          if (!hasCode(error, "ENOENT")) {
+            this.onWarning?.(
+              `Failed to remove image staging file: ${errorMessage(error)}`,
+            );
+          }
+        });
+      }
+    }
+  }
+
+  private async cleanupStagingFiles(): Promise<void> {
+    const names = await readdir(this.root);
+    const now = Date.now();
+    for (const name of names) {
+      if (!STAGING_PATTERN.test(name)) {
+        continue;
+      }
+      const stagingPath = path.join(this.root, name);
+      try {
+        const entry = await lstat(stagingPath);
+        const age = now - entry.mtimeMs;
+        if (!Number.isFinite(age) || age < 0) {
+          this.onWarning?.(`Image staging file has an invalid mtime: ${name}`);
+          continue;
+        }
+        if (!entry.isFile() || entry.isSymbolicLink() || age <= STAGING_MAX_AGE_MS) {
+          continue;
+        }
+        await rm(stagingPath);
+      } catch (error) {
+        if (!hasCode(error, "ENOENT")) {
+          this.onWarning?.(
+            `Image staging cleanup skipped ${name}: ${errorMessage(error)}`,
+          );
+        }
+      }
+    }
+  }
+}
+
+async function ensureAssetRoot(workspaceRoot: string): Promise<string> {
+  let current = workspaceRoot;
+  for (const name of [".tinker", "assets", "images"]) {
+    current = path.join(current, name);
+    try {
+      const entry = await lstat(current);
+      if (entry.isSymbolicLink() || !entry.isDirectory()) {
+        throw new Error(
+          `Image asset directory is not a regular directory: ${current}.`,
+        );
+      }
+    } catch (error) {
+      if (!hasCode(error, "ENOENT")) {
+        throw error;
+      }
+      await mkdir(current, { mode: 0o700 });
+    }
+    if (name !== ".tinker") {
+      await chmod(current, 0o700);
+    }
+  }
+  const canonical = await realpath(current);
+  assertContained(workspaceRoot, canonical, "Image asset root");
+  if (canonical !== current) {
+    throw new Error("Image asset root is not canonical.");
+  }
+  return canonical;
+}
+
+function assertContained(root: string, candidate: string, name: string): void {
+  const relative = path.relative(root, candidate);
+  if (
+    relative === "" ||
+    (!relative.startsWith(`..${path.sep}`) &&
+      relative !== ".." &&
+      !path.isAbsolute(relative))
+  ) {
+    return;
+  }
+  throw new Error(`${name} is outside the workspace.`);
+}
+
+async function syncDirectory(directoryPath: string): Promise<void> {
+  const handle = await open(directoryPath, constants.O_RDONLY);
+  try {
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+}
+
+function noFollowFlag(): number {
+  return typeof constants.O_NOFOLLOW === "number" ? constants.O_NOFOLLOW : 0;
+}
+
+function throwIfAborted(signal: AbortSignal | undefined): void {
+  signal?.throwIfAborted();
+}
+
+function hasCode(error: unknown, code: string): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "code" in error &&
+    error.code === code
+  );
+}
+
+function shortAssetId(assetId: ImageAssetId): string {
+  return `${assetId.slice(0, 12)}…`;
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/image/image-input-policy.ts

@@ -0,0 +1,14 @@
+export const IMAGE_INPUT_POLICY = Object.freeze({
+  transport: "openai-chat-image-url-data-v1",
+  allowedMimeTypes: Object.freeze(["image/png", "image/jpeg", "image/webp"] as const),
+  maxBytesPerImage: 20 * 1024 * 1024,
+  maxImagesPerMessage: 8,
+  maxImagesPerRequest: 8,
+  maxLongEdge: 4096,
+  maxPixels: 8_847_360,
+  maxRequestBodyBytes: 90_000_000,
+  planningTokensPerImage: 2048,
+  retryPolicy: "none",
+} as const);
+
+export const IMAGE_INPUT_POLICY_VERSION = "image-input-policy-v1" as const;

package/src/image/image-probe.ts

@@ -0,0 +1,233 @@
+import sharp from "sharp";
+import { IMAGE_INPUT_POLICY } from "./image-input-policy";
+import {
+  imageAssetIdForBytes,
+  type ImageAssetRef,
+  type ImageMimeType,
+} from "./image-types";
+
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+
+export type ImageProbeOptions = {
+  fullDecode?: boolean;
+  sourceName?: string;
+};
+
+export class ImageNotRecognizedError extends Error {
+  readonly code = "IMAGE_NOT_RECOGNIZED" as const;
+}
+
+export class UnsupportedImageFormatError extends Error {
+  readonly code = "IMAGE_FORMAT_UNSUPPORTED" as const;
+}
+
+export async function probeImageBytes(
+  bytes: Buffer,
+  options: ImageProbeOptions = {},
+): Promise<ImageAssetRef> {
+  if (bytes.length < 1) {
+    throw new Error("Image file is empty.");
+  }
+  if (bytes.length > IMAGE_INPUT_POLICY.maxBytesPerImage) {
+    throw new Error(
+      `Image is ${bytes.length} bytes; maximum is ${IMAGE_INPUT_POLICY.maxBytesPerImage}.`,
+    );
+  }
+
+  const container = inspectContainer(bytes, options.sourceName);
+  let metadata;
+  try {
+    const instance = sharp(bytes, {
+      failOn: "warning",
+      limitInputPixels: IMAGE_INPUT_POLICY.maxPixels,
+      unlimited: false,
+      sequentialRead: true,
+    });
+    metadata = await instance.metadata();
+    if (options.fullDecode !== false) {
+      await instance.raw().toBuffer();
+    }
+  } catch (error) {
+    throw new Error(`Image decode failed: ${errorMessage(error)}.`, {
+      cause: error,
+    });
+  }
+
+  const mimeType = mimeTypeForSharpFormat(metadata.format);
+  if (mimeType !== container.mimeType) {
+    throw new Error(
+      `Image container and decoder disagree on format (${container.mimeType} vs ${mimeType}).`,
+    );
+  }
+  const width = requireDimension(metadata.width, "width");
+  const height = requireDimension(metadata.height, "height");
+  const decoderAnimated =
+    (metadata.pages ?? 1) > 1 || metadata.pageHeight !== undefined;
+  if (container.animated || decoderAnimated) {
+    throw new Error("Animated images are not supported.");
+  }
+  if (
+    width > IMAGE_INPUT_POLICY.maxLongEdge ||
+    height > IMAGE_INPUT_POLICY.maxLongEdge
+  ) {
+    throw new Error(
+      `Image dimensions ${width}x${height} exceed ${IMAGE_INPUT_POLICY.maxLongEdge}px.`,
+    );
+  }
+  const pixels = width * height;
+  if (!Number.isSafeInteger(pixels) || pixels > IMAGE_INPUT_POLICY.maxPixels) {
+    throw new Error(
+      `Image pixel count ${pixels} exceeds ${IMAGE_INPUT_POLICY.maxPixels}.`,
+    );
+  }
+
+  return Object.freeze({
+    assetId: imageAssetIdForBytes(bytes),
+    mimeType,
+    byteLength: bytes.length,
+    width,
+    height,
+  });
+}
+
+function inspectContainer(
+  bytes: Buffer,
+  sourceName?: string,
+): {
+  mimeType: ImageMimeType;
+  animated: boolean;
+} {
+  if (bytes.subarray(0, PNG_SIGNATURE.length).equals(PNG_SIGNATURE)) {
+    return { mimeType: "image/png", animated: inspectPng(bytes) };
+  }
+  if (
+    bytes.length >= 3 &&
+    bytes[0] === 0xff &&
+    bytes[1] === 0xd8 &&
+    bytes[2] === 0xff
+  ) {
+    return { mimeType: "image/jpeg", animated: false };
+  }
+  if (
+    bytes.length >= 12 &&
+    bytes.toString("ascii", 0, 4) === "RIFF" &&
+    bytes.toString("ascii", 8, 12) === "WEBP"
+  ) {
+    return { mimeType: "image/webp", animated: inspectWebp(bytes) };
+  }
+  const prefix = bytes.subarray(0, Math.min(bytes.length, 512));
+  const looksUnsupported =
+    prefix.subarray(0, 6).toString("ascii") === "GIF87a" ||
+    prefix.subarray(0, 6).toString("ascii") === "GIF89a" ||
+    prefix.toString("utf8").trimStart().startsWith("<svg") ||
+    /\.(?:apng|avif|bmp|gif|heic|heif|jpe?g|png|svg|tiff?|webp)$/i.test(
+      sourceName ?? "",
+    );
+  if (looksUnsupported) {
+    throw new UnsupportedImageFormatError(
+      "Image format is unsupported or the image content is invalid.",
+    );
+  }
+  throw new ImageNotRecognizedError("Selected file is not an image.");
+}
+
+function inspectPng(bytes: Buffer): boolean {
+  let offset = PNG_SIGNATURE.length;
+  let chunkIndex = 0;
+  let sawIend = false;
+  let animated = false;
+  while (offset < bytes.length) {
+    if (bytes.length - offset < 12) {
+      throw new Error("PNG container is truncated.");
+    }
+    const length = bytes.readUInt32BE(offset);
+    const type = bytes.toString("ascii", offset + 4, offset + 8);
+    const chunkEnd = offset + 12 + length;
+    if (!/^[A-Za-z]{4}$/.test(type) || chunkEnd > bytes.length) {
+      throw new Error("PNG chunk length or type is invalid.");
+    }
+    if (chunkIndex === 0 && (type !== "IHDR" || length !== 13)) {
+      throw new Error("PNG must begin with a valid IHDR chunk.");
+    }
+    if (type === "acTL") {
+      if (length !== 8) {
+        throw new Error("PNG acTL chunk is invalid.");
+      }
+      animated = true;
+    }
+    if (type === "IEND") {
+      if (length !== 0 || chunkEnd !== bytes.length) {
+        throw new Error("PNG IEND chunk or trailing data is invalid.");
+      }
+      sawIend = true;
+      break;
+    }
+    offset = chunkEnd;
+    chunkIndex += 1;
+  }
+  if (!sawIend) {
+    throw new Error("PNG container has no IEND chunk.");
+  }
+  return animated;
+}
+
+function inspectWebp(bytes: Buffer): boolean {
+  const declaredSize = bytes.readUInt32LE(4) + 8;
+  if (declaredSize !== bytes.length) {
+    throw new Error("WebP RIFF size does not match the file length.");
+  }
+  let offset = 12;
+  let animated = false;
+  let chunkCount = 0;
+  while (offset < bytes.length) {
+    if (bytes.length - offset < 8) {
+      throw new Error("WebP container is truncated.");
+    }
+    const type = bytes.toString("ascii", offset, offset + 4);
+    const length = bytes.readUInt32LE(offset + 4);
+    const dataStart = offset + 8;
+    const paddedEnd = dataStart + length + (length % 2);
+    if (!/^[ -~]{4}$/.test(type) || paddedEnd > bytes.length) {
+      throw new Error("WebP chunk length or type is invalid.");
+    }
+    if (type === "VP8X") {
+      if (length !== 10) {
+        throw new Error("WebP VP8X chunk is invalid.");
+      }
+      animated ||= (bytes[dataStart] & 0x02) !== 0;
+    }
+    if (type === "ANIM" || type === "ANMF") {
+      animated = true;
+    }
+    chunkCount += 1;
+    offset = paddedEnd;
+  }
+  if (offset !== bytes.length || chunkCount === 0) {
+    throw new Error("WebP container has an invalid chunk boundary.");
+  }
+  return animated;
+}
+
+function mimeTypeForSharpFormat(format: string | undefined): ImageMimeType {
+  switch (format) {
+    case "png":
+      return "image/png";
+    case "jpeg":
+      return "image/jpeg";
+    case "webp":
+      return "image/webp";
+    default:
+      throw new Error(`Unsupported decoded image format: ${String(format)}.`);
+  }
+}
+
+function requireDimension(value: number | undefined, name: string): number {
+  if (!Number.isSafeInteger(value) || value === undefined || value < 1) {
+    throw new Error(`Decoded image ${name} must be a positive safe integer.`);
+  }
+  return value;
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}