@intx/agent 0.1.2

package/src/lock.test.ts

@@ -0,0 +1,93 @@
+import { describe, test, expect } from "bun:test";
+import { resolve } from "node:path";
+
+import { acquireContextDirLock, AgentInUseError } from "./lock";
+
+describe("acquireContextDirLock", () => {
+  test("returns a lock whose path is the resolved absolute path", () => {
+    const lock = acquireContextDirLock("/tmp/agent-lock-1");
+    try {
+      expect(lock.path).toBe(resolve("/tmp/agent-lock-1"));
+    } finally {
+      lock.release();
+    }
+  });
+
+  test("rejects a second acquisition of the same directory", () => {
+    const lock = acquireContextDirLock("/tmp/agent-lock-2");
+    try {
+      expect(() => acquireContextDirLock("/tmp/agent-lock-2")).toThrow(
+        AgentInUseError,
+      );
+    } finally {
+      lock.release();
+    }
+  });
+
+  test("re-acquires the same directory after release", () => {
+    const lock1 = acquireContextDirLock("/tmp/agent-lock-3");
+    lock1.release();
+    const lock2 = acquireContextDirLock("/tmp/agent-lock-3");
+    try {
+      expect(lock2.path).toBe(resolve("/tmp/agent-lock-3"));
+    } finally {
+      lock2.release();
+    }
+  });
+
+  test("collides on lexically distinct but equivalent paths", () => {
+    const lock = acquireContextDirLock("/tmp/agent-lock-4/../agent-lock-4/foo");
+    try {
+      expect(() => acquireContextDirLock("/tmp/agent-lock-4/foo")).toThrow(
+        AgentInUseError,
+      );
+    } finally {
+      lock.release();
+    }
+  });
+
+  test("collides on a relative path that resolves to the same absolute path", () => {
+    const absolute = resolve("relative-lock-test-dir");
+    const lock = acquireContextDirLock("relative-lock-test-dir");
+    try {
+      expect(lock.path).toBe(absolute);
+      expect(() => acquireContextDirLock(absolute)).toThrow(AgentInUseError);
+    } finally {
+      lock.release();
+    }
+  });
+
+  test("does not collide between distinct directories", () => {
+    const lock1 = acquireContextDirLock("/tmp/agent-lock-5a");
+    const lock2 = acquireContextDirLock("/tmp/agent-lock-5b");
+    try {
+      expect(lock1.path).not.toBe(lock2.path);
+    } finally {
+      lock1.release();
+      lock2.release();
+    }
+  });
+
+  test("release is idempotent", () => {
+    const lock = acquireContextDirLock("/tmp/agent-lock-6");
+    lock.release();
+    lock.release();
+    const reacquired = acquireContextDirLock("/tmp/agent-lock-6");
+    reacquired.release();
+  });
+
+  test("AgentInUseError exposes contextDir as the resolved path", () => {
+    const lock = acquireContextDirLock("/tmp/agent-lock-7");
+    try {
+      acquireContextDirLock("/tmp/agent-lock-7");
+      throw new Error("should have thrown AgentInUseError");
+    } catch (err) {
+      expect(err).toBeInstanceOf(AgentInUseError);
+      if (err instanceof AgentInUseError) {
+        expect(err.contextDir).toBe(resolve("/tmp/agent-lock-7"));
+      }
+    } finally {
+      lock.release();
+    }
+  });
+});

package/src/lock.ts

@@ -0,0 +1,57 @@
+// Process-wide registry of held context-directory locks.
+//
+// The agent enforces a runtime singleton-per-contextDir invariant: at most one
+// in-process agent may own a given context directory at a time. Holding two
+// agents against the same directory simultaneously corrupts both the git
+// state and the audit collector's bookkeeping.
+//
+// This is a best-effort in-process check. It does not coordinate across OS
+// processes, and it compares lexically-resolved absolute paths — two paths
+// that point to the same directory through symlinks or `..`/`/./` segments
+// are normalized by `path.resolve`, but a hard link or a separately mounted
+// bind to the same inode will not be detected. Callers passing their own
+// `contextStore` (rather than a `contextDir` string) bypass the lock; they
+// are responsible for their store's lifetime.
+
+import { resolve } from "node:path";
+
+const heldLocks = new Set<string>();
+
+export class AgentInUseError extends Error {
+  readonly contextDir: string;
+
+  constructor(contextDir: string) {
+    super(`an agent is already open for context directory: ${contextDir}`);
+    this.name = "AgentInUseError";
+    this.contextDir = contextDir;
+  }
+}
+
+export type ContextDirLock = {
+  /** Absolute, resolved path of the locked directory. */
+  readonly path: string;
+  /** Release the lock. Idempotent. */
+  release(): void;
+};
+
+/**
+ * Acquire the process-wide lock for `contextDir`. Throws `AgentInUseError`
+ * if another agent already holds it. The returned `release` is idempotent.
+ */
+export function acquireContextDirLock(contextDir: string): ContextDirLock {
+  const path = resolve(contextDir);
+  if (heldLocks.has(path)) {
+    throw new AgentInUseError(path);
+  }
+  heldLocks.add(path);
+
+  let released = false;
+  return {
+    path,
+    release() {
+      if (released) return;
+      released = true;
+      heldLocks.delete(path);
+    },
+  };
+}

