@botcord/botcord 0.3.2-beta.20260407032921 → 0.3.2

package/src/room-context.ts

@@ -10,6 +10,7 @@
 import { getBotCordRuntime, getConfig } from "./runtime.js";
 import { resolveAccountConfig, resolveChannelConfig, resolveAccounts, isAccountConfigured } from "./config.js";
 import { attachTokenPersistence } from "./credentials.js";
+import { sanitizeUntrustedContent } from "./sanitize.js";
 import type { RoomInfo } from "./types.js";
 
 // ── Session ↔ Room mapping ──────────────────────────────────────
@@ -117,21 +118,26 @@ export async function buildRoomStaticContext(
   if (!cached) return null;
 
   const { room, members } = cached;
+  // Sanitize all tenant-controlled fields to prevent prompt injection
+  // via room metadata that lands in appendSystemContext.
+  // Strip newlines from single-line fields (name, member names) to
+  // prevent structural reshaping of the system prompt.
+  const safeName = sanitizeUntrustedContent((room.name || "").replace(/[\r\n]+/g, " "));
   const lines: string[] = [
     `[BotCord Room Context]`,
-    `Room: ${room.name} (${room.room_id})`,
+    `Room: ${safeName} (${room.room_id})`,
   ];
   if (room.description) {
-    lines.push(`Description: ${room.description}`);
+    lines.push(`Description: ${sanitizeUntrustedContent(room.description)}`);
   }
   if (room.rule) {
-    lines.push(`Rule: ${room.rule}`);
+    lines.push(`Rule: ${sanitizeUntrustedContent(room.rule)}`);
   }
   lines.push(`Visibility: ${room.visibility}, Join: ${room.join_policy}`);
 
   const memberList = members
     .map((m) => {
-      const name = m.display_name || m.agent_id;
+      const name = sanitizeUntrustedContent((m.display_name || m.agent_id).replace(/[\r\n]+/g, " "));
       return m.role && m.role !== "member" ? `${name} (${m.role})` : name;
     })
     .join(", ");
@@ -184,7 +190,10 @@ export async function buildCrossRoomDigest(
   ];
 
   for (const { key, entry } of toDigest) {
-    const roomLabel = entry.roomName || entry.roomId;
+    // Sanitize room label — tenant-controlled name could contain
+    // injection markers or newlines that reshape the digest structure.
+    const rawLabel = entry.roomName || entry.roomId;
+    const roomLabel = sanitizeUntrustedContent(rawLabel.replace(/[\r\n]+/g, " "));
     const isDm = entry.roomId.startsWith("rm_dm_");
     const typeLabel = isDm ? "DM" : "Room";
 
@@ -199,13 +208,28 @@ export async function buildCrossRoomDigest(
         continue;
       }
 
-      // Extract a brief summary from the last messages
+      // Extract a brief summary from the last messages.
+      // Sanitize previews to neutralize prompt injection from other rooms.
       const previews = messages
         .slice(-3)
         .map((msg: any) => {
           const role = msg.role || "unknown";
-          const text = (msg.content || msg.text || "").slice(0, 120);
-          return `  [${role}] ${text}${text.length >= 120 ? "…" : ""}`;
+          // Content may be a string, an array of content blocks, or
+          // missing. Coerce safely to avoid throwing on non-string shapes.
+          let rawText: string;
+          const c = msg.content ?? msg.text ?? "";
+          if (typeof c === "string") {
+            rawText = c;
+          } else if (Array.isArray(c)) {
+            rawText = c
+              .map((part: any) => (typeof part === "string" ? part : part?.text ?? ""))
+              .join(" ");
+          } else {
+            rawText = String(c);
+          }
+          const truncated = rawText.slice(0, 120);
+          const text = sanitizeUntrustedContent(truncated);
+          return `  [${role}] ${text}${rawText.length > 120 ? "…" : ""}`;
         })
         .join("\n");
 
@@ -250,14 +274,17 @@ function buildOwnerChatSceneContext(): string {
 // ── Combined hook handler ───────────────────────────────────────
 
 /**
- * before_prompt_build handler that injects room context.
- * Returns appendSystemContext (static, cacheable) and prependContext (dynamic).
+ * before_prompt_build handler that injects static room context only.
+ *
+ * Returns appendSystemContext (cacheable) for room metadata and
+ * owner-chat scene description. Dynamic context (cross-room digest,
+ * working memory, loop-risk) is now handled by the context engine
+ * in context-engine.ts to avoid polluting session transcript.
  */
-export async function buildRoomContextHookResult(
+export async function buildRoomStaticContextHookResult(
   sessionKey: string | undefined,
 ): Promise<{
   appendSystemContext?: string;
-  prependContext?: string;
 } | null> {
   if (!sessionKey) return null;
 
@@ -273,20 +300,8 @@ export async function buildRoomContextHookResult(
   // custom-routed keys that don't carry the prefix.
   if (!sessionRoomMap.has(sessionKey)) return null;
 
-  const result: { appendSystemContext?: string; prependContext?: string } = {};
-
-  // Layer 1: Static room context (cacheable)
+  // Static room context (cacheable)
   const staticCtx = await buildRoomStaticContext(sessionKey);
-  if (staticCtx) {
-    result.appendSystemContext = staticCtx;
-  }
-
-  // Layer 2: Cross-room activity digest (dynamic, per-turn)
-  const digest = await buildCrossRoomDigest(sessionKey);
-  if (digest) {
-    result.prependContext = digest;
-  }
-
-  if (!result.appendSystemContext && !result.prependContext) return null;
-  return result;
+  if (!staticCtx) return null;
+  return { appendSystemContext: staticCtx };
 }

package/src/tools/notify.ts

@@ -4,9 +4,12 @@
  * is important enough to warrant notifying the owner.
  */
 import { getBotCordRuntime } from "../runtime.js";
-import { getConfig as getAppConfig } from "../runtime.js";
-import { getSingleAccountModeError, resolveAccountConfig } from "../config.js";
 import { deliverNotification, normalizeNotifySessions } from "../inbound.js";
+import { isAccountConfigured } from "../config.js";
+import { BotCordClient } from "../client.js";
+import { attachTokenPersistence } from "../credentials.js";
+import { withConfig } from "./with-client.js";
+import { validationError } from "./tool-result.js";
 
 export function createNotifyTool() {
   return {
@@ -28,40 +31,54 @@ export function createNotifyTool() {
       required: ["text"],
     },
     execute: async (toolCallId: any, args: any) => {
-      const cfg = getAppConfig();
-      if (!cfg) return { error: "No configuration available" };
-      const singleAccountError = getSingleAccountModeError(cfg);
-      if (singleAccountError) return { error: singleAccountError };
+      return withConfig(async (cfg, acct) => {
+        const sessions = normalizeNotifySessions(acct.notifySession);
+        const hasAccount = isAccountConfigured(acct);
 
-      const acct = resolveAccountConfig(cfg);
-      const sessions = normalizeNotifySessions(acct.notifySession);
-      if (sessions.length === 0) {
-        return { error: "notifySession is not configured in channels.botcord" };
-      }
+        if (sessions.length === 0 && !hasAccount) {
+          return validationError(
+            "No notification channel available. Configure notifySession in channels.botcord or register a BotCord account.",
+          );
+        }
+
+        const core = getBotCordRuntime();
+        const text = typeof args.text === "string" ? args.text.trim() : "";
+        if (!text) {
+          return validationError("text is required");
+        }
 
-      const core = getBotCordRuntime();
-      const text = typeof args.text === "string" ? args.text.trim() : "";
-      if (!text) {
-        return { error: "text is required" };
-      }
+        const errors: string[] = [];
+        const channels: string[] = [];
 
-      const errors: string[] = [];
-      for (const ns of sessions) {
-        try {
-          await deliverNotification(core, cfg, ns, text);
-        } catch (err: any) {
-          errors.push(`${ns}: ${err?.message ?? err}`);
+        for (const ns of sessions) {
+          try {
+            await deliverNotification(core, cfg, ns, text);
+            channels.push(ns);
+          } catch (err: any) {
+            errors.push(`${ns}: ${err?.message ?? err}`);
+          }
         }
-      }
 
-      if (errors.length > 0) {
-        return {
-          ok: errors.length < sessions.length,
-          notifySessions: sessions,
-          errors,
-        };
-      }
-      return { ok: true, notifySessions: sessions };
+        // Also push notification to owner's dashboard via Hub API
+        if (hasAccount) {
+          try {
+            const client = new BotCordClient(acct);
+            attachTokenPersistence(client, acct);
+            await client.notifyOwner(text);
+            channels.push("owner-chat");
+          } catch (err: any) {
+            errors.push(`owner-chat: ${err?.message ?? err}`);
+          }
+        }
+
+        if (channels.length === 0) {
+          return { ok: false, errors };
+        }
+        if (errors.length > 0) {
+          return { ok: true, channels, errors };
+        }
+        return { ok: true, channels };
+      });
     },
   };
 }

package/src/tools/tool-result.ts

@@ -0,0 +1,119 @@
+/**
+ * Structured tool result types and builder helpers.
+ *
+ * Provides a unified response envelope for all BotCord tools:
+ * - Success: { ok: true, ...data }
+ * - Failure: { ok: false, error: { type, code, message, hint? } }
+ * - DryRun:  { ok: true, dry_run: true, request: { method, path, body? } }
+ */
+
+// ── Error types ─────────────────────────────────────────────────
+
+export type ToolErrorType = "config" | "auth" | "validation" | "api" | "network";
+
+export interface ToolError {
+  type: ToolErrorType;
+  code: string;
+  message: string;
+  hint?: string;
+}
+
+// ── Result types ────────────────────────────────────────────────
+
+export type ToolSuccess<T = Record<string, unknown>> = { ok: true } & T;
+export type ToolFailure = { ok: false; error: ToolError };
+export type ToolResult<T = Record<string, unknown>> = ToolSuccess<T> | ToolFailure;
+
+export interface DryRunRequest {
+  method: string;
+  path: string;
+  body?: unknown;
+  query?: Record<string, string>;
+}
+
+export type DryRunResult = { ok: true; dry_run: true; request: DryRunRequest };
+
+// ── Builder helpers ─────────────────────────────────────────────
+
+export function success<T extends Record<string, unknown>>(data: T): ToolSuccess<T> {
+  return { ok: true, ...data };
+}
+
+export function fail(
+  type: ToolErrorType,
+  code: string,
+  message: string,
+  hint?: string,
+): ToolFailure {
+  return { ok: false, error: { type, code, message, ...(hint ? { hint } : {}) } };
+}
+
+export function configError(message: string, hint?: string): ToolFailure {
+  return fail("config", "NOT_CONFIGURED", message, hint);
+}
+
+export function validationError(message: string, hint?: string): ToolFailure {
+  return fail("validation", "INVALID_INPUT", message, hint);
+}
+
+export function apiError(code: string, message: string, hint?: string): ToolFailure {
+  return fail("api", code, message, hint);
+}
+
+export function dryRunResult(method: string, path: string, body?: unknown, query?: Record<string, string>): DryRunResult {
+  return {
+    ok: true,
+    dry_run: true,
+    request: { method, path, ...(body !== undefined ? { body } : {}), ...(query ? { query } : {}) },
+  };
+}
+
+// ── Error classifier ────────────────────────────────────────────
+
+import { HubApiError } from "../client.js";
+
+/**
+ * Classify a caught error into a structured ToolFailure.
+ * Uses HubApiError's typed status and code properties.
+ */
+export function classifyError(err: unknown): ToolFailure {
+  if (!(err instanceof Error)) {
+    return fail("api", "UNKNOWN", String(err));
+  }
+
+  const message = err.message;
+
+  // Network-level failures
+  if (
+    err.name === "AbortError" ||
+    message.includes("fetch failed") ||
+    message.includes("ECONNREFUSED") ||
+    message.includes("ENOTFOUND") ||
+    message.includes("network")
+  ) {
+    return fail("network", "CONNECTION_FAILED", message, "Check Hub URL and network connectivity");
+  }
+
+  // Typed Hub API errors
+  if (err instanceof HubApiError) {
+    const { status, code } = err;
+    switch (status) {
+      case 401:
+        return fail("auth", "TOKEN_EXPIRED", message, "Token refresh may have failed — try again or re-register");
+      case 403:
+        return fail("auth", code || "FORBIDDEN", message);
+      case 404:
+        return fail("api", "NOT_FOUND", message, "Verify the target ID exists via botcord_directory(action=\"resolve\")");
+      case 409:
+        return fail("api", "CONFLICT", message);
+      case 422:
+        return fail("validation", "UNPROCESSABLE", message);
+      case 429:
+        return fail("api", "RATE_LIMITED", message, "Throttle requests — 20 msg/min global, 10 msg/min per conversation");
+      default:
+        return fail("api", code || `HTTP_${status}`, message);
+    }
+  }
+
+  return fail("api", "UNKNOWN", message);
+}

package/src/tools/with-client.ts

@@ -0,0 +1,93 @@
+/**
+ * Shared tool wrapper that eliminates boilerplate across all BotCord tools.
+ *
+ * Handles: config check → single-account guard → account resolution →
+ * client creation → token persistence → try/catch with error classification.
+ */
+import {
+  getSingleAccountModeError,
+  resolveAccountConfig,
+  isAccountConfigured,
+} from "../config.js";
+import { BotCordClient } from "../client.js";
+import { attachTokenPersistence } from "../credentials.js";
+import { getConfig as getAppConfig } from "../runtime.js";
+import type { BotCordAccountConfig } from "../types.js";
+import { configError, classifyError, type ToolResult, type DryRunResult } from "./tool-result.js";
+
+/**
+ * Run a tool action with a fully-configured BotCordClient.
+ *
+ * The callback receives the client and resolved account config.
+ * If it returns a plain object, it is automatically wrapped in `{ ok: true, ... }`.
+ * If it returns an object that already has `ok` set, it is passed through as-is.
+ */
+export async function withClient(
+  fn: (client: BotCordClient, acct: BotCordAccountConfig) => Promise<ToolResult | DryRunResult | Record<string, unknown>>,
+): Promise<ToolResult | DryRunResult> {
+  const cfg = getAppConfig();
+  if (!cfg) {
+    return configError("No configuration available", "Run /botcord_healthcheck to diagnose");
+  }
+
+  const singleErr = getSingleAccountModeError(cfg);
+  if (singleErr) {
+    return configError(singleErr);
+  }
+
+  const acct = resolveAccountConfig(cfg);
+  if (!isAccountConfigured(acct)) {
+    return configError(
+      "BotCord is not configured.",
+      "Run botcord-register to create an identity or botcord-import to restore one",
+    );
+  }
+
+  try {
+    const client = new BotCordClient(acct);
+    attachTokenPersistence(client, acct);
+    const result = await fn(client, acct);
+
+    // If the callback already returned a structured result, pass through
+    if (result && typeof result === "object" && "ok" in result) {
+      return result as ToolResult | DryRunResult;
+    }
+
+    // Otherwise wrap in success envelope
+    return { ok: true as const, ...result };
+  } catch (err: unknown) {
+    return classifyError(err);
+  }
+}
+
+/**
+ * Lightweight version that only checks config availability (no client creation).
+ * Used by tools that don't need a BotCordClient (e.g. register, notify).
+ */
+export async function withConfig(
+  fn: (cfg: any, acct: BotCordAccountConfig) => Promise<ToolResult | DryRunResult | Record<string, unknown>>,
+): Promise<ToolResult | DryRunResult> {
+  const cfg = getAppConfig();
+  if (!cfg) {
+    return configError("No configuration available", "Run /botcord_healthcheck to diagnose");
+  }
+
+  const singleErr = getSingleAccountModeError(cfg);
+  if (singleErr) {
+    return configError(singleErr);
+  }
+
+  const acct = resolveAccountConfig(cfg);
+
+  try {
+    const result = await fn(cfg, acct);
+
+    if (result && typeof result === "object" && "ok" in result) {
+      return result as ToolResult | DryRunResult;
+    }
+
+    return { ok: true as const, ...result };
+  } catch (err: unknown) {
+    return classifyError(err);
+  }
+}

package/src/tools/working-memory.ts

@@ -1,54 +1,143 @@
 /**
  * botcord_update_working_memory — explicit tool for persisting working memory.
+ *
+ * Supports named sections for granular updates:
+ * - { goal: "..." }                         → update goal only
+ * - { section: "contacts", content: "..." } → update one section
+ * - { content: "..." }                      → update default "notes" section
+ * - { section: "old", content: "" }          → delete a section
  */
-import { writeWorkingMemory } from "../memory.js";
+import { readWorkingMemory, writeWorkingMemory } from "../memory.js";
 
-const MAX_WORKING_MEMORY_CHARS = 20_000;
+const MAX_SECTION_CHARS = 10_000;
+const MAX_GOAL_CHARS = 500;
+const MAX_TOTAL_CHARS = 20_000;
+const DEFAULT_SECTION = "notes";
 
 export function createWorkingMemoryTool() {
   return {
     name: "botcord_update_working_memory",
     label: "Update Working Memory",
     description:
-      "Replace BotCord's persistent working memory with the complete new content. " +
-      "Use only when important long-lived context changes, such as a stable fact, preference, person profile, relationship, or pending commitment that should influence future replies. " +
-      "Do not call on every turn, and do not use it for one-off chatter or room-local temporary state.",
+      "Update BotCord's persistent working memory. Memory is organized into named sections " +
+      "that are updated independently — changing one section never affects others. " +
+      "Pass 'goal' to set your work goal (pinned, survives all updates). " +
+      "Pass 'section' + 'content' to update a specific section. " +
+      "Pass only 'content' to update the default 'notes' section. " +
+      "Pass 'section' with empty 'content' to delete a section. " +
+      "Use clear section names like 'contacts', 'pending_tasks', 'preferences' (letters, digits, underscores only).",
     parameters: {
       type: "object" as const,
       properties: {
+        goal: {
+          type: "string" as const,
+          description:
+            "Set or update the agent's work goal. This is pinned and never lost when sections are updated. " +
+            `Max ${MAX_GOAL_CHARS} characters.`,
+        },
+        section: {
+          type: "string" as const,
+          description:
+            "Name of the section to update (e.g. 'contacts', 'pending_tasks', 'preferences'). " +
+            `Defaults to '${DEFAULT_SECTION}' if not specified.`,
+        },
         content: {
           type: "string" as const,
           description:
-            "The complete replacement content for working memory. " +
-            "Keep it concise and include only important facts, stable preferences, durable person/relationship context, pending commitments, and other key context that should persist across sessions and rooms.",
+            "The complete replacement content for the specified section. " +
+            "Pass empty string to delete the section. " +
+            `Max ${MAX_SECTION_CHARS} characters per section.`,
         },
       },
-      required: ["content"],
+      required: [],
     },
     execute: async (_toolCallId: any, args: any) => {
-      if (typeof args?.content !== "string") {
-        return { error: "content must be a string" };
+      // Type validation — reject wrong types explicitly
+      if (args?.goal !== undefined && typeof args.goal !== "string") {
+        return { error: "'goal' must be a string" };
+      }
+      if (args?.section !== undefined && typeof args.section !== "string") {
+        return { error: "'section' must be a string" };
+      }
+      if (args?.content !== undefined && typeof args.content !== "string") {
+        return { error: "'content' must be a string" };
+      }
+
+      const goalArg = typeof args?.goal === "string" ? args.goal.trim() : undefined;
+      const sectionArg = typeof args?.section === "string" ? args.section.trim() : undefined;
+      const contentArg = typeof args?.content === "string" ? args.content : undefined;
+
+      // Must provide at least one of goal or content
+      if (goalArg === undefined && contentArg === undefined) {
+        return { error: "Must provide at least 'goal' or 'content'" };
       }
 
-      const content = args.content.trim();
-      if (!content) {
-        return { error: "content must not be empty — use a separate mechanism to clear memory" };
+      // Validate goal
+      if (goalArg !== undefined && goalArg.length > MAX_GOAL_CHARS) {
+        return { error: `goal exceeds ${MAX_GOAL_CHARS} characters` };
       }
-      if (content.length > MAX_WORKING_MEMORY_CHARS) {
-        return { error: `content exceeds ${MAX_WORKING_MEMORY_CHARS} characters` };
+
+      // Validate section name
+      const sectionName = sectionArg || DEFAULT_SECTION;
+      if (!/^[a-zA-Z0-9_]+$/.test(sectionName)) {
+        return { error: "section name must contain only letters, digits, and underscores" };
+      }
+
+      // Validate content
+      const content = contentArg?.trim() ?? undefined;
+      if (content !== undefined && content.length > MAX_SECTION_CHARS) {
+        return { error: `content exceeds ${MAX_SECTION_CHARS} characters for section '${sectionName}'` };
       }
 
       try {
-        writeWorkingMemory({
-          version: 1,
-          content,
-          updatedAt: new Date().toISOString(),
-        });
-        return {
+        // Read existing memory (or start fresh)
+        const existing = readWorkingMemory() ?? {
+          version: 2 as const,
+          sections: {},
+          updatedAt: "",
+        };
+
+        // Update goal if provided
+        if (goalArg !== undefined) {
+          existing.goal = goalArg || undefined;
+        }
+
+        // Update section if content provided
+        if (content !== undefined) {
+          if (content === "") {
+            delete existing.sections[sectionName];
+          } else {
+            existing.sections[sectionName] = content;
+          }
+        }
+
+        // Check total size
+        const totalChars =
+          (existing.goal?.length ?? 0) +
+          Object.values(existing.sections).reduce((sum, s) => sum + s.length, 0);
+        if (totalChars > MAX_TOTAL_CHARS) {
+          return { error: `total working memory exceeds ${MAX_TOTAL_CHARS} characters (current: ${totalChars})` };
+        }
+
+        existing.updatedAt = new Date().toISOString();
+
+        writeWorkingMemory(existing);
+
+        const result: Record<string, unknown> = {
           ok: true,
-          updated: true,
-          content_length: content.length,
         };
+        if (goalArg !== undefined) {
+          result.goal_updated = true;
+        }
+        if (content !== undefined) {
+          result.section = sectionName;
+          result.section_updated = content !== "";
+          result.section_deleted = content === "";
+        }
+        result.total_sections = Object.keys(existing.sections).length;
+        result.total_chars = totalChars;
+
+        return result;
       } catch (err: unknown) {
         const message = err instanceof Error ? err.message : String(err);
         return { error: `Failed to update working memory: ${message}` };