@botcord/botcord 0.3.6 → 0.3.7

package/src/commands/uninstall.ts

@@ -0,0 +1,129 @@
+/**
+ * CLI: `openclaw botcord-uninstall`
+ *
+ * Safe uninstall that uses OpenClaw's plugin API instead of editing JSON directly.
+ * Prevents the common failure mode where AI agents corrupt openclaw.json.
+ */
+
+export function createUninstallCli() {
+  return {
+    setup: (ctx: any) => {
+      ctx.program
+        .command("botcord-uninstall")
+        .description("Safely uninstall the BotCord plugin")
+        .option("--purge", "Also delete credentials from ~/.botcord/", false)
+        .option("--keep-channel", "Keep channel config in openclaw.json", false)
+        .option("--profile <name>", "OpenClaw profile to target")
+        .option("--dev", "Target the dev profile")
+        .action(async (options: { purge?: boolean; keepChannel?: boolean; profile?: string; dev?: boolean }) => {
+          const { existsSync, rmSync, readdirSync } = await import("node:fs");
+          const { join } = await import("node:path");
+          const { spawnSync } = await import("node:child_process");
+          const { homedir } = await import("node:os");
+
+          const home = homedir();
+          const credDir = join(home, ".botcord", "credentials");
+
+          // Build profile args to forward to openclaw CLI (as array, never shell-interpolated)
+          const profileArgs: string[] = [];
+          if (options.dev) profileArgs.push("--dev");
+          else if (options.profile) {
+            // Validate profile name to prevent injection via spawn args
+            if (!/^[a-zA-Z0-9._-]+$/.test(options.profile)) {
+              ctx.logger.error("Invalid profile name — only alphanumeric, dots, hyphens, and underscores are allowed");
+              return;
+            }
+            profileArgs.push("--profile", options.profile);
+          }
+
+          // Helper: run openclaw CLI safely via spawnSync (no shell interpolation)
+          const oc = (cmdArgs: string[]) =>
+            spawnSync("openclaw", [...profileArgs, ...cmdArgs], { stdio: "pipe", encoding: "utf8" });
+
+          // Resolve extension dir from openclaw CLI if possible, else default
+          let extensionDir = join(home, ".openclaw", "extensions", "botcord");
+          try {
+            const result = oc(["config", "path"]);
+            const configFile = (result.stdout || "").trim();
+            if (configFile) {
+              const configDir = join(configFile, "..");
+              extensionDir = join(configDir, "extensions", "botcord");
+            }
+          } catch {
+            // fall back to default path
+          }
+
+          // Step 1: Disable plugin via OpenClaw CLI (safe — no JSON editing)
+          ctx.logger.info("Disabling BotCord plugin ...");
+          try {
+            const result = oc(["plugins", "disable", "botcord"]);
+            if (result.status === 0) {
+              ctx.logger.info("  Plugin disabled");
+            } else {
+              ctx.logger.warn("  Plugin was not enabled (or already disabled)");
+            }
+          } catch {
+            ctx.logger.warn("  Plugin was not enabled (or already disabled)");
+          }
+
+          // Step 2: Remove channel config via OpenClaw CLI if available
+          if (!options.keepChannel) {
+            ctx.logger.info("Removing channel configuration ...");
+            try {
+              const result = oc(["config", "unset", "channels.botcord"]);
+              if (result.status === 0) {
+                ctx.logger.info("  Channel config removed");
+              } else {
+                ctx.logger.warn("  Could not remove channel config via CLI — may need manual cleanup");
+                ctx.logger.warn("  If needed, remove 'channels.botcord' from openclaw.json");
+              }
+            } catch {
+              ctx.logger.warn("  Could not remove channel config via CLI — may need manual cleanup");
+              ctx.logger.warn("  If needed, remove 'channels.botcord' from openclaw.json");
+            }
+          } else {
+            ctx.logger.info("Keeping channel configuration (--keep-channel)");
+          }
+
+          // Step 3: Remove plugin files
+          if (existsSync(extensionDir)) {
+            ctx.logger.info(`Removing plugin files from ${extensionDir} ...`);
+            rmSync(extensionDir, { recursive: true, force: true });
+            ctx.logger.info("  Plugin files removed");
+          } else {
+            ctx.logger.info("  No plugin files found (already removed)");
+          }
+
+          // Step 4: Optionally purge credentials
+          if (options.purge) {
+            if (existsSync(credDir)) {
+              const files = readdirSync(credDir).filter((f: string) => f.endsWith(".json"));
+              if (files.length > 0) {
+                ctx.logger.info(`Deleting ${files.length} credential file(s) from ${credDir} ...`);
+                for (const f of files) {
+                  rmSync(join(credDir, f), { force: true });
+                  ctx.logger.info(`  Deleted ${f}`);
+                }
+              }
+            } else {
+              ctx.logger.info("  No credentials directory found");
+            }
+          } else {
+            // Show what's preserved
+            if (existsSync(credDir)) {
+              const files = readdirSync(credDir).filter((f: string) => f.endsWith(".json"));
+              if (files.length > 0) {
+                ctx.logger.info(`Credentials preserved in ${credDir} (${files.length} file(s))`);
+                ctx.logger.info("  Use --purge to also delete credentials");
+              }
+            }
+          }
+
+          ctx.logger.info("");
+          ctx.logger.info("BotCord plugin uninstalled.");
+          ctx.logger.info("Restart OpenClaw to apply: openclaw gateway restart");
+        });
+    },
+    commands: ["botcord-uninstall"],
+  };
+}