package/src/send-queue.test.ts

@@ -0,0 +1,207 @@
+import { describe, test, expect } from "bun:test";
+
+import { createSendQueue, SendQueueFullError } from "./send-queue";
+
+/**
+ * Tests use `string` as the result type so the queue's generic R parameter
+ * holds a real value (it cannot be `void` under
+ * `@typescript-eslint/no-invalid-void-type`). The actual values are
+ * arbitrary; tests assert ordering and lifecycle, not result content.
+ */
+
+describe("createSendQueue", () => {
+  test("starts the first enqueued item immediately", () => {
+    const started: string[] = [];
+    const q = createSendQueue<string, string>({
+      maxDepth: 4,
+      start: (item) => {
+        started.push(item);
+      },
+    });
+
+    void q.enqueue("a");
+    expect(started).toEqual(["a"]);
+  });
+
+  test("queues subsequent items and starts each on resolveActive", async () => {
+    const started: string[] = [];
+    const q = createSendQueue<string, string>({
+      maxDepth: 4,
+      start: (item) => {
+        started.push(item);
+      },
+    });
+
+    const p1 = q.enqueue("a");
+    const p2 = q.enqueue("b");
+    expect(started).toEqual(["a"]);
+
+    q.resolveActive("r1");
+    expect(await p1).toBe("r1");
+    expect(started).toEqual(["a", "b"]);
+
+    q.resolveActive("r2");
+    expect(await p2).toBe("r2");
+  });
+
+  test("throws SendQueueFullError synchronously at capacity", () => {
+    const started: number[] = [];
+    const q = createSendQueue<number, string>({
+      maxDepth: 2,
+      start: (item) => {
+        started.push(item);
+      },
+    });
+
+    void q.enqueue(1);
+    void q.enqueue(2);
+    expect(() => q.enqueue(3)).toThrow(SendQueueFullError);
+  });
+
+  test("rejects pre-aborted signal without enqueuing", async () => {
+    const ctl = new AbortController();
+    ctl.abort();
+
+    const started: number[] = [];
+    const q = createSendQueue<number, string>({
+      maxDepth: 4,
+      start: (item) => {
+        started.push(item);
+      },
+    });
+
+    await expect(q.enqueue(1, ctl.signal)).rejects.toBeDefined();
+    expect(started).toEqual([]);
+    expect(q.depth).toBe(0);
+  });
+
+  test("removes a queued item whose signal fires before processing", async () => {
+    const started: number[] = [];
+    const ctl = new AbortController();
+    const q = createSendQueue<number, string>({
+      maxDepth: 4,
+      start: (item) => {
+        started.push(item);
+      },
+    });
+
+    const p1 = q.enqueue(1);
+    const p2 = q.enqueue(2, ctl.signal);
+    const p3 = q.enqueue(3);
+
+    expect(started).toEqual([1]);
+    ctl.abort();
+    await expect(p2).rejects.toBeDefined();
+
+    q.resolveActive("r1");
+    expect(await p1).toBe("r1");
+    expect(started).toEqual([1, 3]);
+
+    q.resolveActive("r3");
+    expect(await p3).toBe("r3");
+  });
+
+  test("settles caller on in-flight abort but waits for consumer to advance", async () => {
+    const started: number[] = [];
+    const ctl = new AbortController();
+    const q = createSendQueue<number, string>({
+      maxDepth: 4,
+      start: (item) => {
+        started.push(item);
+      },
+    });
+
+    const p1 = q.enqueue(1, ctl.signal);
+    const p2 = q.enqueue(2);
+    expect(started).toEqual([1]);
+
+    ctl.abort();
+    await expect(p1).rejects.toBeDefined();
+    // Active slot is still held until the consumer reports the cycle done.
+    expect(started).toEqual([1]);
+
+    q.resolveActive("late-r1");
+    expect(started).toEqual([1, 2]);
+
+    q.resolveActive("r2");
+    expect(await p2).toBe("r2");
+  });
+
+  test("late resolveActive after abort is a no-op for the caller", async () => {
+    const ctl = new AbortController();
+    const started: number[] = [];
+    const q = createSendQueue<number, string>({
+      maxDepth: 4,
+      start: (item) => {
+        started.push(item);
+      },
+    });
+
+    const p = q.enqueue(1, ctl.signal);
+    ctl.abort();
+    await expect(p).rejects.toBeDefined();
+
+    q.resolveActive("late");
+    expect(q.depth).toBe(0);
+  });
+
+  test("drain rejects active and pending jobs with the given reason", async () => {
+    const started: number[] = [];
+    const q = createSendQueue<number, string>({
+      maxDepth: 4,
+      start: (item) => {
+        started.push(item);
+      },
+    });
+
+    const p1 = q.enqueue(1);
+    const p2 = q.enqueue(2);
+    const reason = new Error("closed");
+
+    q.drain(reason);
+    await expect(p1).rejects.toBe(reason);
+    await expect(p2).rejects.toBe(reason);
+    expect(q.depth).toBe(0);
+  });
+
+  test("depth reflects active + pending", () => {
+    const started: number[] = [];
+    const q = createSendQueue<number, string>({
+      maxDepth: 4,
+      start: (item) => {
+        started.push(item);
+      },
+    });
+
+    expect(q.depth).toBe(0);
+    void q.enqueue(1);
+    expect(q.depth).toBe(1);
+    void q.enqueue(2);
+    expect(q.depth).toBe(2);
+
+    q.resolveActive("r1");
+    expect(q.depth).toBe(1);
+    q.resolveActive("r2");
+    expect(q.depth).toBe(0);
+  });
+
+  test("capacity check counts the abandoned active slot", async () => {
+    const ctl = new AbortController();
+    const started: number[] = [];
+    const q = createSendQueue<number, string>({
+      maxDepth: 2,
+      start: (item) => {
+        started.push(item);
+      },
+    });
+
+    const p1 = q.enqueue(1, ctl.signal);
+    void q.enqueue(2);
+    ctl.abort();
+    await expect(p1).rejects.toBeDefined();
+
+    // Active slot still occupied (consumer has not advanced). Adding a
+    // third would exceed maxDepth=2.
+    expect(() => q.enqueue(3)).toThrow(SendQueueFullError);
+  });
+});

