@byok-sdk/client 0.8.0 → 0.9.0-rc.1

package/dist/agent-home.d.ts

@@ -48,7 +48,11 @@ export interface AgentHomeProjectionApplyInput extends AgentHomeProjectionInput
 export interface AgentHomeProjection {
     /** Optional creation/task-time host preparation retained as a distinct lifecycle. */
     prepare?(input: AgentHomeProjectionInput): void | Promise<void>;
-    /** Task-free opaque projection consumer. Its successful return means its own bytes are durable. */
+    /**
+     * Task-free opaque desired-state consumer. It must atomically and
+     * idempotently ensure its own durable bytes because exact revision/hash
+     * requests may replay after local derived-file loss or transport failure.
+     */
     apply?(input: AgentHomeProjectionApplyInput): void | Promise<void>;
 }
 export type AgentHomeProjectionFunction = (input: AgentHomeProjectionInput) => void | Promise<void>;
@@ -58,6 +62,11 @@ export interface AgentHomeLease {
     readonly agentRef: AgentRef;
     readonly canonicalHome: string;
     readonly cwd: string;
+    /** Filesystem identity captured under the writer lease; task-scoped memory rechecks it before pinning a descriptor. */
+    readonly homeIdentity: Readonly<{
+        dev: bigint;
+        ino: bigint;
+    }>;
     release(): Promise<void>;
 }
 export interface AgentHomeBinding {
@@ -82,7 +91,15 @@ export declare class AgentHomeLayout {
      * file is created by this preflight.
      */
     preflight(): Promise<void>;
+    /**
+     * Construction-time validation is deliberately non-mutating. The actual
+     * writable preflight runs asynchronously after daemon ownership is acquired
+     * and before transport/capability publication, where it can participate in
+     * the cross-process relocation gate without a sync shadow lock.
+     */
+    preflightSync(): void;
     private resolveRoot;
+    private acquireRootMutationGate;
 }
 export declare function stableAgentHomeOwnerId(storeDir: string, productId: string): string;
 /** One-writer lease backed by both a process registry and an exclusive marker. */
@@ -108,6 +125,8 @@ export declare class AgentHomeManager {
     prepare(agentRef: AgentRef): Promise<AgentHomeBinding>;
     /** Validate the configured root before capability publication. */
     preflight(): Promise<void>;
+    /** Synchronous construction-time preflight for strict Agent-only admission. */
+    preflightSync(): void;
     /** Resolve and lease without applying downstream projection side effects. */
     acquire(agentRef: AgentRef): Promise<AgentHomeBinding>;
     /** Initialize only after any requested session exact-match has succeeded. */
@@ -115,11 +134,17 @@ export declare class AgentHomeManager {
     supportsTaskFreeProjection(): boolean;
     /**
      * Apply one task-free projection under the same canonical-home writer lease
-     * used by Agent execution. Only a successful host hook followed by the
-     * SDK-owned fsynced ordering record can return `applied`.
+     * used by Agent execution. The host hook owns an atomic/idempotent ensure of
+     * its opaque product bytes, so an exact desired-state replay invokes it again
+     * before returning `idempotent`. Only a successful new-state hook followed
+     * by the SDK-owned fsynced ordering record can return `applied`.
      */
     project(input: AgentHomeProjectionPayload): Promise<AgentHomeProjectionOutcome>;
 }
 export declare function createAgentHomeProjection(prepare: AgentHomeProjectionFunction): AgentHomeProjection;
-/** Create only the task-free opaque projection consumer; no task-time fallback is inferred. */
+/**
+ * Create the task-free atomic/idempotent opaque desired-state consumer.
+ * Exact revision/hash delivery may invoke it again before an idempotent receipt;
+ * no task-time fallback is inferred.
+ */
 export declare function createAgentHomeProjectionConsumer(apply: AgentHomeProjectionApplyFunction): AgentHomeProjection;

package/dist/bin/agent-memory-mcp-server.d.ts

@@ -0,0 +1,38 @@
+export declare const AGENT_MEMORY_RECALL_TOOL_NAME = "memory.recall";
+export declare const AGENT_MEMORY_SAVE_TOOL_NAME = "memory.save";
+export interface AgentMemoryMcpDeps {
+    recall(input: {
+        path: string;
+        ifRevision?: string;
+    }): Promise<{
+        path: string;
+        revision: string;
+        content: string;
+        auditWarning?: {
+            code: 'agent_memory_audit_unavailable';
+        };
+    }>;
+    save(input: {
+        op: 'replace' | 'delete';
+        path: string;
+        expectedRevision: string;
+        content?: string;
+    }): Promise<{
+        path: string;
+        revision?: string;
+        deleted: boolean;
+    }>;
+}
+interface RequestLike {
+    jsonrpc?: unknown;
+    id?: unknown;
+    method?: unknown;
+    params?: unknown;
+}
+export declare function handleAgentMemoryMcpRequest(request: RequestLike, deps: AgentMemoryMcpDeps): Promise<Record<string, unknown> | undefined>;
+export declare function serveAgentMemoryMcpOverStdio(input: {
+    deps: AgentMemoryMcpDeps;
+    stdin?: NodeJS.ReadableStream;
+    stdout?: NodeJS.WritableStream;
+}): void;
+export {};

package/dist/bin/agent-message-mcp-server.d.ts

@@ -0,0 +1,24 @@
+import type { AgentMessageContentType } from '@byok-sdk/protocol';
+export declare const AGENT_MESSAGE_TOOL_NAME = "send_agent_message";
+export interface AgentMessageMcpDeps {
+    publish(input: {
+        contentType: AgentMessageContentType;
+        body: string;
+    }): Promise<{
+        messageId: string;
+        state: string;
+    }>;
+}
+interface RequestLike {
+    jsonrpc?: unknown;
+    id?: unknown;
+    method?: unknown;
+    params?: unknown;
+}
+export declare function handleAgentMessageMcpRequest(request: RequestLike, deps: AgentMessageMcpDeps): Promise<Record<string, unknown> | undefined>;
+export declare function serveAgentMessageMcpOverStdio(input: {
+    deps: AgentMessageMcpDeps;
+    stdin?: NodeJS.ReadableStream;
+    stdout?: NodeJS.WritableStream;
+}): void;
+export {};

package/dist/bin/byok-agent-memory-mcp.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/byok-agent-memory-mcp.js

@@ -0,0 +1,432 @@
+#!/usr/bin/env node
+import { promises, constants } from 'fs';
+import net from 'net';
+import { randomBytes, createHash, timingSafeEqual, createHmac } from 'crypto';
+import path from 'path';
+import { createInterface } from 'readline';
+
+var CONTROL_PROTOCOL_VERSION = 1;
+var HANDSHAKE_TIMEOUT_MS = 3e3;
+var UNIX_SOCKET_PATH_SOFT_LIMIT = 100;
+var CONTROL_SOCKET_FALLBACK_ROOT = "/tmp";
+function shortHash(input) {
+  return createHash("sha256").update(input, "utf8").digest("hex").slice(0, 16);
+}
+function controlSocketPath(storeDir) {
+  const candidate = path.join(storeDir, "control.sock");
+  if (Buffer.byteLength(candidate, "utf8") <= UNIX_SOCKET_PATH_SOFT_LIMIT) return candidate;
+  return path.join(CONTROL_SOCKET_FALLBACK_ROOT, `byok-${shortHash(storeDir)}`, "sock");
+}
+function controlPipeName(productId, storeDir) {
+  const id = shortHash(`${productId}|${path.resolve(storeDir)}`);
+  return `\\\\.\\pipe\\byok-${id}`;
+}
+function controlEndpointPath(productId, storeDir, platform = process.platform) {
+  return platform === "win32" ? controlPipeName(productId, storeDir) : controlSocketPath(storeDir);
+}
+function controlTokenPath(storeDir) {
+  return path.join(storeDir, "control.token");
+}
+var SERVER_PROOF_LABEL = "byok-control-server|";
+var CLIENT_AUTH_LABEL = "byok-control-client|";
+function randomNonceHex() {
+  return randomBytes(32).toString("hex");
+}
+function hmacHex(token, message) {
+  return createHmac("sha256", token).update(message, "utf8").digest("hex");
+}
+function computeServerProof(token, clientNonce) {
+  return hmacHex(token, SERVER_PROOF_LABEL + clientNonce);
+}
+function computeClientAuth(token, serverNonce) {
+  return hmacHex(token, CLIENT_AUTH_LABEL + serverNonce);
+}
+function timingSafeEqualHex(a, b) {
+  const bufA = Buffer.from(a, "hex");
+  const bufB = Buffer.from(b, "hex");
+  if (bufA.length !== bufB.length) return false;
+  return timingSafeEqual(bufA, bufB);
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+function parseServerHello(value) {
+  if (!isRecord(value)) return void 0;
+  if (value.v !== CONTROL_PROTOCOL_VERSION || value.hello !== "server" || typeof value.proof !== "string" || typeof value.nonce !== "string") {
+    return void 0;
+  }
+  return { v: CONTROL_PROTOCOL_VERSION, hello: "server", proof: value.proof, nonce: value.nonce };
+}
+function parseServerReady(value) {
+  if (!isRecord(value)) return void 0;
+  if (value.v !== CONTROL_PROTOCOL_VERSION || value.ready !== true) return void 0;
+  return { v: CONTROL_PROTOCOL_VERSION, ready: true };
+}
+function encodeFrame(frame) {
+  return `${JSON.stringify(frame)}
+`;
+}
+var ControlError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "ControlError";
+  }
+  code;
+};
+var MAX_LINE_BYTES = 64 * 1024;
+var NdjsonLineReader = class {
+  pending = Buffer.alloc(0);
+  /** @throws if the still-unterminated remainder exceeds {@link MAX_LINE_BYTES} — see that constant's own doc comment. */
+  push(chunk) {
+    this.pending = this.pending.length > 0 ? Buffer.concat([this.pending, chunk]) : chunk;
+    const lines = [];
+    let newlineIndex;
+    while ((newlineIndex = this.pending.indexOf(10)) !== -1) {
+      const line = this.pending.subarray(0, newlineIndex).toString("utf8");
+      this.pending = this.pending.subarray(newlineIndex + 1);
+      if (line.length > 0) lines.push(line);
+    }
+    if (this.pending.length > MAX_LINE_BYTES) {
+      throw new Error(`NDJSON line exceeded ${MAX_LINE_BYTES} bytes without a terminating newline`);
+    }
+    return lines;
+  }
+};
+
+// src/bin/control-client.ts
+var MAX_CONTROL_TOKEN_BYTES = 256;
+function errorMessage(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+function sameFileState(left, right) {
+  return left.dev === right.dev && left.ino === right.ino && left.size === right.size && left.mtimeNs === right.mtimeNs && left.ctimeNs === right.ctimeNs;
+}
+async function readControlToken(tokenPath) {
+  let namedBefore;
+  try {
+    namedBefore = await promises.lstat(tokenPath, { bigint: true });
+  } catch (err) {
+    if (err.code === "ENOENT") return void 0;
+    throw err;
+  }
+  if (!namedBefore.isFile() || namedBefore.isSymbolicLink()) {
+    throw new Error("control token is not a real regular file");
+  }
+  const handle = await promises.open(
+    tokenPath,
+    constants.O_RDONLY | (constants.O_NONBLOCK ?? 0) | (constants.O_NOFOLLOW ?? 0)
+  );
+  try {
+    const opened = await handle.stat({ bigint: true });
+    const namedAfterOpen = await promises.lstat(tokenPath, { bigint: true });
+    if (!opened.isFile() || !namedAfterOpen.isFile() || namedAfterOpen.isSymbolicLink() || !sameFileState(namedBefore, opened) || !sameFileState(opened, namedAfterOpen)) {
+      throw new Error("control token pathname changed before safe open");
+    }
+    if (opened.size < 0 || opened.size > BigInt(MAX_CONTROL_TOKEN_BYTES)) {
+      throw new Error("control token exceeds the bounded read limit");
+    }
+    const size = Number(opened.size);
+    const bytes = Buffer.alloc(size);
+    const { bytesRead } = await handle.read(bytes, 0, size, 0);
+    const afterRead = await handle.stat({ bigint: true });
+    const namedAfterRead = await promises.lstat(tokenPath, { bigint: true });
+    if (bytesRead !== size || namedAfterRead.isSymbolicLink() || !sameFileState(opened, afterRead) || !sameFileState(afterRead, namedAfterRead)) {
+      throw new Error("control token changed during bounded read");
+    }
+    return bytes.toString("utf8").trim();
+  } finally {
+    await handle.close();
+  }
+}
+async function connectControlClient(opts) {
+  const tokenPath = controlTokenPath(opts.storeDir);
+  let token;
+  try {
+    const read = await readControlToken(tokenPath);
+    if (read === void 0) {
+      return { ok: false, reason: "daemon is not running (no control.token found)" };
+    }
+    token = read;
+  } catch (err) {
+    return { ok: false, reason: `could not read the control token: ${errorMessage(err)}` };
+  }
+  if (!token) {
+    return { ok: false, reason: "control token file is empty" };
+  }
+  const endpoint = controlEndpointPath(opts.productId, opts.storeDir);
+  try {
+    const client = await connectAndHandshake(endpoint, token, opts);
+    return { ok: true, client };
+  } catch (err) {
+    return { ok: false, reason: `daemon control socket not reachable: ${errorMessage(err)}` };
+  }
+}
+function connectAndHandshake(endpoint, token, opts) {
+  return new Promise((resolve, reject) => {
+    const socket = net.createConnection(endpoint);
+    const reader = new NdjsonLineReader();
+    let phase = "server-hello";
+    let settled = false;
+    const clientNonce = randomNonceHex();
+    const timer = setTimeout(() => {
+      fail(new Error("handshake timed out"));
+    }, opts.handshakeTimeoutMs ?? HANDSHAKE_TIMEOUT_MS);
+    timer.unref?.();
+    function fail(err) {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      socket.removeAllListeners();
+      socket.destroy();
+      reject(err instanceof Error ? err : new Error(String(err)));
+    }
+    function succeed() {
+      settled = true;
+      clearTimeout(timer);
+      socket.removeListener("error", onError);
+      socket.removeListener("data", onData);
+      resolve(createControlClient(socket, reader, opts));
+    }
+    function onData(chunk) {
+      let lines;
+      try {
+        lines = reader.push(chunk);
+      } catch (err) {
+        fail(err);
+        return;
+      }
+      for (const line of lines) {
+        let parsed;
+        try {
+          parsed = JSON.parse(line);
+        } catch {
+          fail(new Error("malformed handshake frame"));
+          return;
+        }
+        if (phase === "server-hello") {
+          const hello = parseServerHello(parsed);
+          if (!hello) {
+            fail(new Error("malformed or unexpected server hello"));
+            return;
+          }
+          if (!timingSafeEqualHex(hello.proof, computeServerProof(token, clientNonce))) {
+            fail(new Error("server failed to prove it holds the control token"));
+            return;
+          }
+          socket.write(encodeFrame({ v: CONTROL_PROTOCOL_VERSION, auth: computeClientAuth(token, hello.nonce) }));
+          phase = "ready";
+          continue;
+        }
+        if (!parseServerReady(parsed)) {
+          fail(new Error("server did not confirm readiness"));
+          return;
+        }
+        succeed();
+        return;
+      }
+    }
+    function onError(err) {
+      fail(err);
+    }
+    socket.once("error", onError);
+    socket.once("connect", () => {
+      socket.write(encodeFrame({ v: CONTROL_PROTOCOL_VERSION, hello: "client", nonce: clientNonce }));
+      socket.on("data", onData);
+    });
+  });
+}
+function withTimeout(promise, ms, message) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error(message)), ms);
+    timer.unref?.();
+    promise.then(
+      (value) => {
+        clearTimeout(timer);
+        resolve(value);
+      },
+      (err) => {
+        clearTimeout(timer);
+        reject(err);
+      }
+    );
+  });
+}
+function createControlClient(socket, reader, opts) {
+  const pending = /* @__PURE__ */ new Map();
+  let idSeq = 0;
+  let closed = false;
+  function handleFrame(parsed) {
+    if (!isRecord(parsed) || typeof parsed.id !== "string") return;
+    const entry = pending.get(parsed.id);
+    if (!entry) return;
+    if ("event" in parsed) {
+      entry.onEvent?.(parsed.event);
+      return;
+    }
+    if (parsed.ok === true) {
+      pending.delete(parsed.id);
+      entry.resolve(parsed.done === true ? void 0 : parsed.result);
+      return;
+    }
+    pending.delete(parsed.id);
+    const shape = parsed.error;
+    entry.reject(
+      new ControlError(
+        typeof shape?.code === "string" ? shape.code : "internal_error",
+        typeof shape?.message === "string" ? shape.message : "unknown control error"
+      )
+    );
+  }
+  socket.on("data", (chunk) => {
+    let lines;
+    try {
+      lines = reader.push(chunk);
+    } catch {
+      socket.destroy();
+      return;
+    }
+    for (const line of lines) {
+      let parsed;
+      try {
+        parsed = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      handleFrame(parsed);
+    }
+  });
+  socket.on("close", () => {
+    closed = true;
+    for (const entry of pending.values()) entry.reject(new Error("control connection closed"));
+    pending.clear();
+  });
+  socket.on("error", () => {
+  });
+  function send(method, params, onEvent) {
+    const id = `c${++idSeq}`;
+    const promise = new Promise((resolve, reject) => {
+      pending.set(id, { resolve, reject, onEvent });
+    });
+    socket.write(encodeFrame({ v: CONTROL_PROTOCOL_VERSION, id, method, params }));
+    return { id, promise };
+  }
+  return {
+    async request(method, params) {
+      if (closed) throw new Error("control connection is closed");
+      const { promise } = send(method, params);
+      const result = await withTimeout(promise, opts.requestTimeoutMs ?? 1e4, `control request "${method}" timed out`);
+      return result;
+    },
+    subscribe(method, params, onEvent) {
+      const { id, promise } = send(method, params, onEvent);
+      promise.catch(() => {
+      });
+      return {
+        close: () => {
+          pending.delete(id);
+          socket.destroy();
+        }
+      };
+    },
+    close() {
+      socket.destroy();
+    }
+  };
+}
+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/bin/byok-agent-memory-mcp.ts
+function required(name) {
+  const value = process.env[name];
+  if (!value) throw new Error(`missing required environment variable ${name}`);
+  return value;
+}
+async function main() {
+  const storeDir = required("BYOK_STORE_DIR");
+  const productId = required("BYOK_PRODUCT_ID");
+  const contextToken = required("BYOK_AGENT_MEMORY_CONTEXT");
+  let clientPromise;
+  const client = async () => {
+    if (!clientPromise) clientPromise = connectControlClient({ storeDir, productId }).then((result) => {
+      if (!result.ok) throw new Error(result.reason);
+      return result.client;
+    });
+    return clientPromise;
+  };
+  const deps = {
+    recall: async (input) => (await client()).request("agent_memory.recall", { contextToken, ...input }),
+    save: async (input) => (await client()).request("agent_memory.save", { contextToken, ...input })
+  };
+  serveAgentMemoryMcpOverStdio({ deps });
+}
+main().catch((error) => {
+  process.stderr.write(`byok-agent-memory-mcp: ${error instanceof Error ? error.message : String(error)}
+`);
+  process.exit(1);
+});
+//# sourceMappingURL=byok-agent-memory-mcp.js.map
+//# sourceMappingURL=byok-agent-memory-mcp.js.map