package/src/credentials.ts

@@ -1,108 +1,26 @@
-import { chmodSync, mkdirSync, readFileSync, writeFileSync, existsSync } from "node:fs";
-import os from "node:os";
-import path from "node:path";
-import { derivePublicKey } from "./crypto.js";
-import { normalizeAndValidateHubUrl } from "./hub-url.js";
+import { existsSync, readFileSync } from "node:fs";
+import {
+  type StoredBotCordCredentials,
+  updateCredentialsToken,
+  loadStoredCredentials,
+  writeCredentialsFile,
+  resolveCredentialsFilePath,
+  defaultCredentialsFile,
+} from "@botcord/protocol-core";
 import type { BotCordAccountConfig } from "./types.js";
 import type { BotCordClient as BotCordClientType } from "./client.js";
 
-export interface StoredBotCordCredentials {
-  version: 1;
-  hubUrl: string;
-  agentId: string;
-  keyId: string;
-  privateKey: string;
-  publicKey: string;
-  displayName?: string;
-  savedAt: string;
-  token?: string;
-  tokenExpiresAt?: number;
-  onboardedAt?: string;
-}
-
-function normalizeCredentialValue(raw: any, keys: string[]): string | undefined {
-  for (const key of keys) {
-    const value = raw?.[key];
-    if (typeof value === "string" && value.trim()) return value;
-  }
-  return undefined;
-}
-
-export function resolveCredentialsFilePath(credentialsFile: string): string {
-  if (credentialsFile === "~") return os.homedir();
-  if (credentialsFile.startsWith("~/")) {
-    return path.join(os.homedir(), credentialsFile.slice(2));
-  }
-  return path.isAbsolute(credentialsFile)
-    ? credentialsFile
-    : path.resolve(credentialsFile);
-}
-
-export function defaultCredentialsFile(agentId: string): string {
-  return path.join(os.homedir(), ".botcord", "credentials", `${agentId}.json`);
-}
-
-function readCredentialSource(credentialsFile: string): Record<string, unknown> {
-  const resolved = resolveCredentialsFilePath(credentialsFile);
-  try {
-    return JSON.parse(readFileSync(resolved, "utf8")) as Record<string, unknown>;
-  } catch (err: any) {
-    throw new Error(`Unable to read BotCord credentials file "${resolved}": ${err.message}`);
-  }
-}
-
-export function loadStoredCredentials(credentialsFile: string): StoredBotCordCredentials {
-  const resolved = resolveCredentialsFilePath(credentialsFile);
-  const raw = readCredentialSource(resolved);
-  const hubUrl = normalizeCredentialValue(raw, ["hubUrl", "hub_url", "hub"]);
-  const agentId = normalizeCredentialValue(raw, ["agentId", "agent_id"]);
-  const keyId = normalizeCredentialValue(raw, ["keyId", "key_id"]);
-  const privateKey = normalizeCredentialValue(raw, ["privateKey", "private_key"]);
-  const publicKey = normalizeCredentialValue(raw, ["publicKey", "public_key"]);
-  const displayName = normalizeCredentialValue(raw, ["displayName", "display_name"]);
-  const savedAt = normalizeCredentialValue(raw, ["savedAt", "saved_at"]);
-  const token = normalizeCredentialValue(raw, ["token"]);
-  const tokenExpiresAt = typeof raw.tokenExpiresAt === "number"
-    ? raw.tokenExpiresAt
-    : typeof raw.token_expires_at === "number"
-      ? raw.token_expires_at
-      : undefined;
+// Re-export core functions so existing plugin imports don't break
+export {
+  type StoredBotCordCredentials,
+  updateCredentialsToken,
+  loadStoredCredentials,
+  writeCredentialsFile,
+  resolveCredentialsFilePath,
+  defaultCredentialsFile,
+} from "@botcord/protocol-core";
 
-  if (!hubUrl) throw new Error(`BotCord credentials file "${resolved}" is missing hubUrl`);
-  if (!agentId) throw new Error(`BotCord credentials file "${resolved}" is missing agentId`);
-  if (!keyId) throw new Error(`BotCord credentials file "${resolved}" is missing keyId`);
-  if (!privateKey) throw new Error(`BotCord credentials file "${resolved}" is missing privateKey`);
-
-  const derivedPublicKey = derivePublicKey(privateKey);
-  if (publicKey && publicKey !== derivedPublicKey) {
-    throw new Error(
-      `BotCord credentials file "${resolved}" has a publicKey that does not match privateKey`,
-    );
-  }
-
-  let normalizedHubUrl: string;
-  try {
-    normalizedHubUrl = normalizeAndValidateHubUrl(hubUrl);
-  } catch (err: any) {
-    throw new Error(`BotCord credentials file "${resolved}" has an invalid hubUrl: ${err.message}`);
-  }
-
-  const onboardedAt = normalizeCredentialValue(raw, ["onboardedAt", "onboarded_at"]);
-
-  return {
-    version: 1,
-    hubUrl: normalizedHubUrl,
-    agentId,
-    keyId,
-    privateKey,
-    publicKey: publicKey || derivedPublicKey,
-    displayName,
-    savedAt: savedAt || new Date().toISOString(),
-    token,
-    tokenExpiresAt,
-    onboardedAt,
-  };
-}
+// Plugin-specific helpers below
 
 export function readCredentialFileData(credentialsFile?: string): Partial<BotCordAccountConfig> {
   if (!credentialsFile) return {};
@@ -123,55 +41,15 @@ export function readCredentialFileData(credentialsFile?: string): Partial<BotCor
   }
 }
 
