@byok-sdk/client 0.9.0 → 0.10.0

package/dist/agent-memory/index.js

@@ -0,0 +1,762 @@
+import { randomUUID, createHash } from 'crypto';
+import { constants, existsSync, promises } from 'fs';
+import path2 from 'path';
+import '@byok-sdk/protocol';
+import { spawn } from 'child_process';
+import { createInterface } from 'readline';
+
+// src/daemon/agent-memory.ts
+var AGENT_HOME_INTERNAL_DIRECTORY = ".byok";
+
+// src/daemon/agent-memory.ts
+var AGENT_MEMORY_AUDIT_FILENAME = "agent-memory-audit-v1.jsonl";
+var AGENT_MEMORY_MAX_FILE_BYTES = 256 * 1024;
+var AGENT_MEMORY_MAX_SNAPSHOT_BYTES = 1024 * 1024;
+var AGENT_MEMORY_MAX_SNAPSHOT_FILES = 128;
+var AGENT_MEMORY_MAX_SNAPSHOT_ENTRIES = 512;
+var AGENT_MEMORY_MAX_LOCAL_LOG_BYTES = AGENT_MEMORY_MAX_SNAPSHOT_BYTES;
+var REVISION = /^sha256:[a-f0-9]{64}$/u;
+var SAFE_SEGMENT = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u;
+var SECRET_LIKE = /(?:^|[-_.])(secret|token|credential|password|passwd|api[-_]?key|private[-_]?key|cookie)(?:$|[-_.])/iu;
+var encoder = new TextEncoder();
+var AgentMemoryError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "AgentMemoryError";
+  }
+};
+var AgentMemoryRevisionConflictError = class extends AgentMemoryError {
+  constructor(expectedRevision, actualRevision) {
+    super(`Agent memory revision conflict: expected ${expectedRevision}, current ${actualRevision}`);
+    this.expectedRevision = expectedRevision;
+    this.actualRevision = actualRevision;
+    this.name = "AgentMemoryRevisionConflictError";
+  }
+  expectedRevision;
+  actualRevision;
+};
+function digestBytes(content) {
+  return `sha256:${createHash("sha256").update(content).digest("hex")}`;
+}
+function digest(content) {
+  return digestBytes(encoder.encode(content));
+}
+function nonEmpty(value) {
+  return typeof value === "string" && value.length > 0 && !/[\u0000\r\n]/u.test(value);
+}
+function revision(value) {
+  return typeof value === "string" && REVISION.test(value);
+}
+function taskContext(value) {
+  if (!value || !nonEmpty(value.taskId) || !nonEmpty(value.tenantId) || !nonEmpty(value.deviceId) || !nonEmpty(value.sessionRef) || !nonEmpty(value.runtimeId) || !nonEmpty(value.leaseId) || !value.agentRef || !nonEmpty(value.agentRef.agentId) || !nonEmpty(value.agentRef.profileRevision) || !path2.isAbsolute(value.canonicalHome) || typeof value.homeIdentity?.dev !== "bigint" || typeof value.homeIdentity.ino !== "bigint") {
+    throw new AgentMemoryError("Agent memory requires an exact active Agent task context");
+  }
+  return Object.freeze({ ...value, agentRef: Object.freeze({ ...value.agentRef }), homeIdentity: Object.freeze({ ...value.homeIdentity }), canonicalHome: path2.resolve(value.canonicalHome) });
+}
+function validateAgentMemoryPath(value) {
+  if (typeof value !== "string" || value.length === 0 || value.length > 1024 || /[\u0000\\]/u.test(value)) throw new AgentMemoryError("memory path is invalid");
+  if (value === "MEMORY.md") return value;
+  if (path2.posix.isAbsolute(value) || /[*?\[{]/u.test(value)) throw new AgentMemoryError("memory path must name exactly one file");
+  const parts = value.split("/");
+  if (parts.length < 2 || parts[0] !== "notes" || !value.endsWith(".md") || parts.some((part) => part === "" || part === "." || part === ".." || part === ".byok" || !SAFE_SEGMENT.test(part) || SECRET_LIKE.test(part))) {
+    throw new AgentMemoryError("memory path must be MEMORY.md or notes/<safe-relative>.md");
+  }
+  return value;
+}
+var SECURE_DIRECTORY_DESCRIPTOR_ROOT = "/proc/self/fd";
+function isAgentMemorySecureFilesystemAvailable(externalHelperConfigured = false) {
+  const nativeLinux = process.platform === "linux" && typeof constants.O_NOFOLLOW === "number" && typeof constants.O_DIRECTORY === "number" && typeof constants.O_NONBLOCK === "number" && existsSync(SECURE_DIRECTORY_DESCRIPTOR_ROOT);
+  return nativeLinux || externalHelperConfigured && process.platform === "darwin";
+}
+function requireSecureDirectoryDescriptors() {
+  if (!isAgentMemorySecureFilesystemAvailable(false) || process.platform !== "linux") {
+    throw new AgentMemoryError("Agent memory is unavailable because this Node platform lacks safe descriptor-relative filesystem operations");
+  }
+  return SECURE_DIRECTORY_DESCRIPTOR_ROOT;
+}
+function noFollowFlags(base) {
+  requireSecureDirectoryDescriptors();
+  return base | constants.O_NOFOLLOW;
+}
+function descriptorPath(handle) {
+  return `${requireSecureDirectoryDescriptors()}/${handle.fd}`;
+}
+async function openPinnedDirectory(target, expectedIdentity) {
+  requireSecureDirectoryDescriptors();
+  let handle;
+  try {
+    handle = await promises.open(target, noFollowFlags(constants.O_RDONLY | constants.O_DIRECTORY));
+    const stat = await handle.stat({ bigint: true });
+    if (!stat.isDirectory() || stat.isSymbolicLink() || expectedIdentity !== void 0 && (stat.dev !== expectedIdentity.dev || stat.ino !== expectedIdentity.ino)) throw new AgentMemoryError("memory directory is not a real directory");
+    return handle;
+  } catch (error) {
+    await handle?.close().catch(() => {
+    });
+    if (error instanceof AgentMemoryError) throw error;
+    throw new AgentMemoryError("memory directory is unavailable or unsafe");
+  }
+}
+async function withPinnedDirectory(home, parts, operation, expectedHomeIdentity) {
+  const handles = [];
+  try {
+    let directory = await openPinnedDirectory(home, expectedHomeIdentity);
+    handles.push(directory);
+    for (const part of parts) {
+      directory = await openPinnedDirectory(`${descriptorPath(directory)}/${part}`);
+      handles.push(directory);
+    }
+    return await operation(directory);
+  } finally {
+    await Promise.all(handles.reverse().map((handle) => handle.close().catch(() => {
+    })));
+  }
+}
+async function withMemoryParent(context, relativePath, operation) {
+  const parts = relativePath.split("/");
+  const fileName = parts.pop();
+  if (fileName === void 0 || parts.some((part) => !SAFE_SEGMENT.test(part) && part !== ".byok")) throw new AgentMemoryError("memory path is invalid");
+  return withPinnedDirectory(context.canonicalHome, parts, (directory) => operation(directory, fileName), context.homeIdentity);
+}
+async function readPinnedFile(directory, fileName, maxBytes = AGENT_MEMORY_MAX_FILE_BYTES) {
+  let handle;
+  try {
+    handle = await promises.open(
+      `${descriptorPath(directory)}/${fileName}`,
+      noFollowFlags(constants.O_RDONLY | constants.O_NONBLOCK)
+    );
+  } catch (error) {
+    if (error.code === "ENOENT") return Object.freeze({ exists: false, content: "", revision: digest(""), byteCount: 0 });
+    throw new AgentMemoryError("could not open memory file");
+  }
+  try {
+    const before = await handle.stat({ bigint: true });
+    if (!before.isFile() || before.isSymbolicLink() || before.size > BigInt(maxBytes)) throw new AgentMemoryError("memory file is not a bounded regular file");
+    const bytes = Buffer.alloc(Number(before.size));
+    let offset = 0;
+    while (offset < bytes.length) {
+      const read = await handle.read(bytes, offset, bytes.length - offset, offset);
+      if (read.bytesRead === 0) break;
+      offset += read.bytesRead;
+    }
+    const after = await handle.stat({ bigint: true });
+    if (offset !== bytes.length || after.size !== before.size || after.mtimeNs !== before.mtimeNs || after.ino !== before.ino) throw new AgentMemoryError("memory file changed during read");
+    const content = bytes.toString("utf8");
+    if (!Buffer.from(content, "utf8").equals(bytes)) throw new AgentMemoryError("memory file is not valid UTF-8");
+    return Object.freeze({ exists: true, content, revision: digestBytes(bytes), byteCount: bytes.length });
+  } finally {
+    await handle.close().catch(() => {
+    });
+  }
+}
+async function readFile(context, relativePath, maxBytes = AGENT_MEMORY_MAX_FILE_BYTES) {
+  if (context.filesystem !== void 0) return context.filesystem.read(relativePath, maxBytes);
+  return withMemoryParent(context, relativePath, (directory, fileName) => readPinnedFile(directory, fileName, maxBytes));
+}
+async function syncDirectory(directory) {
+  try {
+    await directory.sync();
+  } catch (error) {
+    if (!["EINVAL", "EPERM"].includes(error.code ?? "")) throw error;
+  }
+}
+async function replaceNative(context, relativePath, expected, content) {
+  const byteCount = encoder.encode(content).byteLength;
+  if (byteCount > AGENT_MEMORY_MAX_FILE_BYTES) throw new AgentMemoryError("memory content exceeds its bounded file size");
+  return withMemoryParent(context, relativePath, async (directory, fileName) => {
+    const before = await readPinnedFile(directory, fileName);
+    if (before.revision !== expected) throw new AgentMemoryRevisionConflictError(expected, before.revision);
+    const parent = descriptorPath(directory);
+    const temporary = `${parent}/.byok-memory-${randomUUID()}.tmp`;
+    let handle;
+    try {
+      const check = await readPinnedFile(directory, fileName);
+      if (check.revision !== expected || check.exists !== before.exists) throw new AgentMemoryRevisionConflictError(expected, check.revision);
+      handle = await promises.open(temporary, noFollowFlags(constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL), 384);
+      await handle.writeFile(content, "utf8");
+      await handle.sync();
+      await handle.close();
+      handle = void 0;
+      const finalCheck = await readPinnedFile(directory, fileName);
+      if (finalCheck.revision !== expected || finalCheck.exists !== before.exists) throw new AgentMemoryRevisionConflictError(expected, finalCheck.revision);
+      await promises.rename(temporary, `${parent}/${fileName}`);
+      await syncDirectory(directory);
+      return Object.freeze({ exists: true, content, revision: digest(content), byteCount });
+    } catch (error) {
+      await handle?.close().catch(() => {
+      });
+      await promises.rm(temporary, { force: true }).catch(() => {
+      });
+      if (error instanceof AgentMemoryError) throw error;
+      throw new AgentMemoryError("could not atomically replace memory file");
+    }
+  });
+}
+async function replace(context, relativePath, expected, content) {
+  if (context.filesystem !== void 0) return context.filesystem.replace(relativePath, expected, content, AGENT_MEMORY_MAX_FILE_BYTES);
+  return replaceNative(context, relativePath, expected, content);
+}
+async function removeNative(context, relativePath, expected) {
+  if (relativePath === "MEMORY.md") throw new AgentMemoryError("MEMORY.md may not be deleted");
+  await withMemoryParent(context, relativePath, async (directory, fileName) => {
+    const before = await readPinnedFile(directory, fileName);
+    if (!before.exists || before.revision !== expected) throw new AgentMemoryRevisionConflictError(expected, before.revision);
+    const parent = descriptorPath(directory);
+    const tombstone = `${parent}/.byok-memory-delete-${randomUUID()}.tmp`;
+    try {
+      const check = await readPinnedFile(directory, fileName);
+      if (!check.exists || check.revision !== expected) throw new AgentMemoryRevisionConflictError(expected, check.revision);
+      await promises.rename(`${parent}/${fileName}`, tombstone);
+      await syncDirectory(directory);
+      await promises.rm(tombstone);
+      await syncDirectory(directory);
+    } catch (error) {
+      if (error instanceof AgentMemoryError) throw error;
+      throw new AgentMemoryError("could not atomically delete memory file");
+    }
+  });
+}
+async function remove(context, relativePath, expected) {
+  if (relativePath === "MEMORY.md") throw new AgentMemoryError("MEMORY.md may not be deleted");
+  if (context.filesystem !== void 0) return context.filesystem.delete(relativePath, expected);
+  return removeNative(context, relativePath, expected);
+}
+async function readInternalFile(context, fileName) {
+  const relativePath = `${AGENT_HOME_INTERNAL_DIRECTORY}/${fileName}`;
+  if (context.filesystem !== void 0) return context.filesystem.read(relativePath, AGENT_MEMORY_MAX_LOCAL_LOG_BYTES);
+  return withPinnedDirectory(
+    context.canonicalHome,
+    [AGENT_HOME_INTERNAL_DIRECTORY],
+    (directory) => readPinnedFile(directory, fileName, AGENT_MEMORY_MAX_LOCAL_LOG_BYTES),
+    context.homeIdentity
+  );
+}
+async function replaceInternalFile(context, fileName, expectedRevision, content) {
+  const byteCount = encoder.encode(content).byteLength;
+  if (byteCount > AGENT_MEMORY_MAX_LOCAL_LOG_BYTES) throw new AgentMemoryError("Agent memory internal state exceeds its bounded size");
+  const relativePath = `${AGENT_HOME_INTERNAL_DIRECTORY}/${fileName}`;
+  if (context.filesystem !== void 0) return context.filesystem.replace(relativePath, expectedRevision, content, AGENT_MEMORY_MAX_LOCAL_LOG_BYTES);
+  return withPinnedDirectory(context.canonicalHome, [AGENT_HOME_INTERNAL_DIRECTORY], async (directory) => {
+    const before = await readPinnedFile(directory, fileName, AGENT_MEMORY_MAX_LOCAL_LOG_BYTES);
+    if (before.revision !== expectedRevision) throw new AgentMemoryRevisionConflictError(expectedRevision, before.revision);
+    const parent = descriptorPath(directory);
+    const temporary = `${parent}/.byok-agent-memory-${randomUUID()}.tmp`;
+    let handle;
+    try {
+      handle = await promises.open(temporary, noFollowFlags(constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL), 384);
+      await handle.writeFile(content, "utf8");
+      await handle.sync();
+      await handle.close();
+      handle = void 0;
+      const check = await readPinnedFile(directory, fileName, AGENT_MEMORY_MAX_LOCAL_LOG_BYTES);
+      if (check.revision !== expectedRevision || check.exists !== before.exists) throw new AgentMemoryRevisionConflictError(expectedRevision, check.revision);
+      await promises.rename(temporary, `${parent}/${fileName}`);
+      await syncDirectory(directory);
+      return Object.freeze({ exists: true, content, revision: digest(content), byteCount });
+    } catch (error) {
+      await handle?.close().catch(() => {
+      });
+      await promises.rm(temporary, { force: true }).catch(() => {
+      });
+      if (error instanceof AgentMemoryError) throw error;
+      throw new AgentMemoryError("could not atomically replace Agent memory internal state");
+    }
+  }, context.homeIdentity);
+}
+function boundedAuditTail(previous, entry) {
+  if (encoder.encode(entry).byteLength > AGENT_MEMORY_MAX_LOCAL_LOG_BYTES) throw new AgentMemoryError("Agent memory audit entry exceeds its bounded size");
+  const lines = previous.split("\n").filter((line) => line.length > 0);
+  const kept = [entry];
+  let byteCount = encoder.encode(entry).byteLength;
+  for (let index = lines.length - 1; index >= 0; index -= 1) {
+    const candidate = `${lines[index]}
+`;
+    const candidateBytes = encoder.encode(candidate).byteLength;
+    if (byteCount + candidateBytes > AGENT_MEMORY_MAX_LOCAL_LOG_BYTES) break;
+    kept.unshift(candidate);
+    byteCount += candidateBytes;
+  }
+  return kept.join("");
+}
+async function audit(context, kind, values) {
+  const entry = `${JSON.stringify({ version: 1, kind, taskId: context.taskId, tenantId: context.tenantId, deviceId: context.deviceId, agentRef: context.agentRef, sessionRef: context.sessionRef, runtimeId: context.runtimeId, ...values, recordedAt: (/* @__PURE__ */ new Date()).toISOString() })}
+`;
+  const current = await readInternalFile(context, AGENT_MEMORY_AUDIT_FILENAME);
+  await replaceInternalFile(context, AGENT_MEMORY_AUDIT_FILENAME, current.revision, boundedAuditTail(current.content, entry));
+}
+async function recordAuditWarning(context, kind, values) {
+  try {
+    await audit(context, kind, values);
+    return void 0;
+  } catch {
+    return Object.freeze({ code: "agent_memory_audit_unavailable" });
+  }
+}
+var agentMemoryHomeQueues = /* @__PURE__ */ new Map();
+async function exclusiveAgentMemoryHome(home, fn) {
+  const previous = agentMemoryHomeQueues.get(home) ?? Promise.resolve();
+  let release;
+  const next = new Promise((resolve) => {
+    release = resolve;
+  });
+  agentMemoryHomeQueues.set(home, next);
+  await previous;
+  try {
+    return await fn();
+  } finally {
+    release();
+    if (agentMemoryHomeQueues.get(home) === next) agentMemoryHomeQueues.delete(home);
+  }
+}
+var AgentMemoryService = class {
+  constructor(input) {
+    this.input = input;
+  }
+  input;
+  async recall(input) {
+    const context = taskContext(this.input);
+    const relativePath = validateAgentMemoryPath(input.path);
+    if (input.ifRevision !== void 0 && !revision(input.ifRevision)) throw new AgentMemoryError("ifRevision must be a sha256 content revision");
+    const current = await readFile(context, relativePath);
+    if (!current.exists) throw new AgentMemoryError("memory file does not exist");
+    if (input.ifRevision !== void 0 && current.revision !== input.ifRevision) throw new AgentMemoryRevisionConflictError(input.ifRevision, current.revision);
+    const auditWarning = await exclusiveAgentMemoryHome(context.canonicalHome, () => recordAuditWarning(context, "recall", {
+      path: relativePath,
+      revision: current.revision,
+      byteCount: current.byteCount
+    }));
+    return Object.freeze({
+      path: relativePath,
+      revision: current.revision,
+      content: current.content,
+      ...auditWarning === void 0 ? {} : { auditWarning }
+    });
+  }
+  async save(input) {
+    const context = taskContext(this.input);
+    const relativePath = validateAgentMemoryPath(input.path);
+    if (input.op !== "replace" && input.op !== "delete" || !revision(input.expectedRevision)) throw new AgentMemoryError("memory save requires op and sha256 expectedRevision");
+    if (input.op === "replace" && typeof input.content !== "string") throw new AgentMemoryError("replace requires string content");
+    if (input.op === "delete" && input.content !== void 0) throw new AgentMemoryError("delete does not accept content");
+    const expectedRevision = input.expectedRevision;
+    const content = input.content;
+    return exclusiveAgentMemoryHome(context.canonicalHome, async () => {
+      if (input.op === "delete") {
+        await remove(context, relativePath, expectedRevision);
+        const auditWarning2 = await recordAuditWarning(context, "save", { path: relativePath, operation: "delete" });
+        return Object.freeze({ path: relativePath, deleted: true, ...auditWarning2 === void 0 ? {} : { auditWarning: auditWarning2 } });
+      }
+      if (typeof content !== "string") throw new AgentMemoryError("replace requires string content");
+      const current = await replace(context, relativePath, expectedRevision, content);
+      const auditWarning = await recordAuditWarning(context, "save", { path: relativePath, operation: "replace", revision: current.revision, byteCount: current.byteCount });
+      return Object.freeze({ path: relativePath, revision: current.revision, deleted: false, ...auditWarning === void 0 ? {} : { auditWarning } });
+    });
+  }
+};
+async function memoryNotePaths(context) {
+  if (context.filesystem !== void 0) {
+    const paths = await context.filesystem.walk("notes", AGENT_MEMORY_MAX_SNAPSHOT_ENTRIES);
+    const candidates2 = [];
+    for (const candidate of paths) {
+      try {
+        candidates2.push(validateAgentMemoryPath(candidate));
+      } catch {
+      }
+    }
+    return Object.freeze(candidates2);
+  }
+  const candidates = [];
+  let entriesSeen = 0;
+  async function walk(directory, relativeDirectory) {
+    const entries = await promises.readdir(descriptorPath(directory), { withFileTypes: true });
+    for (const entry of entries) {
+      entriesSeen += 1;
+      if (entriesSeen > AGENT_MEMORY_MAX_SNAPSHOT_ENTRIES) throw new AgentMemoryError("memory snapshot exceeds bounded directory entries");
+      const candidate = `${relativeDirectory}/${entry.name}`;
+      if (entry.isSymbolicLink()) throw new AgentMemoryError("memory notes contains a symlink");
+      if (entry.isDirectory()) {
+        if (SAFE_SEGMENT.test(entry.name) && !SECRET_LIKE.test(entry.name) && entry.name !== ".byok") {
+          const nested = await openPinnedDirectory(`${descriptorPath(directory)}/${entry.name}`);
+          try {
+            await walk(nested, candidate);
+          } finally {
+            await nested.close().catch(() => {
+            });
+          }
+        }
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      try {
+        candidates.push(validateAgentMemoryPath(candidate));
+      } catch {
+      }
+    }
+  }
+  await withPinnedDirectory(context.canonicalHome, ["notes"], (directory) => walk(directory, "notes"), context.homeIdentity);
+  return Object.freeze(candidates);
+}
+async function captureAgentMemorySnapshot(input) {
+  const context = taskContext(input);
+  const candidates = ["MEMORY.md", ...await memoryNotePaths(context)];
+  const paths = [...new Set(candidates)].sort((a, b) => a.localeCompare(b));
+  if (paths.length > AGENT_MEMORY_MAX_SNAPSHOT_FILES) throw new AgentMemoryError("memory snapshot exceeds bounded file count");
+  const files = [];
+  let totalBytes = 0;
+  for (const relativePath of paths) {
+    const current = await readFile(context, relativePath);
+    if (!current.exists) {
+      if (relativePath === "MEMORY.md") throw new AgentMemoryError("MEMORY.md disappeared before snapshot");
+      continue;
+    }
+    totalBytes += current.byteCount;
+    if (totalBytes > AGENT_MEMORY_MAX_SNAPSHOT_BYTES) throw new AgentMemoryError("memory snapshot exceeds bounded total size");
+    files.push(Object.freeze({ path: relativePath, revision: current.revision, byteCount: current.byteCount, content: current.content }));
+  }
+  const snapshot = Object.freeze({ files: Object.freeze(files), totalBytes });
+  await exclusiveAgentMemoryHome(context.canonicalHome, () => audit(context, "snapshot", {
+    files: files.map((file) => ({ path: file.path, revision: file.revision, byteCount: file.byteCount }))
+  }));
+  return snapshot;
+}
+var AGENT_MEMORY_FILESYSTEM_HELPER_PROTOCOL = 2;
+var AGENT_MEMORY_FILESYSTEM_HELPER_VERSION = "2";
+var HELPER_REQUEST_TIMEOUT_MS = 1e4;
+var HELPER_MAX_JSON_LINE_BYTES = 2 * 1024 * 1024;
+var HELPER_MAX_CONTENT_BYTES = 1 * 1024 * 1024;
+var HELPER_MAX_STDERR_BYTES = 4 * 1024;
+var HelperRevisionConflict = class extends Error {
+  constructor(actualRevision) {
+    super("helper revision conflict");
+    this.actualRevision = actualRevision;
+  }
+  actualRevision;
+};
+function safeHelperPath(value) {
+  if (typeof value !== "string" || !path2.isAbsolute(value) || value.length === 0 || /[\u0000\r\n]/u.test(value)) {
+    throw new AgentMemoryError("Agent memory filesystem helper must be an explicit absolute executable path");
+  }
+  return path2.resolve(value);
+}
+function helperPlatformSupported() {
+  return process.platform === "darwin";
+}
+function isAgentMemoryFilesystemHelperSupported() {
+  return helperPlatformSupported();
+}
+function unixIdentity(homeIdentity) {
+  return Object.freeze({ kind: "unix", dev: homeIdentity.dev.toString(10), ino: homeIdentity.ino.toString(10) });
+}
+function responseRecord(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return void 0;
+  const record2 = value;
+  if (typeof record2.id !== "string" || record2.protocol !== AGENT_MEMORY_FILESYSTEM_HELPER_PROTOCOL || typeof record2.ok !== "boolean") return void 0;
+  if (record2.ok) {
+    if (record2.result === null || typeof record2.result !== "object" || Array.isArray(record2.result)) return void 0;
+    return record2;
+  }
+  if (record2.error === null || typeof record2.error !== "object" || Array.isArray(record2.error)) return void 0;
+  const error = record2.error;
+  if (typeof error.code !== "string" || typeof error.message !== "string" || error.actualRevision !== void 0 && typeof error.actualRevision !== "string") return void 0;
+  return record2;
+}
+function boundedFileState(result, maxBytes) {
+  let content;
+  try {
+    if (typeof result.contentBase64 !== "string" || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}|[A-Za-z0-9+/]{3})?$/u.test(result.contentBase64)) {
+      throw new Error("invalid base64");
+    }
+    content = Buffer.from(result.contentBase64, "base64").toString("utf8");
+  } catch {
+    throw new AgentMemoryError("Agent memory filesystem helper returned an invalid file state");
+  }
+  if (typeof result.exists !== "boolean" || typeof result.revision !== "string" || typeof result.byteCount !== "number" || !Number.isSafeInteger(result.byteCount) || result.byteCount < 0 || result.byteCount > maxBytes || Buffer.byteLength(content, "utf8") !== result.byteCount || !/^sha256:[a-f0-9]{64}$/u.test(result.revision)) {
+    throw new AgentMemoryError("Agent memory filesystem helper returned an invalid file state");
+  }
+  return Object.freeze({ exists: result.exists, content, revision: result.revision, byteCount: result.byteCount });
+}
+function encodeReplaceContent(content, maxBytes) {
+  if (!Number.isSafeInteger(maxBytes) || maxBytes < 0 || maxBytes > HELPER_MAX_CONTENT_BYTES) {
+    throw new AgentMemoryError("Agent memory filesystem helper requested an invalid byte limit");
+  }
+  const bytes = Buffer.from(content, "utf8");
+  if (bytes.byteLength > maxBytes) {
+    throw new AgentMemoryError("Agent memory filesystem helper replacement exceeds its requested byte limit");
+  }
+  return bytes.toString("base64").replace(/=+$/u, "");
+}
+var AgentMemoryFilesystemHelperClient = class _AgentMemoryFilesystemHelperClient {
+  constructor(child) {
+    this.child = child;
+    child.stdout.on("data", (chunk) => this.handleStdoutChunk(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)));
+    child.stderr.on("data", (chunk) => {
+      this.stderrBytes += Buffer.byteLength(chunk);
+      if (this.stderrBytes > HELPER_MAX_STDERR_BYTES) this.fail(new AgentMemoryError("Agent memory filesystem helper exceeded bounded stderr"));
+    });
+    child.stdin.on("error", () => this.fail(new AgentMemoryError("Agent memory filesystem helper request could not be written")));
+    child.once("error", () => this.fail(new AgentMemoryError("Agent memory filesystem helper could not be started")));
+    child.once("exit", (code, signal) => {
+      if (!this.closed || code !== 0) this.fail(new AgentMemoryError(`Agent memory filesystem helper exited unexpectedly (${code ?? signal ?? "unknown"})`));
+    });
+  }
+  child;
+  pending = /* @__PURE__ */ new Map();
+  stdoutBuffer = Buffer.alloc(0);
+  sequence = 0;
+  stderrBytes = 0;
+  closed = false;
+  fatalError;
+  static async open(input) {
+    if (!helperPlatformSupported()) throw new AgentMemoryError("Agent memory filesystem helper is not admitted on this platform");
+    const helperBin = safeHelperPath(input.helperBin);
+    const child = spawn(helperBin, ["serve"], {
+      stdio: ["pipe", "pipe", "pipe"],
+      shell: false,
+      windowsHide: true,
+      env: Object.freeze({})
+    });
+    const client = new _AgentMemoryFilesystemHelperClient(child);
+    try {
+      const result = await client.request("open", {
+        root: path2.resolve(input.canonicalHome),
+        expectedIdentity: unixIdentity(input.homeIdentity)
+      });
+      if (result.helperVersion !== AGENT_MEMORY_FILESYSTEM_HELPER_VERSION) throw new AgentMemoryError("Agent memory filesystem helper version mismatch");
+      const identity = result.identity;
+      if (identity === null || typeof identity !== "object" || Array.isArray(identity)) throw new AgentMemoryError("Agent memory filesystem helper omitted root identity");
+      const actual = identity;
+      const expected = unixIdentity(input.homeIdentity);
+      if (actual.kind !== expected.kind || actual.dev !== expected.dev || actual.ino !== expected.ino) throw new AgentMemoryError("Agent memory filesystem helper root identity mismatch");
+      return client;
+    } catch (error) {
+      await client.close().catch(() => {
+      });
+      throw error;
+    }
+  }
+  async read(relativePath, maxBytes) {
+    return boundedFileState(await this.request("read", { path: relativePath, maxBytes }), maxBytes);
+  }
+  async replace(relativePath, expectedRevision, content, maxBytes) {
+    try {
+      const contentBase64 = encodeReplaceContent(content, maxBytes);
+      return boundedFileState(await this.request("replace", { path: relativePath, expectedRevision, contentBase64, maxBytes }), maxBytes);
+    } catch (error) {
+      if (error instanceof HelperRevisionConflict) throw new AgentMemoryRevisionConflictError(expectedRevision, error.actualRevision);
+      throw error;
+    }
+  }
+  async delete(relativePath, expectedRevision) {
+    try {
+      await this.request("delete", { path: relativePath, expectedRevision });
+    } catch (error) {
+      if (error instanceof HelperRevisionConflict) throw new AgentMemoryRevisionConflictError(expectedRevision, error.actualRevision);
+      throw error;
+    }
+  }
+  async append(relativePath, content, maxBytes) {
+    await this.request("append", { path: relativePath, content, maxBytes });
+  }
+  async walk(relativePath, maxEntries) {
+    const result = await this.request("walk", { path: relativePath, maxEntries });
+    if (!Array.isArray(result.paths) || result.paths.length > maxEntries || result.paths.some((candidate) => typeof candidate !== "string")) {
+      throw new AgentMemoryError("Agent memory filesystem helper returned an invalid walk result");
+    }
+    return Object.freeze([...result.paths]);
+  }
+  async close() {
+    if (this.closed) return;
+    this.closed = true;
+    try {
+      if (this.child.exitCode === null && this.child.signalCode === null && this.fatalError === void 0) await this.requestWhileClosing("close", {});
+    } finally {
+      this.child.stdin.end();
+      if (this.child.exitCode === null && this.child.signalCode === null) this.child.kill();
+      this.rejectPending(new AgentMemoryError("Agent memory filesystem helper is closed"));
+    }
+  }
+  request(op, fields) {
+    if (this.closed) return Promise.reject(new AgentMemoryError("Agent memory filesystem helper is closed"));
+    return this.requestInternal(op, fields);
+  }
+  requestWhileClosing(op, fields) {
+    return this.requestInternal(op, fields);
+  }
+  requestInternal(op, fields) {
+    if (this.fatalError !== void 0) return Promise.reject(this.fatalError);
+    const id = `m${++this.sequence}`;
+    let line;
+    try {
+      line = `${JSON.stringify({ id, protocol: AGENT_MEMORY_FILESYSTEM_HELPER_PROTOCOL, op, ...fields })}
+`;
+    } catch {
+      return Promise.reject(new AgentMemoryError("Agent memory filesystem helper request could not be encoded"));
+    }
+    if (Buffer.byteLength(line, "utf8") > HELPER_MAX_JSON_LINE_BYTES) {
+      return Promise.reject(new AgentMemoryError("Agent memory filesystem helper request exceeded bounded stdin"));
+    }
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        const error = new AgentMemoryError("Agent memory filesystem helper request timed out");
+        reject(error);
+        this.fail(error);
+      }, HELPER_REQUEST_TIMEOUT_MS);
+      timer.unref?.();
+      this.pending.set(id, { resolve: (response) => resolve(response.result), reject, timer });
+      this.child.stdin.write(line, (error) => {
+        if (!error) return;
+        const item = this.pending.get(id);
+        if (item === void 0) return;
+        clearTimeout(item.timer);
+        this.pending.delete(id);
+        item.reject(new AgentMemoryError("Agent memory filesystem helper request could not be written"));
+      });
+    });
+  }
+  handleStdoutChunk(chunk) {
+    let offset = 0;
+    while (offset < chunk.length && this.fatalError === void 0) {
+      const newline = chunk.indexOf(10, offset);
+      const end = newline === -1 ? chunk.length : newline;
+      const segment = chunk.subarray(offset, end);
+      if (this.stdoutBuffer.length + segment.length > HELPER_MAX_JSON_LINE_BYTES) {
+        this.fail(new AgentMemoryError("Agent memory filesystem helper exceeded bounded stdout"));
+        return;
+      }
+      this.stdoutBuffer = this.stdoutBuffer.length === 0 ? Buffer.from(segment) : Buffer.concat([this.stdoutBuffer, segment]);
+      if (newline === -1) return;
+      const line = this.stdoutBuffer;
+      this.stdoutBuffer = Buffer.alloc(0);
+      this.handleLine(line);
+      offset = newline + 1;
+    }
+  }
+  handleLine(line) {
+    let parsed;
+    try {
+      parsed = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(line));
+    } catch {
+      this.fail(new AgentMemoryError("Agent memory filesystem helper returned malformed JSON"));
+      return;
+    }
+    const response = responseRecord(parsed);
+    if (response === void 0) {
+      this.fail(new AgentMemoryError("Agent memory filesystem helper returned an invalid response"));
+      return;
+    }
+    const item = this.pending.get(response.id);
+    if (item === void 0) {
+      this.fail(new AgentMemoryError("Agent memory filesystem helper returned an unsolicited response"));
+      return;
+    }
+    clearTimeout(item.timer);
+    this.pending.delete(response.id);
+    if (response.ok) {
+      item.resolve(response);
+      return;
+    }
+    if (response.error.code === "revision_conflict" && typeof response.error.actualRevision === "string") {
+      item.reject(new HelperRevisionConflict(response.error.actualRevision));
+      return;
+    }
+    item.reject(new AgentMemoryError(`Agent memory filesystem helper rejected the operation: ${response.error.code}`));
+  }
+  fail(error) {
+    if (this.fatalError !== void 0) return;
+    this.fatalError = error;
+    this.rejectPending(error);
+    if (this.child.exitCode === null && this.child.signalCode === null) this.child.kill();
+  }
+  rejectPending(error) {
+    for (const item of this.pending.values()) {
+      clearTimeout(item.timer);
+      item.reject(error);
+    }
+    this.pending.clear();
+  }
+};
+async function openAgentMemoryFilesystemHelper(input) {
+  return AgentMemoryFilesystemHelperClient.open(input);
+}
+var AGENT_MEMORY_RECALL_TOOL_NAME = "memory.recall";
+var AGENT_MEMORY_SAVE_TOOL_NAME = "memory.save";
+function record(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value : void 0;
+}
+function invalid(id, message) {
+  return { jsonrpc: "2.0", id, error: { code: -32602, message } };
+}
+function success(id, value) {
+  return { jsonrpc: "2.0", id, result: { content: [{ type: "text", text: JSON.stringify(value) }] } };
+}
+async function handleAgentMemoryMcpRequest(request, deps) {
+  const id = request.id;
+  if (request.method === "initialize") {
+    const params2 = record(request.params) ?? {};
+    return { jsonrpc: "2.0", id, result: { protocolVersion: typeof params2.protocolVersion === "string" ? params2.protocolVersion : "2024-11-05", capabilities: { tools: {} }, serverInfo: { name: "byok-agent-memory-mcp", version: "0.0.1" } } };
+  }
+  if (request.method === "notifications/initialized") return void 0;
+  if (request.method === "tools/list") return {
+    jsonrpc: "2.0",
+    id,
+    result: { tools: [
+      { name: AGENT_MEMORY_RECALL_TOOL_NAME, description: "Recall one SDK-owned memory file for this exact active Agent task. Identity and memory root are never model parameters.", inputSchema: { type: "object", additionalProperties: false, required: ["path"], properties: { path: { type: "string" }, ifRevision: { type: "string", pattern: "^sha256:[a-f0-9]{64}$" } } } },
+      { name: AGENT_MEMORY_SAVE_TOOL_NAME, description: "Atomically replace or delete one SDK-owned memory file with exact sha256 compare-and-swap.", inputSchema: { type: "object", additionalProperties: false, required: ["op", "path", "expectedRevision"], properties: { op: { type: "string", enum: ["replace", "delete"] }, path: { type: "string" }, expectedRevision: { type: "string", pattern: "^sha256:[a-f0-9]{64}$" }, content: { type: "string" } } } }
+    ] }
+  };
+  if (request.method !== "tools/call") return id === void 0 ? void 0 : { jsonrpc: "2.0", id, error: { code: -32601, message: `unknown method: ${String(request.method)}` } };
+  const params = record(request.params);
+  const args = record(params?.arguments);
+  if (!params || !args || typeof params.name !== "string") return invalid(id, "memory tool input must be an object");
+  try {
+    if (params.name === AGENT_MEMORY_RECALL_TOOL_NAME) {
+      if (Object.keys(args).some((key) => key !== "path" && key !== "ifRevision") || typeof args.path !== "string" || args.ifRevision !== void 0 && typeof args.ifRevision !== "string") return invalid(id, "memory.recall accepts only path and optional ifRevision");
+      return success(id, await deps.recall({ path: args.path, ...args.ifRevision === void 0 ? {} : { ifRevision: args.ifRevision } }));
+    }
+    if (params.name === AGENT_MEMORY_SAVE_TOOL_NAME) {
+      if (Object.keys(args).some((key) => key !== "op" && key !== "path" && key !== "expectedRevision" && key !== "content") || args.op !== "replace" && args.op !== "delete" || typeof args.path !== "string" || typeof args.expectedRevision !== "string" || args.op === "replace" && typeof args.content !== "string" || args.op === "delete" && args.content !== void 0) return invalid(id, "memory.save requires replace|delete, path, expectedRevision, and content only for replace");
+      const content = args.content;
+      return success(id, await deps.save({ op: args.op, path: args.path, expectedRevision: args.expectedRevision, ...typeof content === "string" ? { content } : {} }));
+    }
+    return invalid(id, "unknown Agent memory tool");
+  } catch (error) {
+    return { jsonrpc: "2.0", id, error: { code: -32e3, message: error instanceof Error ? error.message : String(error) } };
+  }
+}
+function serveAgentMemoryMcpOverStdio(input) {
+  const reader = createInterface({ input: input.stdin ?? process.stdin, terminal: false });
+  const output = input.stdout ?? process.stdout;
+  reader.on("line", (line) => {
+    const trimmed = line.trim();
+    if (!trimmed) return;
+    void (async () => {
+      let request;
+      try {
+        request = JSON.parse(trimmed);
+      } catch {
+        return;
+      }
+      const response = await handleAgentMemoryMcpRequest(request, input.deps);
+      if (response !== void 0) output.write(`${JSON.stringify(response)}
+`);
+    })();
+  });
+}
+
+// src/daemon/memory-guidance.ts
+var AGENT_MEMORY_GUIDANCE = [
+  "At the start of this Agent task, first read `MEMORY.md` in the provided `cwd`.",
+  "Treat `MEMORY.md` as a concise, self-contained recovery index; if it is empty, initialize a brief index from durable, non-secret task knowledge.",
+  "Read files under `notes/` only as needed, following pointers from the index.",
+  "When task permissions allow and a durable value is learned, update the relevant `notes/` entry and the `MEMORY.md` index.",
+  "Never write credentials, secrets, tokens, API keys, private keys, or other authentication material to `MEMORY.md` or `notes/`."
+].join("\n");
+function prependAgentMemoryGuidance(instruction) {
+  return `${AGENT_MEMORY_GUIDANCE}
+
+${instruction}`;
+}
+
+export { AGENT_MEMORY_GUIDANCE, AGENT_MEMORY_RECALL_TOOL_NAME, AGENT_MEMORY_SAVE_TOOL_NAME, AgentMemoryError, AgentMemoryRevisionConflictError, AgentMemoryService, captureAgentMemorySnapshot, isAgentMemoryFilesystemHelperSupported, isAgentMemorySecureFilesystemAvailable, openAgentMemoryFilesystemHelper, prependAgentMemoryGuidance, serveAgentMemoryMcpOverStdio, validateAgentMemoryPath };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map