@abot-ai/runtime 1.5.0 → 1.6.0

package/plugins/exec/source/output-store.ts

@@ -0,0 +1,182 @@
+import { readdir, rm } from "node:fs/promises";
+import { join } from "node:path";
+import {
+  DEFAULT_EXEC_OUTPUT_RETENTION_MS,
+  type ExecOutputBody,
+  type ExecOutputRange,
+  type ExecOutputStream,
+} from "./output-contracts.js";
+import {
+  outputFailure,
+  outputOwnerDirectory,
+  outputStorageRoot,
+  outputStreamPath,
+  prepareOutputOwnerDirectory,
+  readOutputOwner,
+  readOutputSnapshot,
+  writeOutputMetadata,
+} from "./output-files.js";
+import {
+  assertOutputBodyHash,
+  assertOutputRange,
+  readOutputFileRange,
+} from "./output-range-reader.js";
+import { scheduleExecOutputCleanup } from "./output-maintenance.js";
+import { hasOutputExpired } from "./output-retention.js";
+import { createOutputWriter } from "./output-writer.js";
+
+const activeWriters = new Map<string, number>();
+const activeReaders = new Map<string, number>();
+const ownerOperations = new Map<string, Promise<void>>();
+async function withOutputOwnerLock<T>(
+  directory: string,
+  operation: () => Promise<T>,
+): Promise<T> {
+  const previous = ownerOperations.get(directory) ?? Promise.resolve();
+  let release = () => {};
+  const current = new Promise<void>((resolve) => {
+    release = resolve;
+  });
+  ownerOperations.set(directory, current);
+  await previous;
+  try {
+    return await operation();
+  } finally {
+    release();
+    if (ownerOperations.get(directory) === current)
+      ownerOperations.delete(directory);
+  }
+}
+
+export function createExecOutputStore(
+  params: Readonly<{
+    stateDir: string;
+    retentionMs?: number;
+    now?: () => number;
+  }>,
+) {
+  const root = outputStorageRoot(params.stateDir);
+  const retentionMs = params.retentionMs ?? DEFAULT_EXEC_OUTPUT_RETENTION_MS;
+  if (!Number.isSafeInteger(retentionMs) || retentionMs < 0)
+    throw outputFailure("retention_invalid");
+  const now = params.now ?? Date.now;
+  async function retain(directory: string, ownerId: string) {
+    await prepareOutputOwnerDirectory(directory);
+    const previous = await readOutputOwner(directory);
+    if (previous && previous.ownerId !== ownerId)
+      throw outputFailure("owner_binding_invalid");
+    if (previous?.completedAt === null) return;
+    await writeOutputMetadata(join(directory, "owner.json"), {
+      kind: "exec_output_owner_v1",
+      ownerId,
+      completedAt: null,
+    });
+  }
+  const store = Object.freeze({
+    async createWriter(
+      input: Readonly<{ ownerId: string; stream: ExecOutputStream }>,
+    ) {
+      if (input.stream !== "stdout" && input.stream !== "stderr")
+        throw outputFailure("stream_invalid");
+      const directory = outputOwnerDirectory(root, input.ownerId);
+      return withOutputOwnerLock(directory, async () => {
+        await retain(directory, input.ownerId);
+        const writer = await createOutputWriter({
+          directory,
+          ownerId: input.ownerId,
+          stream: input.stream,
+          async onClosed() {
+            await withOutputOwnerLock(directory, async () => {
+              const count = (activeWriters.get(directory) ?? 1) - 1;
+              if (count > 0) activeWriters.set(directory, count);
+              if (count > 0) return;
+              activeWriters.delete(directory);
+              await writeOutputMetadata(join(directory, "owner.json"), {
+                kind: "exec_output_owner_v1",
+                ownerId: input.ownerId,
+                completedAt: now(),
+              });
+            });
+          },
+        });
+        activeWriters.set(directory, (activeWriters.get(directory) ?? 0) + 1);
+        store.startMaintenance();
+        return writer;
+      });
+    },
+    async *readRange(
+      input: Readonly<{ ownerId: string; body: ExecOutputBody }> &
+        ExecOutputRange,
+    ): AsyncIterable<Uint8Array> {
+      const directory = outputOwnerDirectory(root, input.ownerId);
+      assertOutputRange(
+        input.offset,
+        input.offset + input.length,
+        input.body.byteLength,
+      );
+      await withOutputOwnerLock(directory, async () => {
+        const owner = await readOutputOwner(directory);
+        if (!owner) throw outputFailure("expired_or_unavailable");
+        if (owner.ownerId !== input.ownerId)
+          throw outputFailure("owner_binding_invalid");
+        if (
+          !activeWriters.has(directory) &&
+          (await hasOutputExpired(directory, owner, now(), retentionMs))
+        )
+          throw outputFailure("expired");
+        activeReaders.set(directory, (activeReaders.get(directory) ?? 0) + 1);
+      });
+      try {
+        const snapshot = await readOutputSnapshot(
+          directory,
+          input.ownerId,
+          input.body,
+        );
+        const path = outputStreamPath(directory, snapshot.streamId);
+        await assertOutputBodyHash(path, input.body, input.signal);
+        yield* readOutputFileRange(path, {
+          offset: input.body.startByte + input.offset,
+          length: input.length,
+          maxChunkBytes: input.maxChunkBytes,
+          ...(input.signal ? { signal: input.signal } : {}),
+        });
+      } finally {
+        const count = (activeReaders.get(directory) ?? 1) - 1;
+        if (count > 0) activeReaders.set(directory, count);
+        if (count === 0) activeReaders.delete(directory);
+      }
+    },
+    startMaintenance(): void {
+      scheduleExecOutputCleanup(root, retentionMs, () =>
+        store.cleanupExpired(),
+      );
+    },
+    async cleanupExpired(): Promise<number> {
+      const directories = await readdir(root, { withFileTypes: true }).catch(
+        (error: NodeJS.ErrnoException) => {
+          if (error.code === "ENOENT") return [];
+          throw outputFailure("cleanup_failed", error);
+        },
+      );
+      let removed = 0;
+      for (const entry of directories) {
+        if (!entry.isDirectory() || !/^[a-f0-9]{64}$/.test(entry.name))
+          continue;
+        const directory = join(root, entry.name);
+        await withOutputOwnerLock(directory, async () => {
+          if (activeWriters.has(directory)) return;
+          if (activeReaders.has(directory)) return;
+          const owner = await readOutputOwner(directory);
+          if (owner && outputOwnerDirectory(root, owner.ownerId) !== directory)
+            throw outputFailure("owner_binding_invalid");
+          if (!(await hasOutputExpired(directory, owner, now(), retentionMs)))
+            return;
+          await rm(directory, { recursive: true });
+          removed += 1;
+        });
+      }
+      return removed;
+    },
+  });
+  return store;
+}