package/src/send-queue.ts

@@ -0,0 +1,200 @@
+// FIFO queue for serializing send() calls against a single reactor.
+//
+// The agent processes one reactor cycle at a time, so concurrent send()
+// callers are queued. Each queued item carries the caller's resolve/reject
+// hooks and an optional AbortSignal:
+//
+//   - If the signal is already aborted when enqueue() is called the queue
+//     rejects synchronously without enqueueing.
+//   - If the signal fires while the item is still queued the item is
+//     removed and rejected.
+//   - If the signal fires while the item is active the caller-facing
+//     promise rejects immediately, but the reactor cycle continues in the
+//     background. The queue does not start the next item until the consumer
+//     reports the cycle done via resolveActive/rejectActive. This keeps the
+//     queue ordered against actual reactor cycles — two send() promises
+//     cannot interleave at the reactor level.
+//
+// Queue depth (active + pending) is bounded by `maxDepth`; exceeding it
+// throws `SendQueueFullError` synchronously from enqueue() so a buggy
+// caller flooding sends fails loud instead of silently buffering.
+
+export class SendQueueFullError extends Error {
+  readonly maxDepth: number;
+
+  constructor(maxDepth: number) {
+    super(`send queue is full (max depth ${String(maxDepth)})`);
+    this.name = "SendQueueFullError";
+    this.maxDepth = maxDepth;
+  }
+}
+
+type Job<T, R> = {
+  item: T;
+  signal?: AbortSignal;
+  abortHandler?: () => void;
+  resolve: (value: R) => void;
+  reject: (reason: unknown) => void;
+  /**
+   * True once the caller-facing promise has been settled (resolve or
+   * reject). Subsequent settles are no-ops. The active slot may remain
+   * occupied after a settle when the caller aborted mid-cycle — the queue
+   * waits for the consumer's resolveActive/rejectActive before pumping the
+   * next item.
+   */
+  settled: boolean;
+};
+
+export type SendQueueOptions<T> = {
+  maxDepth: number;
+  /**
+   * Called when a job moves from pending to active. The consumer drives
+   * the underlying work and must eventually call `resolveActive` or
+   * `rejectActive` exactly once.
+   */
+  start: (item: T) => void;
+};
+
+export type SendQueue<T, R> = {
+  enqueue(item: T, signal?: AbortSignal): Promise<R>;
+  /** Mark the active job complete with success and pump the next. */
+  resolveActive(value: R): void;
+  /** Mark the active job complete with failure and pump the next. */
+  rejectActive(reason: unknown): void;
+  /** Reject the active job (if any) and every pending job with `reason`. */
+  drain(reason: unknown): void;
+  /** Current pending count (queued + active). */
+  readonly depth: number;
+};
+
+function abortReason(signal: AbortSignal): unknown {
+  return signal.reason ?? new DOMException("aborted", "AbortError");
+}
+
+export function createSendQueue<T, R>(
+  opts: SendQueueOptions<T>,
+): SendQueue<T, R> {
+  const pending: Job<T, R>[] = [];
+  let active: Job<T, R> | null = null;
+
+  function settle(
+    job: Job<T, R>,
+    kind: "resolve" | "reject",
+    value: unknown,
+  ): void {
+    if (job.settled) return;
+    job.settled = true;
+    if (job.abortHandler !== undefined && job.signal !== undefined) {
+      job.signal.removeEventListener("abort", job.abortHandler);
+    }
+    if (kind === "resolve") {
+      // The queue's value type is checked at enqueue / resolveActive; the
+      // generic narrowing here is safe by construction.
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- generic resolve value
+      job.resolve(value as R);
+    } else {
+      job.reject(value);
+    }
+  }
+
+  function pump(): void {
+    while (active === null && pending.length > 0) {
+      const next = pending.shift();
+      if (next === undefined) return;
+      if (next.signal?.aborted === true) {
+        settle(next, "reject", abortReason(next.signal));
+        continue;
+      }
+      active = next;
+      opts.start(next.item);
+      return;
+    }
+  }
+
+  function enqueue(item: T, signal?: AbortSignal): Promise<R> {
+    if (signal?.aborted === true) {
+      return Promise.reject(abortReason(signal));
+    }
+
+    const depth = pending.length + (active !== null ? 1 : 0);
+    if (depth >= opts.maxDepth) {
+      throw new SendQueueFullError(opts.maxDepth);
+    }
+
+    let resolve!: (value: R) => void;
+    let reject!: (reason: unknown) => void;
+    const promise = new Promise<R>((res, rej) => {
+      resolve = res;
+      reject = rej;
+    });
+
+    const job: Job<T, R> = {
+      item,
+      ...(signal !== undefined ? { signal } : {}),
+      resolve,
+      reject,
+      settled: false,
+    };
+
+    if (signal !== undefined) {
+      const handler = (): void => {
+        const reason = abortReason(signal);
+        if (active === job) {
+          // In flight: settle the caller now; the consumer will eventually
+          // call resolveActive/rejectActive which becomes a no-op and
+          // advances the queue.
+          settle(job, "reject", reason);
+        } else {
+          const idx = pending.indexOf(job);
+          if (idx >= 0) pending.splice(idx, 1);
+          settle(job, "reject", reason);
+        }
+      };
+      signal.addEventListener("abort", handler, { once: true });
+      job.abortHandler = handler;
+    }
+
+    pending.push(job);
+    pump();
+    return promise;
+  }
+
+  function resolveActive(value: R): void {
+    if (active === null) return;
+    const job = active;
+    active = null;
+    settle(job, "resolve", value);
+    pump();
+  }
+
+  function rejectActive(reason: unknown): void {
+    if (active === null) return;
+    const job = active;
+    active = null;
+    settle(job, "reject", reason);
+    pump();
+  }
+
+  function drain(reason: unknown): void {
+    const drained: Job<T, R>[] = [];
+    if (active !== null) {
+      drained.push(active);
+      active = null;
+    }
+    drained.push(...pending);
+    pending.length = 0;
+    for (const job of drained) {
+      settle(job, "reject", reason);
+    }
+  }
+
+  return {
+    enqueue,
+    resolveActive,
+    rejectActive,
+    drain,
+    get depth() {
+      return pending.length + (active !== null ? 1 : 0);
+    },
+  };
+}