@halofy/agent-connect 0.1.0

package/src/runtime.mjs

@@ -0,0 +1,254 @@
+import { createHash, randomBytes } from "node:crypto";
+import { join } from "node:path";
+import { BoundedEncryptedQueue } from "./queue.mjs";
+import { CursorStore, deriveSessionHash, readClaudeTranscriptSuffix } from "./session.mjs";
+import { SignedRuntimeTransport } from "./transport.mjs";
+import { withFileLock } from "./storage.mjs";
+
+export class LifecycleRuntime {
+  constructor(connection, {
+    root,
+    transport = new SignedRuntimeTransport(connection),
+    maxBatchEvents = 100,
+    maxBatchBytes = 1024 * 1024,
+    commitThreshold = 20,
+  } = {}) {
+    if (!root) throw new Error("runtime storage root is required");
+    this.connection = connection;
+    this.transport = transport;
+    const connectionRoot = join(root, connection.installationId);
+    this.queue = new BoundedEncryptedQueue(connectionRoot);
+    this.cursors = new CursorStore(connectionRoot);
+    this.operationLockPath = join(connectionRoot, "runtime.operation.lock");
+    this.maxBatchEvents = Math.min(100, Math.max(1, maxBatchEvents));
+    this.maxBatchBytes = Math.min(1024 * 1024, Math.max(1024, maxBatchBytes));
+    this.commitThreshold = commitThreshold;
+    this.sessions = new Map();
+  }
+
+  sessionHash(hostSessionId) {
+    return deriveSessionHash({
+      installationId: this.connection.installationId,
+      clientKind: this.connection.clientKind,
+      hostSessionId,
+    });
+  }
+
+  async resolveSessionByHash(sessionHash, parentSessionId) {
+    if (this.sessions.has(sessionHash)) return this.sessions.get(sessionHash);
+    const opened = await this.transport.openSession({
+      externalSessionId: sessionHash,
+      ...(parentSessionId ? { parentSessionId } : {}),
+    });
+    const sessionId = opened?.sessionId || opened?.id;
+    if (!sessionId) throw new Error("session open returned no session id");
+    this.sessions.set(sessionHash, sessionId);
+    return sessionId;
+  }
+
+  async resolveSession(hostSessionId, parentHostSessionId) {
+    const parentSessionId = parentHostSessionId
+      ? await this.resolveSessionByHash(this.sessionHash(parentHostSessionId))
+      : undefined;
+    return this.resolveSessionByHash(this.sessionHash(hostSessionId), parentSessionId);
+  }
+
+  async recall(hostSessionId, query, budget = 1_500) {
+    const sessionId = await this.resolveSession(hostSessionId);
+    const recalled = await this.transport.recall(sessionId, { query: String(query).slice(0, 8_000), tokenBudget: budget });
+    const blocks = Array.isArray(recalled?.blocks) ? recalled.blocks : Array.isArray(recalled) ? recalled : [];
+    const references = (Array.isArray(recalled?.refs) ? recalled.refs : blocks.map((block) => block?.recallRef))
+      .filter((reference) => typeof reference === "string" && reference.length > 0)
+      .slice(0, 64)
+      .map((reference) => reference.slice(0, 256));
+    if (references.length > 0) {
+      try {
+        await this.enqueueEvent(hostSessionId, {
+          eventKey: `context-recalled:${newLocalEventId()}`,
+          occurredAt: new Date().toISOString(),
+          type: "context_recalled",
+          payload: { refs: references },
+          payloadSha256: createHash("sha256").update(JSON.stringify({ refs: references })).digest("hex"),
+        });
+      } catch {
+        // enqueueEvent persists before replay. A brownout must not turn ranked
+        // recall blocks into an unavailable hook response.
+      }
+    }
+    return recalled;
+  }
+
+  async recordContextUsed(hostSessionId, references) {
+    const bounded = references.filter((value) => typeof value === "string").slice(0, 64).map((value) => value.slice(0, 256));
+    if (bounded.length === 0) return null;
+    return withFileLock(this.operationLockPath, async () => {
+      await this.#replayUnlocked();
+      const sessionHash = this.sessionHash(hostSessionId);
+      const cursor = await this.cursors.get(sessionHash);
+      const response = await this.transport.contextUsed(await this.resolveSession(hostSessionId), {
+        eventId: `context-used:${newLocalEventId()}`,
+        sequence: cursor.sequence + 1,
+        occurredAt: new Date().toISOString(),
+        refs: bounded,
+      });
+      if (Number(response?.accepted ?? 0) + Number(response?.duplicates ?? 0) > 0) {
+        await this.cursors.update(sessionHash, { sequence: cursor.sequence + 1 });
+      }
+      return response;
+    });
+  }
+
+  async captureClaudeTranscript(hostSessionId, transcriptPath) {
+    const sessionHash = this.sessionHash(hostSessionId);
+    const queued = await withFileLock(this.operationLockPath, async () => {
+      const cursor = await this.cursors.get(sessionHash);
+      const suffix = await readClaudeTranscriptSuffix(transcriptPath, cursor, sessionHash);
+      const recentEventKeys = new Set(Array.isArray(cursor.recentEventKeys) ? cursor.recentEventKeys : []);
+      const unseenEvents = suffix.events.filter((event) => !recentEventKeys.has(event.eventKey));
+      const result = unseenEvents.length === 0
+        ? { queued: 0 }
+        : await this.queue.enqueueSessionEvents(sessionHash, unseenEvents, {
+          maxBatchEvents: this.maxBatchEvents,
+          maxBatchBytes: this.maxBatchBytes,
+          acknowledgedSequence: cursor.sequence,
+        });
+      // Complete ignored/malformed JSONL records carry no event, while every
+      // normalized event is already durable in the encrypted queue. Advancing
+      // this byte cursor prevents unbounded reparsing without advancing the
+      // separately acknowledged event sequence.
+      if (suffix.observedEndOffset > cursor.byteOffset) {
+        await this.cursors.update(sessionHash, { byteOffset: suffix.observedEndOffset });
+      }
+      await this.cursors.rememberEventKeys(sessionHash, unseenEvents.map((event) => event.eventKey));
+      return result;
+    });
+    if (queued.queued === 0) return { queued: 0, acknowledged: 0 };
+    const replay = await this.replay();
+    return { queued: queued.queued, acknowledged: replay.acknowledged };
+  }
+
+  async enqueueEvent(hostSessionId, event) {
+    return this.enqueueEvents(hostSessionId, [event]);
+  }
+
+  async enqueueEvents(hostSessionId, events) {
+    const sessionHash = this.sessionHash(hostSessionId);
+    await withFileLock(this.operationLockPath, async () => {
+      const cursor = await this.cursors.get(sessionHash);
+      const recentEventKeys = new Set(Array.isArray(cursor.recentEventKeys) ? cursor.recentEventKeys : []);
+      const unseenEvents = events.filter((event) => !recentEventKeys.has(event.eventKey));
+      if (unseenEvents.length === 0) return;
+      await this.queue.enqueueSessionEvents(sessionHash, unseenEvents, {
+        maxBatchEvents: this.maxBatchEvents,
+        maxBatchBytes: this.maxBatchBytes,
+        acknowledgedSequence: cursor.sequence,
+      });
+      await this.cursors.rememberEventKeys(sessionHash, unseenEvents.map((event) => event.eventKey));
+    });
+    return this.replay();
+  }
+
+  async replay() {
+    return withFileLock(this.operationLockPath, () => this.#replayUnlocked());
+  }
+
+  async #replayUnlocked() {
+    let acknowledged = 0;
+    while (true) {
+      const head = await this.queue.peek();
+      if (!head) break;
+      const sessionId = await this.resolveSessionByHash(head.sessionHash);
+      const response = await this.transport.appendEvents(sessionId, head.events.map(({
+        sourceEndOffset,
+        eventKey,
+        payloadSha256,
+        ...event
+      }) => ({ ...event, eventId: eventKey })));
+      const accepted = Math.max(0, Math.min(
+        head.events.length,
+        Number(response?.acceptedCount ?? response?.acceptedPrefix ??
+          (response?.accepted === undefined ? head.events.length : Number(response.accepted) + Number(response.duplicates ?? 0))),
+      ));
+      if (accepted === 0) {
+        if (Number.isSafeInteger(response?.nextExpectedSequence)) {
+          const expected = response.nextExpectedSequence;
+          const firstExpected = head.events.findIndex((event) => event.sequence >= expected);
+          if (firstExpected > 0) {
+            await this.#acknowledge(head, firstExpected);
+            acknowledged += firstExpected;
+            continue;
+          }
+        }
+        break;
+      }
+      await this.#acknowledge(head, accepted);
+      acknowledged += accepted;
+    }
+    return { acknowledged, ...(await this.queue.diagnostics()) };
+  }
+
+  async #acknowledge(head, accepted) {
+    const acceptedEvents = head.events.slice(0, accepted);
+    const last = acceptedEvents.at(-1);
+    const cursor = await this.cursors.get(head.sessionHash);
+    await this.cursors.update(head.sessionHash, {
+      sequence: Math.max(cursor.sequence, last.sequence),
+      ...(last.sourceEndOffset ? { byteOffset: Math.max(cursor.byteOffset, last.sourceEndOffset) } : {}),
+    });
+    const suffix = head.events.slice(accepted);
+    const suffixId = suffix.length ? createHash("sha256")
+      .update(`${head.sessionHash}\0${suffix.map((event) => event.eventKey).join("\0")}`)
+      .digest("hex") : null;
+    await this.queue.replaceHead(suffix.length ? { ...head, events: suffix, id: suffixId } : null);
+  }
+
+  async commit(hostSessionId, reason, throughSequence) {
+    const sessionHash = this.sessionHash(hostSessionId);
+    const cursor = await this.cursors.get(sessionHash);
+    const target = throughSequence ?? cursor.sequence;
+    if (target <= cursor.committedSequence) return { skipped: true, throughSequence: target };
+    const sessionId = await this.resolveSessionByHash(sessionHash);
+    const result = await this.transport.commit(sessionId, target, reason);
+    await this.cursors.update(sessionHash, { committedSequence: target });
+    return result;
+  }
+
+  async commitIfThreshold(hostSessionId, reason = "threshold") {
+    const cursor = await this.cursors.get(this.sessionHash(hostSessionId));
+    if (cursor.sequence - cursor.committedSequence < this.commitThreshold) return { skipped: true };
+    return this.commit(hostSessionId, reason);
+  }
+
+  async close(hostSessionId, reason = "session_end") {
+    return withFileLock(this.operationLockPath, async () => {
+      await this.#replayUnlocked();
+      const sessionHash = this.sessionHash(hostSessionId);
+      const cursor = await this.cursors.get(sessionHash);
+      await this.commit(hostSessionId, reason, cursor.sequence);
+      // Refresh the server's content-free queue evidence after replay. Session
+      // completeness is computed from both the final acknowledged sequence and
+      // these independently reported queue diagnostics.
+      await this.heartbeat(this.connection.capabilities || {});
+      return this.transport.close(await this.resolveSessionByHash(sessionHash), {
+        closedThroughSequence: cursor.sequence,
+      });
+    });
+  }
+
+  async heartbeat(capabilities) {
+    const queue = await this.queue.diagnostics();
+    return this.transport.heartbeat(capabilities, {
+      pluginVersion: this.connection.pluginVersion || "0.2.0-local",
+      proofStorage: this.connection.proofStorage || "unknown",
+      diagnostics: {
+        queueDepth: queue.depth,
+        oldestPendingAt: queue.oldestPendingAt,
+        expiredCount: queue.expiredCount,
+      },
+    });
+  }
+}
+
+export function newLocalEventId() {
+  return randomBytes(16).toString("base64url");
+}