@vellumai/credential-executor 0.5.16 → 0.6.1

package/Dockerfile

@@ -9,8 +9,8 @@ RUN apt-get update && apt-get install -y \
     unzip \
     && rm -rf /var/lib/apt/lists/*
 
-# Install bun
-RUN curl -fsSL https://bun.sh/install | bash
+# Install bun (pinned version)
+RUN curl -fsSL https://bun.sh/install | bash -s "bun-v1.3.11"
 ENV PATH="/root/.bun/bin:${PATH}"
 
 # Copy shared packages first (needed for repo-local dependencies)

package/bun.lock

@@ -8,6 +8,8 @@
         "@vellumai/ces-contracts": "file:../packages/ces-contracts",
         "@vellumai/credential-storage": "file:../packages/credential-storage",
         "@vellumai/egress-proxy": "file:../packages/egress-proxy",
+        "pino": "^9.6.0",
+        "pino-pretty": "^13.1.3",
       },
       "devDependencies": {
         "@types/bun": "^1.2.4",
@@ -16,6 +18,8 @@
     },
   },
   "packages": {
+    "@pinojs/redact": ["@pinojs/redact@0.4.0", "", {}, "sha512-k2ENnmBugE/rzQfEcdWHcCY+/FM3VLzH9cYEsbdsoqrvzAKRhUZeRNhAZvB8OitQJ1TBed3yqWtdjzS6wJKBwg=="],
+
     "@types/bun": ["@types/bun@1.3.10", "", { "dependencies": { "bun-types": "1.3.10" } }, "sha512-0+rlrUrOrTSskibryHbvQkDOWRJwJZqZlxrUs1u4oOoTln8+WIXBPmAuCF35SWB2z4Zl3E84Nl/D0P7803nigQ=="],
 
     "@types/node": ["@types/node@25.5.0", "", { "dependencies": { "undici-types": "~7.18.0" } }, "sha512-jp2P3tQMSxWugkCUKLRPVUpGaL5MVFwF8RDuSRztfwgN1wmqJeMSbKlnEtQqU8UrhTmzEmZdu2I6v2dpp7XIxw=="],
@@ -26,12 +30,66 @@
 
     "@vellumai/egress-proxy": ["@vellumai/egress-proxy@file:../packages/egress-proxy", { "devDependencies": { "@types/bun": "^1.2.4", "typescript": "^5.7.3" } }],
 
+    "atomic-sleep": ["atomic-sleep@1.0.0", "", {}, "sha512-kNOjDqAh7px0XWNI+4QbzoiR/nTkHAWNud2uvnJquD1/x5a7EQZMJT0AczqK0Qn67oY/TTQ1LbUKajZpp3I9tQ=="],
+
     "bun-types": ["bun-types@1.3.10", "", { "dependencies": { "@types/node": "*" } }, "sha512-tcpfCCl6XWo6nCVnpcVrxQ+9AYN1iqMIzgrSKYMB/fjLtV2eyAVEg7AxQJuCq/26R6HpKWykQXuSOq/21RYcbg=="],
 
+    "colorette": ["colorette@2.0.20", "", {}, "sha512-IfEDxwoWIjkeXL1eXcDiow4UbKjhLdq6/EuSVR9GMN7KVH3r9gQ83e73hsz1Nd1T3ijd5xv1wcWRYO+D6kCI2w=="],
+
+    "dateformat": ["dateformat@4.6.3", "", {}, "sha512-2P0p0pFGzHS5EMnhdxQi7aJN+iMheud0UhG4dlE1DLAlvL8JHjJJTX/CSm4JXwV0Ka5nGk3zC5mcb5bUQUxxMA=="],
+
+    "end-of-stream": ["end-of-stream@1.4.5", "", { "dependencies": { "once": "^1.4.0" } }, "sha512-ooEGc6HP26xXq/N+GCGOT0JKCLDGrq2bQUZrQ7gyrJiZANJ/8YDTxTpQBXGMn+WbIQXNVpyWymm7KYVICQnyOg=="],
+
+    "fast-copy": ["fast-copy@4.0.2", "", {}, "sha512-ybA6PDXIXOXivLJK/z9e+Otk7ve13I4ckBvGO5I2RRmBU1gMHLVDJYEuJYhGwez7YNlYji2M2DvVU+a9mSFDlw=="],
+
+    "fast-safe-stringify": ["fast-safe-stringify@2.1.1", "", {}, "sha512-W+KJc2dmILlPplD/H4K9l9LcAHAfPtP6BY84uVLXQ6Evcz9Lcg33Y2z1IVblT6xdY54PXYVHEv+0Wpq8Io6zkA=="],
+
+    "help-me": ["help-me@5.0.0", "", {}, "sha512-7xgomUX6ADmcYzFik0HzAxh/73YlKR9bmFzf51CZwR+b6YtzU2m0u49hQCqV6SvlqIqsaxovfwdvbnsw3b/zpg=="],
+
+    "joycon": ["joycon@3.1.1", "", {}, "sha512-34wB/Y7MW7bzjKRjUKTa46I2Z7eV62Rkhva+KkopW7Qvv/OSWBqvkSY7vusOPrNuZcUG3tApvdVgNB8POj3SPw=="],
+
+    "minimist": ["minimist@1.2.8", "", {}, "sha512-2yyAR8qBkN3YuheJanUpWC5U3bb5osDywNB8RzDVlDwDHbocAJveqqj1u8+SVD7jkWT4yvsHCpWqqWqAxb0zCA=="],
+
+    "on-exit-leak-free": ["on-exit-leak-free@2.1.2", "", {}, "sha512-0eJJY6hXLGf1udHwfNftBqH+g73EU4B504nZeKpz1sYRKafAghwxEJunB2O7rDZkL4PGfsMVnTXZ2EjibbqcsA=="],
+
+    "once": ["once@1.4.0", "", { "dependencies": { "wrappy": "1" } }, "sha512-lNaJgI+2Q5URQBkccEKHTQOPaXdUxnZZElQTZY0MFUAuaEqe1E+Nyvgdz/aIyNi6Z9MzO5dv1H8n58/GELp3+w=="],
+
+    "pino": ["pino@9.14.0", "", { "dependencies": { "@pinojs/redact": "^0.4.0", "atomic-sleep": "^1.0.0", "on-exit-leak-free": "^2.1.0", "pino-abstract-transport": "^2.0.0", "pino-std-serializers": "^7.0.0", "process-warning": "^5.0.0", "quick-format-unescaped": "^4.0.3", "real-require": "^0.2.0", "safe-stable-stringify": "^2.3.1", "sonic-boom": "^4.0.1", "thread-stream": "^3.0.0" }, "bin": { "pino": "bin.js" } }, "sha512-8OEwKp5juEvb/MjpIc4hjqfgCNysrS94RIOMXYvpYCdm/jglrKEiAYmiumbmGhCvs+IcInsphYDFwqrjr7398w=="],
+
+    "pino-abstract-transport": ["pino-abstract-transport@2.0.0", "", { "dependencies": { "split2": "^4.0.0" } }, "sha512-F63x5tizV6WCh4R6RHyi2Ml+M70DNRXt/+HANowMflpgGFMAym/VKm6G7ZOQRjqN7XbGxK1Lg9t6ZrtzOaivMw=="],
+
+    "pino-pretty": ["pino-pretty@13.1.3", "", { "dependencies": { "colorette": "^2.0.7", "dateformat": "^4.6.3", "fast-copy": "^4.0.0", "fast-safe-stringify": "^2.1.1", "help-me": "^5.0.0", "joycon": "^3.1.1", "minimist": "^1.2.6", "on-exit-leak-free": "^2.1.0", "pino-abstract-transport": "^3.0.0", "pump": "^3.0.0", "secure-json-parse": "^4.0.0", "sonic-boom": "^4.0.1", "strip-json-comments": "^5.0.2" }, "bin": { "pino-pretty": "bin.js" } }, "sha512-ttXRkkOz6WWC95KeY9+xxWL6AtImwbyMHrL1mSwqwW9u+vLp/WIElvHvCSDg0xO/Dzrggz1zv3rN5ovTRVowKg=="],
+
+    "pino-std-serializers": ["pino-std-serializers@7.1.0", "", {}, "sha512-BndPH67/JxGExRgiX1dX0w1FvZck5Wa4aal9198SrRhZjH3GxKQUKIBnYJTdj2HDN3UQAS06HlfcSbQj2OHmaw=="],
+
+    "process-warning": ["process-warning@5.0.0", "", {}, "sha512-a39t9ApHNx2L4+HBnQKqxxHNs1r7KF+Intd8Q/g1bUh6q0WIp9voPXJ/x0j+ZL45KF1pJd9+q2jLIRMfvEshkA=="],
+
+    "pump": ["pump@3.0.4", "", { "dependencies": { "end-of-stream": "^1.1.0", "once": "^1.3.1" } }, "sha512-VS7sjc6KR7e1ukRFhQSY5LM2uBWAUPiOPa/A3mkKmiMwSmRFUITt0xuj+/lesgnCv+dPIEYlkzrcyXgquIHMcA=="],
+
+    "quick-format-unescaped": ["quick-format-unescaped@4.0.4", "", {}, "sha512-tYC1Q1hgyRuHgloV/YXs2w15unPVh8qfu/qCTfhTYamaw7fyhumKa2yGpdSo87vY32rIclj+4fWYQXUMs9EHvg=="],
+
+    "real-require": ["real-require@0.2.0", "", {}, "sha512-57frrGM/OCTLqLOAh0mhVA9VBMHd+9U7Zb2THMGdBUoZVOtGbJzjxsYGDJ3A9AYYCP4hn6y1TVbaOfzWtm5GFg=="],
+
+    "safe-stable-stringify": ["safe-stable-stringify@2.5.0", "", {}, "sha512-b3rppTKm9T+PsVCBEOUR46GWI7fdOs00VKZ1+9c1EWDaDMvjQc6tUwuFyIprgGgTcWoVHSKrU8H31ZHA2e0RHA=="],
+
+    "secure-json-parse": ["secure-json-parse@4.1.0", "", {}, "sha512-l4KnYfEyqYJxDwlNVyRfO2E4NTHfMKAWdUuA8J0yve2Dz/E/PdBepY03RvyJpssIpRFwJoCD55wA+mEDs6ByWA=="],
+
+    "sonic-boom": ["sonic-boom@4.2.1", "", { "dependencies": { "atomic-sleep": "^1.0.0" } }, "sha512-w6AxtubXa2wTXAUsZMMWERrsIRAdrK0Sc+FUytWvYAhBJLyuI4llrMIC1DtlNSdI99EI86KZum2MMq3EAZlF9Q=="],
+
+    "split2": ["split2@4.2.0", "", {}, "sha512-UcjcJOWknrNkF6PLX83qcHM6KHgVKNkV62Y8a5uYDVv9ydGQVwAHMKqHdJje1VTWpljG0WYpCDhrCdAOYH4TWg=="],
+
+    "strip-json-comments": ["strip-json-comments@5.0.3", "", {}, "sha512-1tB5mhVo7U+ETBKNf92xT4hrQa3pm0MZ0PQvuDnWgAAGHDsfp4lPSpiS6psrSiet87wyGPh9ft6wmhOMQ0hDiw=="],
+
+    "thread-stream": ["thread-stream@3.1.0", "", { "dependencies": { "real-require": "^0.2.0" } }, "sha512-OqyPZ9u96VohAyMfJykzmivOrY2wfMSf3C5TtFJVgN+Hm6aj+voFhlK+kZEIv2FBh1X6Xp3DlnCOfEQ3B2J86A=="],
+
     "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
 
     "undici-types": ["undici-types@7.18.2", "", {}, "sha512-AsuCzffGHJybSaRrmr5eHr81mwJU3kjw6M+uprWvCXiNeN9SOGwQ3Jn8jb8m3Z6izVgknn1R0FTCEAP2QrLY/w=="],
 
+    "wrappy": ["wrappy@1.0.2", "", {}, "sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ=="],
+
     "zod": ["zod@4.3.6", "", {}, "sha512-rftlrkhHZOcjDwkGlnUtZZkvaPHCsDATp4pGpuOOMDaTdDDXF91wuVDJoWoPsKX/3YPQ5fHuF3STjcYyKr+Qhg=="],
+
+    "pino-pretty/pino-abstract-transport": ["pino-abstract-transport@3.0.0", "", { "dependencies": { "split2": "^4.0.0" } }, "sha512-wlfUczU+n7Hy/Ha5j9a/gZNy7We5+cXp8YL+X+PG8S0KXxw7n/JXA3c46Y0zQznIJ83URJiwy7Lh56WLokNuxg=="],
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/credential-executor",
-  "version": "0.5.16",
+  "version": "0.6.1",
   "license": "MIT",
   "type": "module",
   "exports": {
@@ -20,7 +20,9 @@
   "dependencies": {
     "@vellumai/ces-contracts": "file:../packages/ces-contracts",
     "@vellumai/credential-storage": "file:../packages/credential-storage",
-    "@vellumai/egress-proxy": "file:../packages/egress-proxy"
+    "@vellumai/egress-proxy": "file:../packages/egress-proxy",
+    "pino": "^9.6.0",
+    "pino-pretty": "^13.1.3"
   },
   "bundledDependencies": [
     "@vellumai/ces-contracts",

package/src/http/log-export-routes.test.ts

@@ -0,0 +1,249 @@
+/**
+ * Tests for the CES log export route handler.
+ *
+ * Verifies:
+ * - Returns a valid tar.gz archive containing CES log files
+ * - Filters log files by startTime query param
+ * - Filters log files by endTime query param
+ * - Returns an empty archive (manifest only) when no logs exist
+ * - Returns 401/403 without a valid service token
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "bun:test";
+import {
+  mkdirSync,
+  mkdtempSync,
+  readdirSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+
+import { handleLogExportRoute } from "./log-export-routes.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const SERVICE_TOKEN = "test-ces-service-token-12345";
+
+let tmpLogDir: string;
+
+function makeRequest(
+  opts: {
+    startTime?: number;
+    endTime?: number;
+    token?: string | null;
+    method?: string;
+  } = {},
+): Request {
+  const params = new URLSearchParams();
+  if (opts.startTime !== undefined)
+    params.set("startTime", String(opts.startTime));
+  if (opts.endTime !== undefined) params.set("endTime", String(opts.endTime));
+
+  const qs = params.toString();
+  const url = `http://localhost:8090/v1/logs/export${qs ? `?${qs}` : ""}`;
+
+  const headers: Record<string, string> = {};
+  if (opts.token !== null) {
+    headers["Authorization"] = `Bearer ${opts.token ?? SERVICE_TOKEN}`;
+  }
+
+  return new Request(url, { method: opts.method ?? "GET", headers });
+}
+
+/**
+ * Extract a tar.gz buffer and return the list of file paths inside.
+ */
+function extractTarGzEntries(buf: ArrayBuffer): string[] {
+  const staging = mkdtempSync(join(tmpdir(), "ces-test-extract-"));
+  try {
+    const tarGzPath = join(staging, "archive.tar.gz");
+    writeFileSync(tarGzPath, Buffer.from(buf));
+
+    const extractDir = join(staging, "out");
+    mkdirSync(extractDir, { recursive: true });
+
+    const proc = spawnSync("tar", ["xzf", tarGzPath, "-C", extractDir]);
+    if (proc.status !== 0) {
+      throw new Error(
+        `tar extraction failed: ${proc.stderr?.toString() ?? "unknown"}`,
+      );
+    }
+
+    // Recursively list all files
+    const files: string[] = [];
+    function walk(dir: string, prefix: string) {
+      for (const entry of readdirSync(dir)) {
+        const full = join(dir, entry);
+        const rel = prefix ? `${prefix}/${entry}` : entry;
+        if (statSync(full).isDirectory()) {
+          walk(full, rel);
+        } else {
+          files.push(rel);
+        }
+      }
+    }
+    walk(extractDir, "");
+    return files.sort();
+  } finally {
+    rmSync(staging, { recursive: true, force: true });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Setup / Teardown
+// ---------------------------------------------------------------------------
+
+beforeEach(() => {
+  tmpLogDir = mkdtempSync(join(tmpdir(), "ces-log-export-test-"));
+  process.env["CES_SERVICE_TOKEN"] = SERVICE_TOKEN;
+});
+
+afterEach(() => {
+  rmSync(tmpLogDir, { recursive: true, force: true });
+  delete process.env["CES_SERVICE_TOKEN"];
+});
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("CES log export route", () => {
+  it("returns tar.gz with CES log files", async () => {
+    // Create test log files
+    writeFileSync(join(tmpLogDir, "ces-2025-01-15.log"), "log line 1\n");
+    writeFileSync(join(tmpLogDir, "ces-2025-01-16.log"), "log line 2\n");
+
+    const res = await handleLogExportRoute(makeRequest(), tmpLogDir);
+    expect(res).not.toBeNull();
+    expect(res!.status).toBe(200);
+    expect(res!.headers.get("Content-Type")).toBe("application/gzip");
+
+    const buf = await res!.arrayBuffer();
+    const entries = extractTarGzEntries(buf);
+
+    // Should contain the manifest and the two log files
+    expect(entries).toContain("ces-export-manifest.json");
+    expect(entries).toContain("ces-logs/ces-2025-01-15.log");
+    expect(entries).toContain("ces-logs/ces-2025-01-16.log");
+  });
+
+  it("filters by startTime query param", async () => {
+    // 2025-01-15 = 1736899200000 (start of day UTC)
+    // 2025-01-16 = 1736985600000 (start of day UTC)
+    // 2025-01-17 = 1737072000000 (start of day UTC)
+    writeFileSync(join(tmpLogDir, "ces-2025-01-15.log"), "old log\n");
+    writeFileSync(join(tmpLogDir, "ces-2025-01-16.log"), "recent log\n");
+    writeFileSync(join(tmpLogDir, "ces-2025-01-17.log"), "newest log\n");
+
+    // startTime at 2025-01-16 12:00:00 UTC — should include 01-16 and 01-17
+    // because 01-16 day end (23:59:59.999) >= startTime
+    const startTime = new Date("2025-01-16T12:00:00Z").getTime();
+    const res = await handleLogExportRoute(
+      makeRequest({ startTime }),
+      tmpLogDir,
+    );
+    expect(res).not.toBeNull();
+    expect(res!.status).toBe(200);
+
+    const entries = extractTarGzEntries(await res!.arrayBuffer());
+    expect(entries).not.toContain("ces-logs/ces-2025-01-15.log");
+    expect(entries).toContain("ces-logs/ces-2025-01-16.log");
+    expect(entries).toContain("ces-logs/ces-2025-01-17.log");
+  });
+
+  it("filters by endTime query param", async () => {
+    writeFileSync(join(tmpLogDir, "ces-2025-01-15.log"), "old log\n");
+    writeFileSync(join(tmpLogDir, "ces-2025-01-16.log"), "recent log\n");
+    writeFileSync(join(tmpLogDir, "ces-2025-01-17.log"), "newest log\n");
+
+    // endTime at 2025-01-16 00:00:00 UTC — should include 01-15 and 01-16
+    // because 01-16 day start (00:00:00) <= endTime, but 01-17 day start > endTime
+    const endTime = new Date("2025-01-16T00:00:00Z").getTime();
+    const res = await handleLogExportRoute(makeRequest({ endTime }), tmpLogDir);
+    expect(res).not.toBeNull();
+    expect(res!.status).toBe(200);
+
+    const entries = extractTarGzEntries(await res!.arrayBuffer());
+    expect(entries).toContain("ces-logs/ces-2025-01-15.log");
+    expect(entries).toContain("ces-logs/ces-2025-01-16.log");
+    expect(entries).not.toContain("ces-logs/ces-2025-01-17.log");
+  });
+
+  it("returns empty archive when no logs exist", async () => {
+    // tmpLogDir exists but has no log files
+    const res = await handleLogExportRoute(makeRequest(), tmpLogDir);
+    expect(res).not.toBeNull();
+    expect(res!.status).toBe(200);
+
+    const entries = extractTarGzEntries(await res!.arrayBuffer());
+    // Should still contain the manifest
+    expect(entries).toContain("ces-export-manifest.json");
+    // No log files in ces-logs/
+    const logFiles = entries.filter((e) => e.startsWith("ces-logs/"));
+    expect(logFiles.length).toBe(0);
+  });
+
+  it("returns 401 without Authorization header", async () => {
+    const res = await handleLogExportRoute(
+      makeRequest({ token: null }),
+      tmpLogDir,
+    );
+    expect(res).not.toBeNull();
+    expect(res!.status).toBe(401);
+
+    const body = await res!.json();
+    expect(body.error).toMatch(/Missing Authorization/i);
+  });
+
+  it("returns 403 with wrong service token", async () => {
+    const res = await handleLogExportRoute(
+      makeRequest({ token: "wrong-token-value" }),
+      tmpLogDir,
+    );
+    expect(res).not.toBeNull();
+    expect(res!.status).toBe(403);
+
+    const body = await res!.json();
+    expect(body.error).toMatch(/Invalid service token/i);
+  });
+
+  it("returns null for non-matching paths", async () => {
+    const req = new Request("http://localhost:8090/v1/other", {
+      method: "GET",
+      headers: { Authorization: `Bearer ${SERVICE_TOKEN}` },
+    });
+    const res = await handleLogExportRoute(req, tmpLogDir);
+    expect(res).toBeNull();
+  });
+
+  it("returns 405 for non-GET methods on the export path", async () => {
+    const res = await handleLogExportRoute(
+      makeRequest({ method: "POST" }),
+      tmpLogDir,
+    );
+    expect(res).not.toBeNull();
+    expect(res!.status).toBe(405);
+  });
+
+  it("ignores non-log files in the directory", async () => {
+    writeFileSync(join(tmpLogDir, "ces-2025-01-15.log"), "real log\n");
+    writeFileSync(join(tmpLogDir, "random-file.txt"), "not a log\n");
+    writeFileSync(join(tmpLogDir, "ces-bad-date.log"), "bad pattern\n");
+
+    const res = await handleLogExportRoute(makeRequest(), tmpLogDir);
+    expect(res).not.toBeNull();
+    expect(res!.status).toBe(200);
+
+    const entries = extractTarGzEntries(await res!.arrayBuffer());
+    expect(entries).toContain("ces-logs/ces-2025-01-15.log");
+    // Non-matching files should not be included
+    const logFiles = entries.filter((e) => e.startsWith("ces-logs/"));
+    expect(logFiles.length).toBe(1);
+  });
+});

package/src/http/log-export-routes.ts

@@ -0,0 +1,219 @@
+/**
+ * Log export HTTP endpoint for the CES managed service.
+ *
+ * Exposes a single `GET /v1/logs/export` endpoint that collects CES log
+ * files, archives them as a tar.gz, and returns the archive. The gateway
+ * calls this endpoint to collect CES logs alongside daemon and gateway
+ * logs during a diagnostic log export.
+ *
+ * Auth: Requires a `CES_SERVICE_TOKEN` bearer token in the
+ * `Authorization` header (same token used for credential CRUD).
+ */
+
+import { spawnSync } from "node:child_process";
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readdirSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { timingSafeEqual } from "node:crypto";
+
+import { LOG_FILE_PATTERN } from "../logger.js";
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** Maximum cumulative size of collected log files (5 MB). */
+const MAX_LOG_BYTES = 5 * 1024 * 1024;
+
+// ---------------------------------------------------------------------------
+// Auth
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate the Authorization header against the configured service token.
+ * Returns an error Response if auth fails, or null if auth succeeds.
+ */
+function checkAuth(req: Request, serviceToken: string): Response | null {
+  const authHeader = req.headers.get("authorization");
+  if (!authHeader) {
+    return new Response(
+      JSON.stringify({ error: "Missing Authorization header" }),
+      { status: 401, headers: { "Content-Type": "application/json" } },
+    );
+  }
+
+  const parts = authHeader.split(" ");
+  if (parts.length !== 2 || parts[0]!.toLowerCase() !== "bearer") {
+    return new Response(
+      JSON.stringify({ error: "Invalid Authorization header format. Expected: Bearer <token>" }),
+      { status: 401, headers: { "Content-Type": "application/json" } },
+    );
+  }
+
+  const provided = Buffer.from(parts[1]!);
+  const expected = Buffer.from(serviceToken);
+  if (provided.length !== expected.length || !timingSafeEqual(provided, expected)) {
+    return new Response(
+      JSON.stringify({ error: "Invalid service token" }),
+      { status: 403, headers: { "Content-Type": "application/json" } },
+    );
+  }
+
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Route handler
+// ---------------------------------------------------------------------------
+
+/**
+ * Try to handle a log export request. Returns a Response if the request
+ * matches `GET /v1/logs/export`, or null if it doesn't match (allowing the
+ * caller to fall through to other routes).
+ */
+export async function handleLogExportRoute(
+  req: Request,
+  logDir: string,
+): Promise<Response | null> {
+  const url = new URL(req.url);
+
+  // Only handle GET /v1/logs/export
+  if (url.pathname !== "/v1/logs/export") {
+    return null;
+  }
+
+  if (req.method !== "GET") {
+    return new Response(
+      JSON.stringify({ error: "Method not allowed" }),
+      { status: 405, headers: { "Content-Type": "application/json" } },
+    );
+  }
+
+  // Auth check
+  const serviceToken = process.env["CES_SERVICE_TOKEN"] ?? "";
+  if (!serviceToken) {
+    return new Response(
+      JSON.stringify({ error: "CES_SERVICE_TOKEN not configured" }),
+      { status: 500, headers: { "Content-Type": "application/json" } },
+    );
+  }
+
+  const authError = checkAuth(req, serviceToken);
+  if (authError) return authError;
+
+  // Parse optional time range query params
+  const startTimeParam = url.searchParams.get("startTime");
+  const endTimeParam = url.searchParams.get("endTime");
+  const startTime = startTimeParam ? Number(startTimeParam) : undefined;
+  const endTime = endTimeParam ? Number(endTimeParam) : undefined;
+
+  const staging = mkdtempSync(join(tmpdir(), "ces-log-export-"));
+
+  try {
+    const logsStaging = join(staging, "ces-logs");
+    mkdirSync(logsStaging, { recursive: true });
+
+    let totalBytes = 0;
+    let filesCollected = 0;
+
+    if (existsSync(logDir)) {
+      const entries = readdirSync(logDir);
+      for (const entry of entries) {
+        const dateMatch = LOG_FILE_PATTERN.exec(entry);
+        if (!dateMatch) continue;
+
+        // Filter by date when startTime/endTime are provided.
+        // Parse the date from the filename and compare start-of-day / end-of-day
+        // against the time bounds.
+        const fileDateStr = dateMatch[1]!;
+        const fileDayStartMs = new Date(fileDateStr + "T00:00:00.000Z").getTime();
+        const fileDayEndMs = new Date(fileDateStr + "T23:59:59.999Z").getTime();
+
+        if (startTime !== undefined && fileDayEndMs < startTime) continue; // entire day before range
+        if (endTime !== undefined && fileDayStartMs > endTime) continue; // entire day after range
+
+        const filePath = join(logDir, entry);
+        try {
+          const stat = statSync(filePath);
+          if (!stat.isFile()) continue;
+          if (totalBytes + stat.size > MAX_LOG_BYTES) continue;
+
+          // Copy the file to the staging directory via Bun.file for efficiency,
+          // but fall back to sync fs for portability in the spawnSync-based flow.
+          const content = await Bun.file(filePath).arrayBuffer();
+          writeFileSync(join(logsStaging, entry), Buffer.from(content));
+          totalBytes += stat.size;
+          filesCollected++;
+        } catch {
+          // Skip unreadable files
+        }
+      }
+    }
+
+    // Always write a manifest so the consumer knows what was collected
+    const manifest = {
+      type: "ces-log-export",
+      exportedAt: new Date().toISOString(),
+      filesCollected,
+      totalBytes,
+      ...(startTime !== undefined ? { startTime } : {}),
+      ...(endTime !== undefined ? { endTime } : {}),
+    };
+    writeFileSync(
+      join(staging, "ces-export-manifest.json"),
+      JSON.stringify(manifest, null, 2),
+      "utf-8",
+    );
+
+    // Create tar.gz archive of the staging directory
+    const proc = spawnSync("tar", ["czf", "-", "-C", staging, "."], {
+      maxBuffer: MAX_LOG_BYTES * 2, // allow headroom for tar overhead
+      timeout: 30_000,
+    });
+
+    if (proc.status !== 0) {
+      const stderr = proc.stderr
+        ? Buffer.isBuffer(proc.stderr)
+          ? proc.stderr.toString("utf-8")
+          : String(proc.stderr)
+        : "unknown error";
+      return new Response(
+        JSON.stringify({ error: "Failed to create archive", detail: stderr }),
+        { status: 500, headers: { "Content-Type": "application/json" } },
+      );
+    }
+
+    const archiveBuffer = Buffer.isBuffer(proc.stdout)
+      ? proc.stdout
+      : Buffer.from(proc.stdout);
+
+    return new Response(
+      archiveBuffer.buffer.slice(
+        archiveBuffer.byteOffset,
+        archiveBuffer.byteOffset + archiveBuffer.byteLength,
+      ),
+      {
+        status: 200,
+        headers: {
+          "Content-Type": "application/gzip",
+          "Content-Disposition": 'attachment; filename="ces-logs.tar.gz"',
+          "Content-Length": String(archiveBuffer.byteLength),
+        },
+      },
+    );
+  } finally {
+    try {
+      rmSync(staging, { recursive: true, force: true });
+    } catch {
+      // Best-effort cleanup
+    }
+  }
+}

package/src/log-redact.ts

@@ -0,0 +1,133 @@
+/**
+ * Pino log serializers that scrub sensitive data (bearer tokens, API keys,
+ * authorization headers) from logged values.
+ *
+ * Standalone copy for the credential-executor package — kept in sync with
+ * gateway/src/log-redact.ts and assistant/src/util/log-redact.ts.
+ */
+
+// ---------------------------------------------------------------------------
+// Sensitive-value patterns
+// ---------------------------------------------------------------------------
+
+const BEARER_RE = /Bearer [A-Za-z0-9._\-]+/g;
+
+const API_KEY_PATTERNS: RegExp[] = [
+  /AKIA[0-9A-Z]{16}/g,
+  /gh[pousr]_[A-Za-z0-9_]{36,255}/g,
+  /github_pat_[A-Za-z0-9_]{22,255}/g,
+  /glpat-[A-Za-z0-9\-_]{20,}/g,
+  /sk_live_[A-Za-z0-9]{24,}/g,
+  /rk_live_[A-Za-z0-9]{24,}/g,
+  /xoxb-[0-9]{10,}-[0-9]{10,}-[A-Za-z0-9]{24,}/g,
+  /xoxp-[0-9]{10,}-[0-9]{10,}-[0-9]{10,}-[a-f0-9]{32}/g,
+  /sk-ant-[A-Za-z0-9\-_]{80,}/g,
+  /sk-[A-Za-z0-9]{20}T3BlbkFJ[A-Za-z0-9]{20}/g,
+  /sk-proj-[A-Za-z0-9\-_]{40,}/g,
+  /AIza[A-Za-z0-9\-_]{35}/g,
+  /GOCSPX-[A-Za-z0-9\-_]{28}/g,
+  /SG\.[A-Za-z0-9\-_]{22}\.[A-Za-z0-9\-_]{43}/g,
+  /[0-9]{8,10}:[A-Za-z0-9_-]{35}/g,
+  /npm_[A-Za-z0-9]{36}/g,
+];
+
+const SENSITIVE_HEADERS = new Set([
+  "authorization",
+  "proxy-authorization",
+  "cookie",
+  "set-cookie",
+  "x-api-key",
+  "x-auth-token",
+]);
+
+// ---------------------------------------------------------------------------
+// String redaction
+// ---------------------------------------------------------------------------
+
+function redactString(value: string): string {
+  let result = value;
+  result = result.replace(BEARER_RE, "Bearer [REDACTED]");
+  for (const pattern of API_KEY_PATTERNS) {
+    pattern.lastIndex = 0;
+    result = result.replace(pattern, "[REDACTED]");
+  }
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Deep value redaction
+// ---------------------------------------------------------------------------
+
+function redactValue(value: unknown, depth: number): unknown {
+  if (depth > 8) return value;
+
+  if (typeof value === "string") {
+    return redactString(value);
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((item) => redactValue(item, depth + 1));
+  }
+
+  if (value !== null && typeof value === "object") {
+    const result: Record<string, unknown> = {};
+    for (const [key, val] of Object.entries(value as Record<string, unknown>)) {
+      if (SENSITIVE_HEADERS.has(key.toLowerCase())) {
+        result[key] = "[REDACTED]";
+      } else {
+        result[key] = redactValue(val, depth + 1);
+      }
+    }
+    return result;
+  }
+
+  return value;
+}
+
+// ---------------------------------------------------------------------------
+// Error serialization — extracts non-enumerable Error fields and cause chain
+// ---------------------------------------------------------------------------
+
+function serializeError(err: unknown, depth: number): unknown {
+  if (depth > 8 || err == null) return err;
+
+  if (!(err instanceof Error)) {
+    return err;
+  }
+
+  const serialized: Record<string, unknown> = {
+    name: err.name,
+    message: err.message,
+  };
+
+  if ("code" in err && typeof (err as { code: unknown }).code === "string") {
+    serialized.code = (err as { code: string }).code;
+  }
+
+  if (err.stack) {
+    serialized.stack = err.stack;
+  }
+
+  if (err.cause !== undefined) {
+    serialized.cause = serializeError(err.cause, depth + 1);
+  }
+
+  // Preserve any additional enumerable properties
+  for (const [key, val] of Object.entries(err)) {
+    if (!(key in serialized)) {
+      serialized[key] = val;
+    }
+  }
+
+  return serialized;
+}
+
+// ---------------------------------------------------------------------------
+// Pino serializers
+// ---------------------------------------------------------------------------
+
+export const logSerializers: Record<string, (value: unknown) => unknown> = {
+  err: (err) => redactValue(serializeError(err, 0), 0),
+  req: (req) => redactValue(req, 0),
+  res: (res) => redactValue(res, 0),
+};

package/src/logger.ts

@@ -0,0 +1,143 @@
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  unlinkSync,
+} from "node:fs";
+import { join } from "node:path";
+import pino from "pino";
+import pinoPretty from "pino-pretty";
+import { logSerializers } from "./log-redact.js";
+
+export type LogFileConfig = {
+  dir: string | undefined;
+  retentionDays: number;
+};
+
+const LOG_FILE_PREFIX = "ces-";
+const LOG_FILE_SUFFIX = ".log";
+export const LOG_FILE_PATTERN = /^ces-(\d{4}-\d{2}-\d{2})\.log$/;
+
+function formatDate(date: Date): string {
+  const y = date.getUTCFullYear();
+  const m = String(date.getUTCMonth() + 1).padStart(2, "0");
+  const d = String(date.getUTCDate()).padStart(2, "0");
+  return `${y}-${m}-${d}`;
+}
+
+function logFilePathForDate(dir: string, date: Date): string {
+  return join(dir, `${LOG_FILE_PREFIX}${formatDate(date)}${LOG_FILE_SUFFIX}`);
+}
+
+export function pruneOldLogFiles(dir: string, retentionDays: number): number {
+  if (!existsSync(dir)) return 0;
+
+  const cutoff = new Date();
+  cutoff.setUTCDate(cutoff.getUTCDate() - retentionDays);
+  cutoff.setUTCHours(0, 0, 0, 0);
+
+  let removed = 0;
+  for (const name of readdirSync(dir)) {
+    const match = LOG_FILE_PATTERN.exec(name);
+    if (!match) continue;
+    const fileDate = new Date(match[1] + "T00:00:00Z");
+    if (fileDate < cutoff) {
+      try {
+        unlinkSync(join(dir, name));
+        removed++;
+      } catch {
+        // best-effort
+      }
+    }
+  }
+  return removed;
+}
+
+let rootLogger: pino.Logger | null = null;
+let activeLogDate: string | null = null;
+let activeConfig: LogFileConfig | null = null;
+
+function buildLogger(config: LogFileConfig | null): pino.Logger {
+  if (!config?.dir) {
+    return pino(
+      { name: "ces", serializers: logSerializers },
+      pinoPretty({ destination: 2 }),
+    );
+  }
+
+  if (!existsSync(config.dir)) {
+    mkdirSync(config.dir, { recursive: true });
+  }
+
+  const today = formatDate(new Date());
+  const filePath = logFilePathForDate(config.dir, new Date());
+  const fileStream = pino.destination({
+    dest: filePath,
+    sync: false,
+    mkdir: true,
+    mode: 0o600,
+  });
+  // Tighten permissions on pre-existing log files that may have been created with looser modes
+  try {
+    chmodSync(filePath, 0o600);
+  } catch {
+    /* best-effort */
+  }
+
+  activeLogDate = today;
+  activeConfig = config;
+
+  return pino(
+    { name: "ces", serializers: logSerializers },
+    pino.multistream([
+      { stream: fileStream, level: "info" as const },
+      { stream: pinoPretty({ destination: 2 }), level: "info" as const },
+    ]),
+  );
+}
+
+function ensureCurrentDate(): void {
+  if (!activeConfig?.dir || !activeLogDate) return;
+  const today = formatDate(new Date());
+  if (today !== activeLogDate) {
+    rootLogger = buildLogger(activeConfig);
+  }
+}
+
+export function initLogger(config: LogFileConfig): void {
+  rootLogger = buildLogger(config);
+
+  if (config.dir && config.retentionDays > 0) {
+    const removed = pruneOldLogFiles(config.dir, config.retentionDays);
+    if (removed > 0) {
+      rootLogger.info(
+        { removed, retentionDays: config.retentionDays },
+        "Pruned old log files",
+      );
+    }
+  }
+}
+
+/**
+ * Returns a lazy proxy logger that always delegates to the **current**
+ * rootLogger. This is critical because module-level `const log = getLogger(...)`
+ * calls execute before `initLogger()` runs. Without the proxy, those early
+ * child loggers would permanently hold the fallback stderr-only stream and
+ * never write to log files.
+ */
+export function getLogger(name: string): pino.Logger {
+  const handler: ProxyHandler<pino.Logger> = {
+    get(_target, prop, receiver) {
+      ensureCurrentDate();
+      if (!rootLogger) {
+        rootLogger = buildLogger(null);
+      }
+      const child = rootLogger.child({ module: name });
+      const value = Reflect.get(child, prop, receiver);
+      return typeof value === "function" ? value.bind(child) : value;
+    },
+  };
+  // The proxy target is a throwaway logger — all access is intercepted.
+  return new Proxy({} as pino.Logger, handler);
+}

package/src/main.ts

@@ -41,10 +41,12 @@ import { createLocalOAuthLookup } from "./materializers/local-oauth-lookup.js";
 import { createLocalTokenRefreshFn } from "./materializers/local-token-refresh.js";
 import { resolveLocalSubject } from "./subjects/local.js";
 import { checkCredentialPolicy } from "./subjects/policy.js";
+import { initLogger, getLogger } from "./logger.js";
 import {
   getCesAuditDir,
   getCesDataRoot,
   getCesGrantsDir,
+  getCesLogDir,
   getCesToolStoreDir,
 } from "./paths.js";
 import {
@@ -292,16 +294,16 @@ function buildHandlers(sessionIdRef: SessionIdRef): RpcHandlerRegistry {
 async function main(): Promise<void> {
   ensureDataDirs();
 
-  const log = (msg: string) =>
-    process.stderr.write(`[ces-local] ${msg}\n`);
+  initLogger({ dir: getCesLogDir(), retentionDays: 30 });
+  const log = getLogger("main");
 
-  log(`Starting CES v${CES_PROTOCOL_VERSION} (local mode, stdio transport)`);
+  log.info(`Starting CES v${CES_PROTOCOL_VERSION} (local mode, stdio transport)`);
 
   const controller = new AbortController();
 
   // Graceful shutdown on SIGTERM / SIGINT
   const shutdown = () => {
-    log("Shutting down...");
+    log.info("Shutting down...");
     controller.abort();
   };
   process.on("SIGTERM", shutdown);
@@ -313,17 +315,15 @@ async function main(): Promise<void> {
   const sessionIdRef: SessionIdRef = { current: `ces-local-${Date.now()}` };
   const handlers = buildHandlers(sessionIdRef);
 
+  const rpcLog = getLogger("rpc");
   const server = new CesRpcServer({
     input: process.stdin,
     output: process.stdout,
     handlers,
     logger: {
-      log: (msg: string, ...args: unknown[]) =>
-        process.stderr.write(`[ces-local] ${msg} ${args.map(String).join(" ")}\n`),
-      warn: (msg: string, ...args: unknown[]) =>
-        process.stderr.write(`[ces-local] WARN: ${msg} ${args.map(String).join(" ")}\n`),
-      error: (msg: string, ...args: unknown[]) =>
-        process.stderr.write(`[ces-local] ERROR: ${msg} ${args.map(String).join(" ")}\n`),
+      log: (msg: string, ...args: unknown[]) => rpcLog.info({ args }, msg),
+      warn: (msg: string, ...args: unknown[]) => rpcLog.warn({ args }, msg),
+      error: (msg: string, ...args: unknown[]) => rpcLog.error({ args }, msg),
     },
     signal: controller.signal,
     onHandshakeComplete: (hsSessionId) => {
@@ -334,10 +334,14 @@ async function main(): Promise<void> {
   });
 
   await server.serve();
-  log("Server stopped.");
+  log.info("Server stopped.");
 }
 
 main().catch((err) => {
-  process.stderr.write(`[ces-local] Fatal: ${err}\n`);
+  try {
+    getLogger("main").fatal({ err }, "Fatal error");
+  } catch {
+    process.stderr.write(`[ces-local] Fatal: ${err}\n`);
+  }
   process.exit(1);
 });

package/src/managed-main.ts

@@ -33,11 +33,13 @@ import {
   createRevokeGrantHandler,
 } from "./grants/rpc-handlers.js";
 import { TemporaryGrantStore } from "./grants/temporary-store.js";
+import { initLogger, getLogger } from "./logger.js";
 import {
   getBootstrapSocketPath,
   getCesAuditDir,
   getCesDataRoot,
   getCesGrantsDir,
+  getCesLogDir,
   getCesToolStoreDir,
   getHealthPort,
 } from "./paths.js";
@@ -60,16 +62,16 @@ import { MANAGED_LOCAL_STATIC_REJECTION_ERROR } from "./managed-errors.js";
 import type { SecureKeyBackend } from "@vellumai/credential-storage";
 import { createLocalSecureKeyBackend } from "./materializers/local-secure-key-backend.js";
 import { handleCredentialRoute, type CredentialRouteDeps } from "./http/credential-routes.js";
+import { handleLogExportRoute } from "./http/log-export-routes.js";
 
 // ---------------------------------------------------------------------------
-// Logging (managed always logs to stderr)
+// Logging
 // ---------------------------------------------------------------------------
 
-const log = (msg: string) =>
-  process.stderr.write(`[ces-managed] ${msg}\n`);
-
-const warn = (msg: string) =>
-  process.stderr.write(`[ces-managed] WARN: ${msg}\n`);
+// Module-level logger used before initLogger() runs (early bootstrap) and
+// after it runs (structured file + stderr). Before initLogger() the fallback
+// inside getLogger() writes to stderr only, so early messages still appear.
+const log = getLogger("main");
 
 // ---------------------------------------------------------------------------
 // Data directory bootstrap
@@ -122,7 +124,7 @@ function buildHandlers(sessionIdRef: SessionIdRef, apiKeyRef: ApiKeyRef, assista
     });
 
   if (!platformBaseUrl) {
-    warn(
+    log.warn(
       "VELLUM_PLATFORM_URL not set. " +
         "Managed credential materialisation will depend on the handshake-provided values.",
     );
@@ -388,6 +390,10 @@ function startHealthServer(
         if (credentialResponse) return credentialResponse;
       }
 
+      // Log export route
+      const logExportResponse = await handleLogExportRoute(req, getCesLogDir("managed"));
+      if (logExportResponse) return logExportResponse;
+
       return new Response("Not Found", { status: 404 });
     },
   });
@@ -450,20 +456,20 @@ function acceptOneConnection(
     });
 
     netServer.listen(socketPath, () => {
-      log(`Bootstrap socket listening at ${socketPath}`);
+      log.info(`Bootstrap socket listening at ${socketPath}`);
     });
 
     netServer.on("connection", (socket: Socket) => {
       // Accept exactly one connection, then close the listener and
       // unlink the socket path so no other process can connect.
-      log("Assistant connected via bootstrap socket");
+      log.info("Assistant connected via bootstrap socket");
       netServer.close();
       try {
         unlinkSync(socketPath);
       } catch {
         // Already unlinked
       }
-      log("Bootstrap socket unlinked (single-connection enforced)");
+      log.info("Bootstrap socket unlinked (single-connection enforced)");
 
       const readable = new Readable({
         read() {
@@ -506,13 +512,15 @@ function acceptOneConnection(
 async function main(): Promise<void> {
   ensureDataDirs();
 
-  log(`Starting CES v${CES_PROTOCOL_VERSION} (managed mode)`);
+  initLogger({ dir: getCesLogDir("managed"), retentionDays: 30 });
+
+  log.info(`Starting CES v${CES_PROTOCOL_VERSION} (managed mode)`);
 
   const controller = new AbortController();
 
   // Graceful shutdown
   const shutdown = () => {
-    log("Shutting down...");
+    log.info("Shutting down...");
     controller.abort();
   };
   process.on("SIGTERM", shutdown);
@@ -534,9 +542,9 @@ async function main(): Promise<void> {
 
   if (serviceToken) {
     credentialDeps = { backend: secureKeyBackend, serviceToken };
-    log("Credential CRUD routes enabled (CES_SERVICE_TOKEN configured)");
+    log.info("Credential CRUD routes enabled (CES_SERVICE_TOKEN configured)");
   } else {
-    warn(
+    log.warn(
       "CES_SERVICE_TOKEN not set — credential CRUD HTTP routes are disabled. " +
         "Set CES_SERVICE_TOKEN to enable credential management over HTTP.",
     );
@@ -545,18 +553,18 @@ async function main(): Promise<void> {
   // Start health server on dedicated port
   const healthPort = getHealthPort();
   const healthServer = startHealthServer(healthPort, controller.signal, credentialDeps);
-  log(`Health server listening on port ${healthPort}`);
+  log.info(`Health server listening on port ${healthPort}`);
 
   // Wait for exactly one assistant connection on the bootstrap socket
   const socketPath = getBootstrapSocketPath();
-  log(`Waiting for assistant connection on ${socketPath}...`);
+  log.info(`Waiting for assistant connection on ${socketPath}...`);
 
   let connection: Awaited<ReturnType<typeof acceptOneConnection>>;
   try {
     connection = await acceptOneConnection(socketPath, controller.signal);
   } catch (err) {
     if (controller.signal.aborted) {
-      log("Shutdown before assistant connected.");
+      log.info("Shutdown before assistant connected.");
       return;
     }
     throw err;
@@ -572,36 +580,34 @@ async function main(): Promise<void> {
   const assistantIdRef: AssistantIdRef = { current: process.env["PLATFORM_ASSISTANT_ID"] ?? "" };
   const handlers = buildHandlers(sessionIdRef, apiKeyRef, assistantIdRef, secureKeyBackend);
 
+  const rpcLog = getLogger("rpc");
   const server = new CesRpcServer({
     input: connection.readable,
     output: connection.writable,
     handlers,
     logger: {
-      log: (msg: string, ...args: unknown[]) =>
-        process.stderr.write(`[ces-managed] ${msg} ${args.map(String).join(" ")}\n`),
-      warn: (msg: string, ...args: unknown[]) =>
-        process.stderr.write(`[ces-managed] WARN: ${msg} ${args.map(String).join(" ")}\n`),
-      error: (msg: string, ...args: unknown[]) =>
-        process.stderr.write(`[ces-managed] ERROR: ${msg} ${args.map(String).join(" ")}\n`),
+      log: (msg: string, ...args: unknown[]) => rpcLog.info({ args }, msg),
+      warn: (msg: string, ...args: unknown[]) => rpcLog.warn({ args }, msg),
+      error: (msg: string, ...args: unknown[]) => rpcLog.error({ args }, msg),
     },
     signal: controller.signal,
     onHandshakeComplete: (hsSessionId, hsApiKey, hsAssistantId) => {
       sessionIdRef.current = hsSessionId;
       if (hsApiKey) {
         apiKeyRef.current = hsApiKey;
-        log(`Received assistant API key via handshake`);
+        log.info("Received assistant API key via handshake");
       }
       if (hsAssistantId) {
         assistantIdRef.current = hsAssistantId;
-        log(`Received assistant ID via handshake`);
+        log.info("Received assistant ID via handshake");
       }
     },
     onApiKeyUpdate: (newKey, newAssistantId) => {
       apiKeyRef.current = newKey;
-      log(`Assistant API key updated via RPC`);
+      log.info("Assistant API key updated via RPC");
       if (newAssistantId) {
         assistantIdRef.current = newAssistantId;
-        log(`Assistant ID updated via RPC`);
+        log.info("Assistant ID updated via RPC");
       }
     },
   });
@@ -609,11 +615,15 @@ async function main(): Promise<void> {
   await server.serve();
 
   rpcConnected = false;
-  log("RPC session ended. Shutting down...");
+  log.info("RPC session ended. Shutting down...");
   controller.abort();
 }
 
 main().catch((err) => {
-  process.stderr.write(`[ces-managed] Fatal: ${err}\n`);
+  try {
+    getLogger("main").fatal({ err }, "Fatal error");
+  } catch {
+    process.stderr.write(`[ces-managed] Fatal: ${err}\n`);
+  }
   process.exit(1);
 });

package/src/paths.ts

@@ -95,6 +95,11 @@ export function getCesToolStoreDir(mode?: CesMode): string {
   return join(getCesDataRoot(mode), "toolstore");
 }
 
+/** Directory for CES log files. */
+export function getCesLogDir(mode?: CesMode): string {
+  return join(getCesDataRoot(mode), "logs");
+}
+
 // ---------------------------------------------------------------------------
 // Bootstrap socket path (managed mode only)
 // ---------------------------------------------------------------------------