@halofy/agent-connect 0.5.1 → 0.7.0

package/src/transcript-drivers/shared.mjs

@@ -0,0 +1,104 @@
+import { open, realpath } from "node:fs/promises";
+import { resolve, sep } from "node:path";
+
+// Windowed suffix budget per catch-up call. Successive calls drain the
+// remainder; nothing is skipped, memory stays bounded even for giant files.
+export const MAX_DRIVER_SUFFIX_BYTES = 8 * 1024 * 1024;
+
+// Host session ids are interpolated into filesystem lookups. Anything with a
+// path character is refused outright — no capture beats a contained read of
+// the wrong file (README containment commitment).
+const HOST_SESSION_ID_PATTERN = /^[A-Za-z0-9_-]{1,128}$/;
+
+export function boundedHostSessionId(value) {
+  const text = String(value ?? "");
+  return HOST_SESSION_ID_PATTERN.test(text) ? text : null;
+}
+
+/**
+ * Resolve `candidate` and require it to live under `root` after every
+ * symlink is followed. Index files and cached paths are untrusted input;
+ * any escape resolves to null (no capture), never an error.
+ */
+export async function containedPath(root, candidate) {
+  try {
+    const realRoot = await realpath(root);
+    const resolved = resolve(realRoot, String(candidate ?? ""));
+    if (resolved !== realRoot && !resolved.startsWith(realRoot + sep)) return null;
+    const real = await realpath(resolved);
+    if (real !== realRoot && !real.startsWith(realRoot + sep)) return null;
+    return real;
+  } catch {
+    return null;
+  }
+}
+
+/** Positioned read of at most `maxBytes` starting at `byteOffset`. */
+export async function readSuffixWindow(path, byteOffset, maxBytes = MAX_DRIVER_SUFFIX_BYTES) {
+  const handle = await open(path, "r");
+  try {
+    const size = (await handle.stat()).size;
+    const start = Number.isSafeInteger(byteOffset) && byteOffset >= 0 && byteOffset <= size
+      ? byteOffset : 0;
+    const length = Math.min(size - start, maxBytes);
+    const buffer = Buffer.alloc(length);
+    if (length > 0) await handle.read(buffer, 0, length, start);
+    return { buffer, start };
+  } finally {
+    await handle.close();
+  }
+}
+
+/**
+ * Yield `{ entry, byteOffset, endOffset }` for every complete JSONL line in
+ * the window. An unparseable line yields `entry: null` (drivers skip it —
+ * unlike the Claude archive, an ignored line is the norm for selective
+ * usage/metadata readers). A trailing record without its newline is left
+ * unread for the next catch-up.
+ */
+export function* completeJsonlLines(buffer, start) {
+  let position = 0;
+  while (position < buffer.length) {
+    const newline = buffer.indexOf(0x0a, position);
+    if (newline === -1) break;
+    let entry = null;
+    try {
+      const parsed = JSON.parse(buffer.subarray(position, newline).toString("utf8"));
+      entry = parsed !== null && typeof parsed === "object" ? parsed : null;
+    } catch {
+      entry = null;
+    }
+    yield { entry, byteOffset: start + position, endOffset: start + newline + 1 };
+    position = newline + 1;
+  }
+}
+
+/**
+ * End offset for a drained window. If a full window held no newline at all
+ * (pathological single-line file), advance past it rather than re-reading the
+ * same bytes forever — usage lines are tiny, so nothing real is lost.
+ */
+export function drainedEndOffset(lastEndOffset, start, bufferLength, maxBytes) {
+  if (lastEndOffset > start) return lastEndOffset;
+  if (bufferLength >= maxBytes) return start + bufferLength;
+  return start;
+}
+
+const MAX_HOST_STATE_BYTES = 1024;
+
+/** Bound the per-session driver scratch state persisted on the cursor. */
+export function boundedHostState(value) {
+  if (value === null || typeof value !== "object") return undefined;
+  const serialized = JSON.stringify(value);
+  return Buffer.byteLength(serialized, "utf8") <= MAX_HOST_STATE_BYTES ? value : undefined;
+}
+
+/**
+ * Bound for host-supplied metadata strings, mirroring collectClaudeMetadata:
+ * non-empty, capped, and free of control characters. The server rejects a
+ * whole batch over an oversized field, so bounding here is not cosmetic.
+ */
+export function boundedMetadataText(value, max) {
+  return typeof value === "string" && value.length > 0 && value.length <= max &&
+    !/[\u0000-\u001f\u007f]/.test(value) ? value : undefined;
+}

package/src/transport.mjs

@@ -64,6 +64,13 @@ export class SignedRuntimeTransport {
     });
   }
 
+  /** Badge skill check-in beacon: exactly the installed {skillId, sha} pairs (D39). */
+  skillsCheckin(items) { return this.request("/v1/agent-runtime/skills/checkin", { body: { items } }); }
+  /** Governed skill export — the same gate as a console download (D38). */
+  skillDownload(skillId) {
+    return this.request(`/v1/agent-runtime/skills/${encodeURIComponent(skillId)}/download`, { method: "GET" });
+  }
+
   openSession(body) { return this.request("/v1/agent-sessions/open", { body }); }
   appendEvents(sessionId, events) { return this.request(`/v1/agent-sessions/${encodeURIComponent(sessionId)}/events`, { body: { events } }); }
   recall(sessionId, body) { return this.request(`/v1/agent-sessions/${encodeURIComponent(sessionId)}/recall`, { body }); }

package/src/version.mjs

@@ -1,4 +1,4 @@
 export const PACKAGE_NAME = "@halofy/agent-connect";
-export const INSTALLER_VERSION = "0.5.1";
-export const RUNTIME_VERSION = "0.5.1";
-export const DISCLOSURE_VERSION = "halofy-agent-lifecycle-2026-08-31.1";
+export const INSTALLER_VERSION = "0.7.0";
+export const RUNTIME_VERSION = "0.7.0";
+export const DISCLOSURE_VERSION = "halofy-agent-lifecycle-2026-09-03.1";