package/plugins/exec/source/output-utf8-boundary.ts

@@ -0,0 +1,14 @@
+/** Keep a valid UTF8 code point together when a running process is observed. */
+export function incompleteUtf8TailBytes(tail: Uint8Array): number {
+  if (tail.length === 0) return 0;
+  let lead = tail.length - 1;
+  while (lead >= 0 && (tail[lead]! & 0xc0) === 0x80) lead -= 1;
+  if (lead < 0) return 0;
+  const byte = tail[lead]!;
+  let expected = 1;
+  if (byte >= 0xc2 && byte <= 0xdf) expected = 2;
+  if (byte >= 0xe0 && byte <= 0xef) expected = 3;
+  if (byte >= 0xf0 && byte <= 0xf4) expected = 4;
+  const available = tail.length - lead;
+  return available < expected ? available : 0;
+}

package/plugins/exec/source/output-writer.ts

@@ -0,0 +1,131 @@
+import { incompleteUtf8TailBytes } from "./output-utf8-boundary.js";
+import { randomUUID } from "node:crypto";
+import { open, type FileHandle } from "node:fs/promises";
+import { Writable } from "node:stream";
+import { finished } from "node:stream/promises";
+import {
+  EXEC_OUTPUT_IO_CHUNK_BYTES,
+  type ExecOutputBody,
+  type ExecOutputStream,
+  type ExecOutputWriter,
+} from "./output-contracts.js";
+import {
+  outputFailure,
+  outputSnapshotPath,
+  outputStreamPath,
+  writeOutputMetadata,
+} from "./output-files.js";
+import { assertOutputRange, hashOutputRange } from "./output-range-reader.js";
+
+class OutputFileSink extends Writable {
+  committedBytes = 0;
+  utf8ByteLength = 0;
+  private tail = Buffer.alloc(0);
+  constructor(private readonly file: FileHandle) {
+    super({ highWaterMark: EXEC_OUTPUT_IO_CHUNK_BYTES });
+  }
+  override _write(
+    chunk: Buffer,
+    _encoding: BufferEncoding,
+    callback: (error?: Error | null) => void,
+  ): void {
+    this.writeChunk(chunk).then(
+      () => callback(),
+      (error) => callback(outputFailure("write_failed", error)),
+    );
+  }
+  private async writeChunk(chunk: Buffer): Promise<void> {
+    let offset = 0;
+    while (offset < chunk.length) {
+      const length = Math.min(
+        EXEC_OUTPUT_IO_CHUNK_BYTES,
+        chunk.length - offset,
+      );
+      const { bytesWritten } = await this.file.write(
+        chunk,
+        offset,
+        length,
+        this.committedBytes,
+      );
+      if (bytesWritten === 0) throw outputFailure("write_zero_progress");
+      const written = chunk.subarray(offset, offset + bytesWritten);
+      this.tail = Buffer.concat([this.tail, written.subarray(-4)]).subarray(-4);
+      offset += bytesWritten;
+      this.committedBytes += bytesWritten;
+      this.utf8ByteLength =
+        this.committedBytes - incompleteUtf8TailBytes(this.tail);
+    }
+  }
+  override _final(callback: (error?: Error | null) => void): void {
+    this.file.datasync().then(
+      () => callback(),
+      (error) => callback(outputFailure("write_failed", error)),
+    );
+  }
+  override _destroy(
+    error: Error | null,
+    callback: (error?: Error | null) => void,
+  ): void {
+    this.file.close().then(
+      () => callback(error),
+      (cause) => callback(error ?? outputFailure("close_failed", cause)),
+    );
+  }
+}
+
+export async function createOutputWriter(
+  params: Readonly<{
+    directory: string;
+    ownerId: string;
+    stream: ExecOutputStream;
+    onClosed(): void | Promise<void>;
+  }>,
+): Promise<ExecOutputWriter> {
+  const streamId = randomUUID();
+  const path = outputStreamPath(params.directory, streamId);
+  const file = await open(path, "wx+", 0o600).catch((error) => {
+    throw outputFailure("write_failed", error);
+  });
+  const sink = new OutputFileSink(file);
+  const completion = finished(sink).finally(params.onClosed);
+  void completion.catch(() => undefined);
+  return Object.freeze({
+    sink,
+    get byteLength() {
+      return sink.committedBytes;
+    },
+    get utf8ByteLength() {
+      return sink.utf8ByteLength;
+    },
+    completion,
+    async snapshot(
+      range: Readonly<{ startByte: number; endByte?: number }> = {
+        startByte: 0,
+      },
+    ): Promise<ExecOutputBody> {
+      if (sink.errored) throw sink.errored;
+      const startByte = range.startByte;
+      const endByte = range.endByte ?? sink.committedBytes;
+      assertOutputRange(startByte, endByte, sink.committedBytes);
+      const body = Object.freeze({
+        id: randomUUID(),
+        stream: params.stream,
+        startByte,
+        endByte,
+        byteLength: endByte - startByte,
+        sha256: await hashOutputRange(path, startByte, endByte),
+      });
+      await writeOutputMetadata(outputSnapshotPath(params.directory, body.id), {
+        kind: "exec_output_snapshot_v1",
+        ownerId: params.ownerId,
+        streamId,
+        body,
+      });
+      return body;
+    },
+    async dispose() {
+      if (!sink.destroyed) sink.destroy();
+      await completion.catch(() => undefined);
+    },
+  });
+}