-export function writeCredentialsFile(
-  credentialsFile: string,
-  credentials: StoredBotCordCredentials,
-): string {
-  const resolved = resolveCredentialsFilePath(credentialsFile);
-  const normalizedCredentials = {
-    ...credentials,
-    hubUrl: normalizeAndValidateHubUrl(credentials.hubUrl),
-  };
-  mkdirSync(path.dirname(resolved), { recursive: true, mode: 0o700 });
-  writeFileSync(resolved, JSON.stringify(normalizedCredentials, null, 2) + "\n", {
-    encoding: "utf8",
-    mode: 0o600,
-  });
-  chmodSync(resolved, 0o600);
-  return resolved;
-}
-
 /**
- * Atomically update only the token fields in an existing credentials file.
- * Reads current file, merges new token/expiresAt, writes back.
- * Returns false if the file does not exist or the write fails.
+ * Check whether the agent completed onboarding under the legacy system
+ * (credentials file contains onboardedAt). Used as a migration bridge
+ * in readOrSeedWorkingMemory() to avoid re-triggering onboarding for
+ * agents that already went through the old flow.
+ *
+ * Read-only — this function never writes to the credentials file.
  */
-export function updateCredentialsToken(
-  credentialsFile: string,
-  token: string,
-  tokenExpiresAt: number,
-): boolean {
-  const resolved = resolveCredentialsFilePath(credentialsFile);
-  try {
-    if (!existsSync(resolved)) return false;
-    const raw = JSON.parse(readFileSync(resolved, "utf8")) as Record<string, unknown>;
-    raw.token = token;
-    raw.tokenExpiresAt = tokenExpiresAt;
-    writeFileSync(resolved, JSON.stringify(raw, null, 2) + "\n", {
-      encoding: "utf8",
-      mode: 0o600,
-    });
-    chmodSync(resolved, 0o600);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Check whether the agent has completed onboarding.
- */
-export function isOnboarded(credentialsFile: string): boolean {
+export function isLegacyOnboarded(credentialsFile: string): boolean {
   const resolved = resolveCredentialsFilePath(credentialsFile);
   try {
     if (!existsSync(resolved)) return false;
@@ -182,26 +60,6 @@ export function isOnboarded(credentialsFile: string): boolean {
   }
 }
 
-/**
- * Mark the agent as onboarded by writing onboardedAt timestamp.
- */
-export function markOnboarded(credentialsFile: string): boolean {
-  const resolved = resolveCredentialsFilePath(credentialsFile);
-  try {
-    if (!existsSync(resolved)) return false;
-    const raw = JSON.parse(readFileSync(resolved, "utf8")) as Record<string, unknown>;
-    raw.onboardedAt = new Date().toISOString();
-    writeFileSync(resolved, JSON.stringify(raw, null, 2) + "\n", {
-      encoding: "utf8",
-      mode: 0o600,
-    });
-    chmodSync(resolved, 0o600);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
 /**
  * Attach token persistence to a BotCordClient.
  * If the account was loaded from a credentialsFile, refreshed tokens

package/src/crypto.ts

@@ -1,155 +1 @@
-/**
- * Ed25519 signing for BotCord protocol.
- * Zero npm dependencies — uses Node.js built-in crypto module.
- * Ported from botcord-skill/skill/botcord-crypto.mjs.
- */
-import {
-  createHash,
-  createPublicKey,
-  createPrivateKey,
-  generateKeyPairSync,
-  sign,
-  randomUUID,
-} from "node:crypto";
-import type { BotCordMessageEnvelope, BotCordSignature, MessageType } from "./types.js";
-
-// ── JCS (RFC 8785) canonicalization ─────────────────────────────
-export function jcsCanonicalize(value: unknown): string | undefined {
-  if (value === null || typeof value === "boolean") return JSON.stringify(value);
-  if (typeof value === "number") {
-    if (Object.is(value, -0)) return "0";
-    return JSON.stringify(value);
-  }
-  if (typeof value === "string") return JSON.stringify(value);
-  if (Array.isArray(value))
-    return "[" + value.map((v) => jcsCanonicalize(v)).join(",") + "]";
-  if (typeof value === "object") {
-    const keys = Object.keys(value as Record<string, unknown>).sort();
-    const parts: string[] = [];
-    for (const k of keys) {
-      const v = (value as Record<string, unknown>)[k];
-      if (v === undefined) continue;
-      parts.push(JSON.stringify(k) + ":" + jcsCanonicalize(v));
-    }
-    return "{" + parts.join(",") + "}";
-  }
-  return undefined;
-}
-
-// ── Build Node.js KeyObject from raw 32-byte seed ───────────────
-function privateKeyFromSeed(seed: Buffer): ReturnType<typeof createPrivateKey> {
-  const prefix = Buffer.from("302e020100300506032b657004220420", "hex");
-  return createPrivateKey({
-    key: Buffer.concat([prefix, seed]),
-    format: "der",
-    type: "pkcs8",
-  });
-}
-
-// ── Payload hash ────────────────────────────────────────────────
-export function computePayloadHash(payload: Record<string, unknown>): string {
-  const canonical = jcsCanonicalize(payload)!;
-  const digest = createHash("sha256").update(canonical).digest("hex");
-  return `sha256:${digest}`;
-}
-
-// ── Sign challenge ──────────────────────────────────────────────
-export function signChallenge(privateKeyB64: string, challengeB64: string): string {
-  const pk = privateKeyFromSeed(Buffer.from(privateKeyB64, "base64"));
-  const sig = sign(null, Buffer.from(challengeB64, "base64"), pk);
-  return sig.toString("base64");
-}
-
-export function derivePublicKey(privateKeyB64: string): string {
-  const privateKey = privateKeyFromSeed(Buffer.from(privateKeyB64, "base64"));
-  const publicKey = createPublicKey(privateKey);
-  const pubDer = publicKey.export({ type: "spki", format: "der" });
-  return Buffer.from(pubDer.subarray(-32)).toString("base64");
-}
-
-// ── Build and sign a full message envelope ──────────────────────
-export function buildSignedEnvelope(params: {
-  from: string;
-  to: string;
-  type: MessageType;
-  payload: Record<string, unknown>;
-  privateKey: string; // base64 Ed25519 seed
-  keyId: string;
-  replyTo?: string | null;
-  ttlSec?: number;
-  topic?: string | null;
-  goal?: string | null;
-}): BotCordMessageEnvelope {
-  const {
-    from,
-    to,
-    type,
-    payload,
-    privateKey,
-    keyId,
-    replyTo = null,
-    ttlSec = 3600,
-    topic = null,
-    goal = null,
-  } = params;
-
-  const msgId = randomUUID();
-  const ts = Math.floor(Date.now() / 1000);
-  const payloadHash = computePayloadHash(payload);
-
-  // Build signing input (newline-joined fields)
-  const parts = [
-    "a2a/0.1",
-    msgId,
-    String(ts),
-    from,
-    to,
-    String(type),
-    replyTo || "",
-    String(ttlSec),
-    payloadHash,
-  ];
-
-  const pk = privateKeyFromSeed(Buffer.from(privateKey, "base64"));
-  const sigValue = sign(null, Buffer.from(parts.join("\n")), pk);
-
-  const sig: BotCordSignature = {
-    alg: "ed25519",
-    key_id: keyId,
-    value: sigValue.toString("base64"),
-  };
-
-  return {
-    v: "a2a/0.1",
-    msg_id: msgId,
-    ts,
-    from,
-    to,
-    type,
-    reply_to: replyTo,
-    ttl_sec: ttlSec,
-    topic,
-    goal,
-    payload,
-    payload_hash: payloadHash,
-    sig,
-  };
-}
-
-// ── Keygen ──────────────────────────────────────────────────────
-export function generateKeypair(): {
-  privateKey: string;
-  publicKey: string;
-  pubkeyFormatted: string;
-} {
-  const { publicKey, privateKey } = generateKeyPairSync("ed25519");
-  const privDer = privateKey.export({ type: "pkcs8", format: "der" });
-  const privB64 = Buffer.from(privDer.subarray(-32)).toString("base64");
-  const pubDer = publicKey.export({ type: "spki", format: "der" });
-  const pubB64 = Buffer.from(pubDer.subarray(-32)).toString("base64");
-  return {
-    privateKey: privB64,
-    publicKey: pubB64,
-    pubkeyFormatted: `ed25519:${pubB64}`,
-  };
-}
+export * from "@botcord/protocol-core";

package/src/dynamic-context.ts

@@ -16,12 +16,13 @@
  * out of the box with zero config.
  */
 import { buildCrossRoomDigest, getSessionRoom } from "./room-context.js";
-import { readWorkingMemory } from "./memory.js";
+import { readWorkingMemory, readOrSeedWorkingMemory } from "./memory.js";
 import { buildWorkingMemoryPrompt } from "./memory-protocol.js";
 import {
   buildBotCordLoopRiskPrompt,
   shouldRunBotCordLoopRiskCheck,
 } from "./loop-risk.js";
+import type { BotCordClient as BotCordClientType } from "./client.js";
 
 /**
  * Build the dynamic context for a BotCord session.
@@ -35,32 +36,48 @@ export async function buildDynamicContext(params: {
   prompt?: string;
   messages?: unknown[];
   trigger?: string;
+  client?: BotCordClientType;
+  credentialsFile?: string;
 }): Promise<string | null> {
-  const { sessionKey, channelId, prompt, messages, trigger } = params;
+  const { sessionKey, channelId, prompt, messages, trigger, client, credentialsFile } = params;
 
   const isOwnerChat = sessionKey === "botcord:owner:main";
   const isBotCordSession = isOwnerChat || !!getSessionRoom(sessionKey);
 
-  if (!isBotCordSession) return null;
-
-  const parts: string[] = [];
-
-  // 1. Cross-room activity digest
-  const digest = await buildCrossRoomDigest(sessionKey);
-  if (digest) parts.push(digest);
-
-  // 2. Working memory
+  // Read working memory early — needed both for injection and for the
+  // onboarding gate decision below.
+  let wm: Awaited<ReturnType<typeof readOrSeedWorkingMemory>> = null;
   try {
-    const wm = readWorkingMemory();
-    const memoryPrompt = buildWorkingMemoryPrompt({ workingMemory: wm });
-    parts.push(memoryPrompt);
+    wm = client
+      ? await readOrSeedWorkingMemory({ client, credentialsFile })
+      : readWorkingMemory();
   } catch (err: unknown) {
     const msg = err instanceof Error ? err.message : String(err);
     console.warn("[botcord] dynamic-context: failed to read working memory:", msg);
   }
 
-  // 3. Loop-risk guard
-  if (prompt && shouldRunBotCordLoopRiskCheck({
+  const onboardingPending = !!wm?.sections?.onboarding;
+
+  // Gate: inject context for BotCord sessions unconditionally, but also
+  // for ANY session while onboarding is still pending — so the agent can
+  // start/continue onboarding from Telegram, Discord, webchat, etc.
+  if (!isBotCordSession && !onboardingPending) return null;
+
+  const parts: string[] = [];
+
+  // 1. Cross-room activity digest (BotCord sessions only — not relevant
+  //    for non-BotCord sessions during onboarding)
+  if (isBotCordSession) {
+    const digest = await buildCrossRoomDigest(sessionKey);
+    if (digest) parts.push(digest);
+  }
+
+  // 2. Working memory
+  const memoryPrompt = buildWorkingMemoryPrompt({ workingMemory: wm });
+  parts.push(memoryPrompt);
+
+  // 3. Loop-risk guard (BotCord sessions only)
+  if (isBotCordSession && prompt && shouldRunBotCordLoopRiskCheck({
     channelId: channelId ?? "botcord",
     prompt,
     trigger,

package/src/hub-url.ts

@@ -1,41 +1 @@
-const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "::1"]);
-
-function isLoopbackHost(hostname: string): boolean {
-  const normalized = hostname.toLowerCase().replace(/^\[(.*)\]$/, "$1");
-  return LOOPBACK_HOSTS.has(normalized) || normalized.endsWith(".localhost");
-}
-
-export function normalizeAndValidateHubUrl(hubUrl: string): string {
-  const trimmed = hubUrl.trim();
-  if (!trimmed) {
-    throw new Error("BotCord hubUrl is required");
-  }
-
-  let parsed: URL;
-  try {
-    parsed = new URL(trimmed);
-  } catch {
-    throw new Error(`BotCord hubUrl must be a valid absolute URL: ${hubUrl}`);
-  }
-
-  if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
-    throw new Error("BotCord hubUrl must use http:// or https://");
-  }
-
-  if (parsed.protocol === "http:" && !isLoopbackHost(parsed.hostname)) {
-    throw new Error(
-      "BotCord hubUrl must use https:// unless it targets localhost, 127.0.0.1, or ::1 for local development",
-    );
-  }
-
-  return trimmed.replace(/\/$/, "");
-}
-
-export function buildHubWebSocketUrl(hubUrl: string): string {
-  const parsed = new URL(normalizeAndValidateHubUrl(hubUrl));
-  parsed.protocol = parsed.protocol === "https:" ? "wss:" : "ws:";
-  parsed.search = "";
-  parsed.hash = "";
-  parsed.pathname = `${parsed.pathname.replace(/\/$/, "")}/hub/ws`;
-  return parsed.toString();
-}
+export * from "@botcord/protocol-core";

package/src/memory.ts

@@ -12,6 +12,8 @@ import path from "node:path";
 import os from "node:os";
 import { getBotCordRuntime, getConfig } from "./runtime.js";
 import { resolveAccountConfig } from "./config.js";
+import { isLegacyOnboarded } from "./credentials.js";
+import type { BotCordClient as BotCordClientType } from "./client.js";
 
 // ── Types ──────────────────────────────────────────────────────────
 
@@ -197,6 +199,54 @@ export function writeWorkingMemory(
   writeJsonFileAtomic(workingMemoryPath(memDir), data);
 }
 
+// ── Seed (lazy init) ──────────────────────────────────────────────
+
+/**
+ * Read working memory with lazy seed from Hub API.
+ *
+ * If local memory file does not exist:
+ * 1. Check the legacy onboardedAt flag → skip seed if set (migration bridge).
+ * 2. Fetch default memory from GET /hub/memory/default.
+ * 3. Write the seed to local file and return it.
+ *
+ * This is the ONLY entry point that should be used on the "display path"
+ * (i.e., injecting memory into the agent prompt). Write-tool internal reads
+ * (read-before-update) should continue using readWorkingMemory() directly.
+ */
+export async function readOrSeedWorkingMemory(params: {
+  client: BotCordClientType;
+  credentialsFile?: string;
+  memDir?: string;
+}): Promise<WorkingMemory | null> {
+  const { client, credentialsFile, memDir } = params;
+
+  // 1. Local file exists → return as-is
+  const existing = readWorkingMemory(memDir);
+  if (existing) return existing;
+
+  // 2. Migration bridge: agent already onboarded under legacy system → skip seed
+  if (credentialsFile && isLegacyOnboarded(credentialsFile)) return null;
+
+  // 3. Fetch seed from Hub API
+  try {
+    const seed = await client.getDefaultMemory();
+    if (seed && typeof seed === "object" && seed.version === 2) {
+      const wm: WorkingMemory = {
+        version: 2,
+        goal: typeof seed.goal === "string" ? seed.goal : undefined,
+        sections: seed.sections && typeof seed.sections === "object" ? seed.sections as Record<string, string> : {},
+        updatedAt: new Date().toISOString(),
+      };
+      writeWorkingMemory(wm, memDir);
+      return wm;
+    }
+  } catch {
+    // Offline / network error → no onboarding guidance, but don't block
+  }
+
+  return null;
+}
+
 // ── Room State ─────────────────────────────────────────────────────
 
 function roomStatePath(roomId: string, memDir?: string): string {