@botcord/daemon 0.2.48 → 0.2.49

package/dist/daemon.js

@@ -19,10 +19,11 @@ import { UserAuthManager } from "./user-auth.js";
 import { PolicyResolver } from "./gateway/policy-resolver.js";
 import { scanMention } from "./mention-scan.js";
 /**
- * Matches the 10-minute turn timeout the legacy daemon dispatcher used, so
- * long-running CLI turns behave the same way under the gateway core.
+ * Default hard cap for a single runtime turn. Long-running coding/research
+ * tasks routinely exceed 10 minutes, so daemon-hosted agents get a larger
+ * window before the dispatcher aborts the runtime.
  */
-const DEFAULT_TURN_TIMEOUT_MS = 10 * 60 * 1000;
+const DEFAULT_TURN_TIMEOUT_MS = 30 * 60 * 1000;
 /**
  * Default cadence for writing `gateway.snapshot()` to disk. Override via
  * `BOTCORD_DAEMON_SNAPSHOT_INTERVAL_MS`.

package/dist/gateway/dispatcher.js

@@ -2,7 +2,7 @@ import { randomUUID } from "node:crypto";
 import { resolveRoute } from "./router.js";
 import { sessionKey } from "./session-store.js";
 import { truncateTextField, } from "./transcript.js";
-const DEFAULT_TURN_TIMEOUT_MS = 10 * 60 * 1000;
+const DEFAULT_TURN_TIMEOUT_MS = 30 * 60 * 1000;
 /**
  * Owner-chat room prefix. Reply-text gating: only rooms with this prefix get
  * `result.text` forwarded to the channel; in every other room the runtime's

package/dist/mention-scan.js

@@ -17,9 +17,13 @@ export function scanMention(text, targets) {
     if (!text)
         return false;
     const lower = text.toLowerCase();
+    const normalizedAgentId = targets.agentId?.trim().toLowerCase();
+    if (normalizedAgentId && lower.includes("(" + normalizedAgentId + ")")) {
+        return true;
+    }
     const candidates = [];
-    if (targets.agentId)
-        candidates.push(targets.agentId.toLowerCase());
+    if (normalizedAgentId)
+        candidates.push(normalizedAgentId);
     if (targets.displayName) {
         const trimmed = targets.displayName.trim();
         if (trimmed)

package/dist/skill-index.d.ts

@@ -0,0 +1,17 @@
+export interface SoftSkillEntry {
+    name: string;
+    path: string;
+    source: string;
+    description?: string;
+    mtimeMs: number;
+}
+export interface SkillIndexOptions {
+    extraDirs?: string[];
+    includeGlobal?: boolean;
+}
+export declare function defaultSkillDirs(agentId: string, opts?: SkillIndexOptions): Array<{
+    dir: string;
+    source: string;
+}>;
+export declare function scanSoftSkills(agentId: string, opts?: SkillIndexOptions): SoftSkillEntry[];
+export declare function buildSoftSkillIndexPrompt(agentId: string, opts?: SkillIndexOptions): string | null;

package/dist/skill-index.js

@@ -0,0 +1,177 @@
+import { existsSync, readdirSync, readFileSync, statSync, } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import { agentCodexHomeDir, agentWorkspaceDir, } from "./agent-workspace.js";
+const MAX_SKILLS = 24;
+const MAX_DESCRIPTION_CHARS = 260;
+const MAX_SKILL_MD_READ_CHARS = 8192;
+export function defaultSkillDirs(agentId, opts = {}) {
+    const includeGlobal = opts.includeGlobal !== false;
+    const dirs = [
+        {
+            dir: path.join(agentWorkspaceDir(agentId), ".claude", "skills"),
+            source: "agent-claude",
+        },
+        {
+            dir: path.join(agentCodexHomeDir(agentId), "skills"),
+            source: "agent-codex",
+        },
+    ];
+    if (includeGlobal) {
+        dirs.push({ dir: path.join(homedir(), ".claude", "skills"), source: "global-claude" }, { dir: path.join(homedir(), ".codex", "skills"), source: "global-codex" });
+    }
+    const envDirs = parseSkillDirsEnv(process.env.BOTCORD_SKILL_DIRS);
+    for (const dir of [...envDirs, ...(opts.extraDirs ?? [])]) {
+        dirs.push({ dir, source: "external" });
+    }
+    return dedupeDirs(dirs);
+}
+export function scanSoftSkills(agentId, opts = {}) {
+    const byName = new Map();
+    const byPath = new Set();
+    for (const root of defaultSkillDirs(agentId, opts)) {
+        if (!existsSync(root.dir))
+            continue;
+        let children;
+        try {
+            children = readdirSync(root.dir);
+        }
+        catch {
+            continue;
+        }
+        for (const child of children) {
+            const skillDir = path.join(root.dir, child);
+            const skillMd = path.join(skillDir, "SKILL.md");
+            if (byPath.has(skillMd) || !existsSync(skillMd))
+                continue;
+            byPath.add(skillMd);
+            let st;
+            try {
+                st = statSync(skillMd);
+                if (!st.isFile())
+                    continue;
+            }
+            catch {
+                continue;
+            }
+            const parsed = parseSkillFile(skillMd, child);
+            const existing = byName.get(parsed.name);
+            const entry = {
+                name: parsed.name,
+                path: skillMd,
+                source: root.source,
+                description: parsed.description,
+                mtimeMs: st.mtimeMs,
+            };
+            if (!existing || priority(root.source) < priority(existing.source)) {
+                byName.set(entry.name, entry);
+            }
+        }
+    }
+    return Array.from(byName.values())
+        .sort((a, b) => a.name.localeCompare(b.name))
+        .slice(0, MAX_SKILLS);
+}
+export function buildSoftSkillIndexPrompt(agentId, opts = {}) {
+    const skills = scanSoftSkills(agentId, opts);
+    if (skills.length === 0)
+        return null;
+    const lines = [
+        "[BotCord Daemon Skill Index]",
+        "The daemon scanned these SKILL.md files on disk this turn. This is a soft skill index for runtimes whose native skill registry may not hot-reload during resumed sessions.",
+        "If the user's request matches a listed skill and the native skill is not already active, read that SKILL.md file directly and follow its workflow manually. Do not assume this index creates new native tools; use only tools and CLIs that are actually available.",
+        "",
+    ];
+    for (const skill of skills) {
+        const desc = skill.description ? ` - ${skill.description}` : "";
+        lines.push(`- ${skill.name} (${skill.source}): ${skill.path}${desc}`);
+    }
+    return lines.join("\n");
+}
+function parseSkillFile(skillMd, fallbackName) {
+    let raw = "";
+    try {
+        raw = readFileSync(skillMd, "utf8").slice(0, MAX_SKILL_MD_READ_CHARS);
+    }
+    catch {
+        return { name: fallbackName };
+    }
+    const fm = raw.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    const frontmatter = fm?.[1] ?? "";
+    const name = readYamlScalar(frontmatter, "name") ?? fallbackName;
+    const description = readYamlScalar(frontmatter, "description") ??
+        readMarkdownDescription(raw) ??
+        undefined;
+    return {
+        name: sanitizeInline(name) || fallbackName,
+        description: description ? truncate(sanitizeInline(description), MAX_DESCRIPTION_CHARS) : undefined,
+    };
+}
+function readYamlScalar(frontmatter, key) {
+    const re = new RegExp(`^${key}:\\s*(.+?)\\s*$`, "m");
+    const match = frontmatter.match(re);
+    if (!match)
+        return null;
+    return unquote(match[1] ?? "");
+}
+function readMarkdownDescription(raw) {
+    const purpose = raw.match(/\*\*Purpose:\*\*\s*([^\n]+)/i);
+    if (purpose?.[1])
+        return purpose[1];
+    const firstParagraph = raw
+        .replace(/^---\r?\n[\s\S]*?\r?\n---/, "")
+        .split(/\n\s*\n/)
+        .map((s) => s.trim())
+        .find((s) => s && !s.startsWith("#"));
+    return firstParagraph ?? null;
+}
+function parseSkillDirsEnv(value) {
+    if (!value)
+        return [];
+    return value
+        .split(path.delimiter)
+        .map((s) => s.trim())
+        .filter(Boolean);
+}
+function dedupeDirs(dirs) {
+    const seen = new Set();
+    const out = [];
+    for (const entry of dirs) {
+        const resolved = path.resolve(entry.dir);
+        if (seen.has(resolved))
+            continue;
+        seen.add(resolved);
+        out.push({ dir: resolved, source: entry.source });
+    }
+    return out;
+}
+function priority(source) {
+    switch (source) {
+        case "agent-claude":
+            return 0;
+        case "agent-codex":
+            return 1;
+        case "global-claude":
+            return 2;
+        case "global-codex":
+            return 3;
+        default:
+            return 4;
+    }
+}
+function unquote(value) {
+    const trimmed = value.trim();
+    if ((trimmed.startsWith("\"") && trimmed.endsWith("\"")) ||
+        (trimmed.startsWith("'") && trimmed.endsWith("'"))) {
+        return trimmed.slice(1, -1);
+    }
+    return trimmed;
+}
+function sanitizeInline(value) {
+    return value.replace(/\s+/g, " ").trim();
+}
+function truncate(value, max) {
+    if (value.length <= max)
+        return value;
+    return `${value.slice(0, Math.max(0, max - 3))}...`;
+}

package/dist/system-context.d.ts

@@ -11,6 +11,7 @@
  *   3. `[BotCord Working Memory]`
  *   4. `[BotCord Room Context]` (group rooms, via optional async fetcher)
  *   5. `[BotCord Cross-Room Awareness]` (optional activity tracker)
+ *   6. `[BotCord Daemon Skill Index]` (soft skill hot-reload index)
  *
  * Behavior:
  *   - Working memory is loaded fresh per turn, so a `memory set` from another
@@ -53,6 +54,11 @@ export interface SystemContextDeps {
      * + cheap — consulted every turn even when roomContextBuilder is absent.
      */
     loopRiskBuilder?: (message: GatewayInboundMessage) => string | null;
+    /**
+     * Optional soft skill index builder. Defaults to scanning daemon-known skill
+     * dirs each turn. Return null to suppress the block.
+     */
+    skillIndexBuilder?: (message: GatewayInboundMessage) => string | null;
 }
 /**
  * Build a {@link SystemContextBuilder} for the gateway dispatcher.

package/dist/system-context.js

@@ -3,6 +3,7 @@ import { buildWorkingMemoryPrompt, readWorkingMemory } from "./working-memory.js
 import { readIdentity } from "./agent-workspace.js";
 import { classifyActivitySender } from "./sender-classify.js";
 import { log } from "./log.js";
+import { buildSoftSkillIndexPrompt } from "./skill-index.js";
 /**
  * Scene prompt injected when the inbound turn comes from the owner's
  * dashboard chat. Mirrors `plugin/src/room-context.ts#buildOwnerChatSceneContext`
@@ -96,14 +97,30 @@ export function createDaemonSystemContextBuilder(deps) {
             return null;
         }
     };
+    const buildSkillIndex = (message) => {
+        try {
+            if (deps.skillIndexBuilder)
+                return deps.skillIndexBuilder(message);
+            return buildSoftSkillIndexPrompt(deps.agentId);
+        }
+        catch (err) {
+            log.warn("system-context: skill index build failed — skipping skill block", {
+                agentId: deps.agentId,
+                roomId: message.conversation.id,
+                err: err instanceof Error ? err.message : String(err),
+            });
+            return null;
+        }
+    };
     if (!deps.roomContextBuilder) {
         const syncBuilder = (message) => {
             const { identity, ownerScene, memory, digest } = gatherSyncBlocks(message);
             // Loop-risk sits at the end so its "reply NO_REPLY unless…" guidance
             // is the last thing the model sees before the user turn body.
             // Identity sits at the very front so it frames every other block.
+            const skillIndex = buildSkillIndex(message);
             const loopRisk = runLoopRisk(message);
-            return assemble([identity, ownerScene, memory, digest, loopRisk]);
+            return assemble([identity, ownerScene, memory, digest, skillIndex, loopRisk]);
         };
         // Compile-time witness that the narrower sync signature still satisfies
         // `SystemContextBuilder` (which allows async). Prevents the two contracts
@@ -131,8 +148,9 @@ export function createDaemonSystemContextBuilder(deps) {
                 err: err instanceof Error ? err.message : String(err),
             });
         }
+        const skillIndex = buildSkillIndex(message);
         const loopRisk = runLoopRisk(message);
-        return assemble([identity, ownerScene, memory, roomBlock, digest, loopRisk]);
+        return assemble([identity, ownerScene, memory, roomBlock, digest, skillIndex, loopRisk]);
     };
     const _typecheck = asyncBuilder;
     void _typecheck;

package/dist/turn-text.js

@@ -73,6 +73,35 @@ function entryText(e) {
         return e.envelope.payload.text;
     return "";
 }
+function formatRoomContext(raw, fallback) {
+    const r = raw && typeof raw === "object" ? raw : {};
+    const roomId = typeof r.room_id === "string" && r.room_id ? r.room_id : fallback.id;
+    const roomName = typeof r.room_name === "string" && r.room_name ? r.room_name : fallback.title;
+    const memberCount = typeof r.room_member_count === "number" && Number.isFinite(r.room_member_count)
+        ? r.room_member_count
+        : undefined;
+    const memberNames = Array.isArray(r.room_member_names)
+        ? r.room_member_names.filter((n) => typeof n === "string" && n.length > 0)
+        : [];
+    const role = typeof r.my_role === "string" && r.my_role ? r.my_role : undefined;
+    const canSend = typeof r.my_can_send === "boolean" ? r.my_can_send : undefined;
+    const parts = [`id: ${sanitizeSenderName(roomId)}`];
+    if (roomName)
+        parts.push(`name: ${sanitizeSenderName(roomName)}`);
+    if (memberCount !== undefined) {
+        const names = memberNames.slice(0, 10).map(sanitizeSenderName).join(", ");
+        parts.push(names ? `members: ${memberCount}: ${names}` : `members: ${memberCount}`);
+    }
+    if (role)
+        parts.push(`role: ${sanitizeSenderName(role)}`);
+    if (canSend !== undefined)
+        parts.push(`can_send: ${canSend ? "true" : "false"}`);
+    const lines = [`[BotCord Room] | ${parts.join(" | ")}`];
+    if (typeof r.room_rule === "string" && r.room_rule.trim()) {
+        lines.push(`[Room Rule] ${sanitizeUntrustedContent(r.room_rule.trim())}`);
+    }
+    return lines;
+}
 /**
  * Compose the user-turn text for a BotCord inbound message.
  *
@@ -133,6 +162,7 @@ export function composeBotCordUserTurn(msg) {
         : null;
     const lines = [
         headerFields.join(" | "),
+        ...(isGroup ? formatRoomContext(msg.raw, { id: conversation.id, title: roomTitle }) : []),
         `<${tag} sender="${sanitizedSenderLabel}" sender_kind="${senderKindAttr}">`,
         trimmed,
         `</${tag}>`,
@@ -186,6 +216,7 @@ function composeBatchedTurn(msg, batch) {
     const hint = isGroup ? GROUP_HINT : DIRECT_HINT;
     const lines = [
         header.join(" | "),
+        ...(isGroup ? formatRoomContext(msg.raw, { id: conversation.id, title: roomTitle }) : []),
         blocks.join("\n"),
         "",
         hint,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botcord/daemon",
-  "version": "0.2.48",
+  "version": "0.2.49",
   "description": "BotCord local daemon — bridges Hub inbox push to local Claude Code / Codex / Gemini CLIs",
   "type": "module",
   "bin": {

package/src/__tests__/mention-scan.test.ts

@@ -0,0 +1,16 @@
+import { describe, expect, it } from "vitest";
+import { scanMention } from "../mention-scan.js";
+
+describe("scanMention", () => {
+  it("matches the exact agent id in structured @Name(agentId) mentions", () => {
+    expect(
+      scanMention("@Harry(ag_973dfb9193eb) 今天的AI日报发一下呢", {
+        agentId: "ag_973dfb9193eb",
+      }),
+    ).toBe(true);
+  });
+
+  it("still matches display-name mentions", () => {
+    expect(scanMention("@Harry 今天的AI日报发一下呢", { displayName: "Harry" })).toBe(true);
+  });
+});

package/src/__tests__/system-context.test.ts

@@ -1,5 +1,5 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { mkdtempSync, rmSync } from "node:fs";
+import { mkdirSync, mkdtempSync, rmSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import type { GatewayInboundMessage } from "../gateway/index.js";
@@ -130,8 +130,35 @@ describe("createDaemonSystemContextBuilder", () => {
   it("skips the identity block when identity.md is blank", () => {
     ensureAgentWorkspace("ag_me", { displayName: "X" });
     writeFileSync(path.join(agentWorkspaceDir("ag_me"), "identity.md"), "");
+    const builder = createDaemonSystemContextBuilder({ agentId: "ag_me" });
+    const out = builder(makeMessage()) as string;
+    expect(out).not.toContain("[BotCord Identity]");
+    expect(out).toContain("[BotCord Daemon Skill Index]");
+  });
+
+  it("detects a newly added global Claude skill on the next turn", () => {
     const builder = createDaemonSystemContextBuilder({ agentId: "ag_me" });
     expect(builder(makeMessage())).toBeUndefined();
+
+    const skillDir = path.join(tmpDir, ".claude", "skills", "digest-query");
+    mkdirSync(skillDir, { recursive: true });
+    writeFileSync(
+      path.join(skillDir, "SKILL.md"),
+      [
+        "---",
+        "name: digest-query",
+        "description: \"Search archived conversation digests with the local digest_query CLI.\"",
+        "---",
+        "",
+        "# Digest Query",
+      ].join("\n"),
+    );
+
+    const out = builder(makeMessage()) as string;
+    expect(out).toContain("[BotCord Daemon Skill Index]");
+    expect(out).toContain("digest-query (global-claude)");
+    expect(out).toContain(path.join(skillDir, "SKILL.md"));
+    expect(out).toContain("Search archived conversation digests");
   });
 
   it("emits the 'memory is currently empty' notice when the memory file exists but is blank", () => {

package/src/__tests__/turn-text.test.ts

@@ -57,6 +57,33 @@ describe("composeBotCordUserTurn", () => {
     expect(out).toContain("mentioned: true");
   });
 
+  it("renders structured room context outside the human message body", () => {
+    const out = composeBotCordUserTurn(
+      makeMessage({
+        sender: { id: "hu_alice", name: "Alice", kind: "user" },
+        text: "@Harry(ag_973dfb9193eb) 今天的AI日报发一下呢",
+        conversation: { id: "rm_news", kind: "group", title: "AI News Daily Brief" },
+        raw: {
+          room_id: "rm_news",
+          room_name: "AI News Daily Brief",
+          room_member_count: 6,
+          room_member_names: ["Alice", "Harry"],
+          my_role: "member",
+          my_can_send: true,
+          room_rule: "Post concise daily summaries.",
+        },
+      }),
+    );
+    const roomIdx = out.indexOf("[BotCord Room]");
+    const tagIdx = out.indexOf('<human-message sender="Alice" sender_kind="human">');
+    const closeIdx = out.indexOf("</human-message>");
+    expect(roomIdx).toBeGreaterThan(-1);
+    expect(roomIdx).toBeLessThan(tagIdx);
+    expect(out).toContain("[Room Rule] Post concise daily summaries.");
+    expect(out.slice(tagIdx, closeIdx)).not.toContain("[BotCord Room]");
+    expect(out.slice(tagIdx, closeIdx)).toContain("@Harry(ag_973dfb9193eb)");
+  });
+
   it("emits the direct-chat hint (not the group hint) for DM conversations", () => {
     const out = composeBotCordUserTurn(
       makeMessage({

package/src/daemon.ts

@@ -48,10 +48,11 @@ import { PolicyResolver } from "./gateway/policy-resolver.js";
 import { scanMention } from "./mention-scan.js";
 
 /**
- * Matches the 10-minute turn timeout the legacy daemon dispatcher used, so
- * long-running CLI turns behave the same way under the gateway core.
+ * Default hard cap for a single runtime turn. Long-running coding/research
+ * tasks routinely exceed 10 minutes, so daemon-hosted agents get a larger
+ * window before the dispatcher aborts the runtime.
  */
-const DEFAULT_TURN_TIMEOUT_MS = 10 * 60 * 1000;
+const DEFAULT_TURN_TIMEOUT_MS = 30 * 60 * 1000;
 
 /**
  * Default cadence for writing `gateway.snapshot()` to disk. Override via

package/src/gateway/dispatcher.ts

@@ -28,7 +28,7 @@ import type {
   UserTurnBuilder,
 } from "./types.js";
 
-const DEFAULT_TURN_TIMEOUT_MS = 10 * 60 * 1000;
+const DEFAULT_TURN_TIMEOUT_MS = 30 * 60 * 1000;
 
 /**
  * Owner-chat room prefix. Reply-text gating: only rooms with this prefix get

package/src/mention-scan.ts

@@ -24,8 +24,12 @@ export interface MentionTargets {
 export function scanMention(text: string | undefined, targets: MentionTargets): boolean {
   if (!text) return false;
   const lower = text.toLowerCase();
+  const normalizedAgentId = targets.agentId?.trim().toLowerCase();
+  if (normalizedAgentId && lower.includes("(" + normalizedAgentId + ")")) {
+    return true;
+  }
   const candidates: string[] = [];
-  if (targets.agentId) candidates.push(targets.agentId.toLowerCase());
+  if (normalizedAgentId) candidates.push(normalizedAgentId);
   if (targets.displayName) {
     const trimmed = targets.displayName.trim();
     if (trimmed) candidates.push(trimmed.toLowerCase());

package/src/skill-index.ts

@@ -0,0 +1,232 @@
+import {
+  existsSync,
+  readdirSync,
+  readFileSync,
+  statSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import {
+  agentCodexHomeDir,
+  agentWorkspaceDir,
+} from "./agent-workspace.js";
+
+const MAX_SKILLS = 24;
+const MAX_DESCRIPTION_CHARS = 260;
+const MAX_SKILL_MD_READ_CHARS = 8192;
+
+export interface SoftSkillEntry {
+  name: string;
+  path: string;
+  source: string;
+  description?: string;
+  mtimeMs: number;
+}
+
+export interface SkillIndexOptions {
+  extraDirs?: string[];
+  includeGlobal?: boolean;
+}
+
+export function defaultSkillDirs(
+  agentId: string,
+  opts: SkillIndexOptions = {},
+): Array<{ dir: string; source: string }> {
+  const includeGlobal = opts.includeGlobal !== false;
+  const dirs: Array<{ dir: string; source: string }> = [
+    {
+      dir: path.join(agentWorkspaceDir(agentId), ".claude", "skills"),
+      source: "agent-claude",
+    },
+    {
+      dir: path.join(agentCodexHomeDir(agentId), "skills"),
+      source: "agent-codex",
+    },
+  ];
+
+  if (includeGlobal) {
+    dirs.push(
+      { dir: path.join(homedir(), ".claude", "skills"), source: "global-claude" },
+      { dir: path.join(homedir(), ".codex", "skills"), source: "global-codex" },
+    );
+  }
+
+  const envDirs = parseSkillDirsEnv(process.env.BOTCORD_SKILL_DIRS);
+  for (const dir of [...envDirs, ...(opts.extraDirs ?? [])]) {
+    dirs.push({ dir, source: "external" });
+  }
+
+  return dedupeDirs(dirs);
+}
+
+export function scanSoftSkills(
+  agentId: string,
+  opts: SkillIndexOptions = {},
+): SoftSkillEntry[] {
+  const byName = new Map<string, SoftSkillEntry>();
+  const byPath = new Set<string>();
+
+  for (const root of defaultSkillDirs(agentId, opts)) {
+    if (!existsSync(root.dir)) continue;
+    let children: string[];
+    try {
+      children = readdirSync(root.dir);
+    } catch {
+      continue;
+    }
+
+    for (const child of children) {
+      const skillDir = path.join(root.dir, child);
+      const skillMd = path.join(skillDir, "SKILL.md");
+      if (byPath.has(skillMd) || !existsSync(skillMd)) continue;
+      byPath.add(skillMd);
+
+      let st;
+      try {
+        st = statSync(skillMd);
+        if (!st.isFile()) continue;
+      } catch {
+        continue;
+      }
+
+      const parsed = parseSkillFile(skillMd, child);
+      const existing = byName.get(parsed.name);
+      const entry: SoftSkillEntry = {
+        name: parsed.name,
+        path: skillMd,
+        source: root.source,
+        description: parsed.description,
+        mtimeMs: st.mtimeMs,
+      };
+      if (!existing || priority(root.source) < priority(existing.source)) {
+        byName.set(entry.name, entry);
+      }
+    }
+  }
+
+  return Array.from(byName.values())
+    .sort((a, b) => a.name.localeCompare(b.name))
+    .slice(0, MAX_SKILLS);
+}
+
+export function buildSoftSkillIndexPrompt(
+  agentId: string,
+  opts: SkillIndexOptions = {},
+): string | null {
+  const skills = scanSoftSkills(agentId, opts);
+  if (skills.length === 0) return null;
+
+  const lines = [
+    "[BotCord Daemon Skill Index]",
+    "The daemon scanned these SKILL.md files on disk this turn. This is a soft skill index for runtimes whose native skill registry may not hot-reload during resumed sessions.",
+    "If the user's request matches a listed skill and the native skill is not already active, read that SKILL.md file directly and follow its workflow manually. Do not assume this index creates new native tools; use only tools and CLIs that are actually available.",
+    "",
+  ];
+
+  for (const skill of skills) {
+    const desc = skill.description ? ` - ${skill.description}` : "";
+    lines.push(`- ${skill.name} (${skill.source}): ${skill.path}${desc}`);
+  }
+
+  return lines.join("\n");
+}
+
+function parseSkillFile(
+  skillMd: string,
+  fallbackName: string,
+): { name: string; description?: string } {
+  let raw = "";
+  try {
+    raw = readFileSync(skillMd, "utf8").slice(0, MAX_SKILL_MD_READ_CHARS);
+  } catch {
+    return { name: fallbackName };
+  }
+
+  const fm = raw.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  const frontmatter = fm?.[1] ?? "";
+  const name = readYamlScalar(frontmatter, "name") ?? fallbackName;
+  const description =
+    readYamlScalar(frontmatter, "description") ??
+    readMarkdownDescription(raw) ??
+    undefined;
+
+  return {
+    name: sanitizeInline(name) || fallbackName,
+    description: description ? truncate(sanitizeInline(description), MAX_DESCRIPTION_CHARS) : undefined,
+  };
+}
+
+function readYamlScalar(frontmatter: string, key: string): string | null {
+  const re = new RegExp(`^${key}:\\s*(.+?)\\s*$`, "m");
+  const match = frontmatter.match(re);
+  if (!match) return null;
+  return unquote(match[1] ?? "");
+}
+
+function readMarkdownDescription(raw: string): string | null {
+  const purpose = raw.match(/\*\*Purpose:\*\*\s*([^\n]+)/i);
+  if (purpose?.[1]) return purpose[1];
+  const firstParagraph = raw
+    .replace(/^---\r?\n[\s\S]*?\r?\n---/, "")
+    .split(/\n\s*\n/)
+    .map((s) => s.trim())
+    .find((s) => s && !s.startsWith("#"));
+  return firstParagraph ?? null;
+}
+
+function parseSkillDirsEnv(value: string | undefined): string[] {
+  if (!value) return [];
+  return value
+    .split(path.delimiter)
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+function dedupeDirs(
+  dirs: Array<{ dir: string; source: string }>,
+): Array<{ dir: string; source: string }> {
+  const seen = new Set<string>();
+  const out: Array<{ dir: string; source: string }> = [];
+  for (const entry of dirs) {
+    const resolved = path.resolve(entry.dir);
+    if (seen.has(resolved)) continue;
+    seen.add(resolved);
+    out.push({ dir: resolved, source: entry.source });
+  }
+  return out;
+}
+
+function priority(source: string): number {
+  switch (source) {
+    case "agent-claude":
+      return 0;
+    case "agent-codex":
+      return 1;
+    case "global-claude":
+      return 2;
+    case "global-codex":
+      return 3;
+    default:
+      return 4;
+  }
+}
+
+function unquote(value: string): string {
+  const trimmed = value.trim();
+  if (
+    (trimmed.startsWith("\"") && trimmed.endsWith("\"")) ||
+    (trimmed.startsWith("'") && trimmed.endsWith("'"))
+  ) {
+    return trimmed.slice(1, -1);
+  }
+  return trimmed;
+}
+
+function sanitizeInline(value: string): string {
+  return value.replace(/\s+/g, " ").trim();
+}
+
+function truncate(value: string, max: number): string {
+  if (value.length <= max) return value;
+  return `${value.slice(0, Math.max(0, max - 3))}...`;
+}

package/src/system-context.ts

@@ -11,6 +11,7 @@
  *   3. `[BotCord Working Memory]`
  *   4. `[BotCord Room Context]` (group rooms, via optional async fetcher)
  *   5. `[BotCord Cross-Room Awareness]` (optional activity tracker)
+ *   6. `[BotCord Daemon Skill Index]` (soft skill hot-reload index)
  *
  * Behavior:
  *   - Working memory is loaded fresh per turn, so a `memory set` from another
@@ -30,6 +31,7 @@ import { buildWorkingMemoryPrompt, readWorkingMemory } from "./working-memory.js
 import { readIdentity } from "./agent-workspace.js";
 import { classifyActivitySender } from "./sender-classify.js";
 import { log } from "./log.js";
+import { buildSoftSkillIndexPrompt } from "./skill-index.js";
 
 /**
  * Async per-turn room-context builder (see `room-context.ts`). Returns the
@@ -77,6 +79,11 @@ export interface SystemContextDeps {
    * + cheap — consulted every turn even when roomContextBuilder is absent.
    */
   loopRiskBuilder?: (message: GatewayInboundMessage) => string | null;
+  /**
+   * Optional soft skill index builder. Defaults to scanning daemon-known skill
+   * dirs each turn. Return null to suppress the block.
+   */
+  skillIndexBuilder?: (message: GatewayInboundMessage) => string | null;
 }
 
 function safeReadWorkingMemory(agentId: string) {
@@ -172,14 +179,29 @@ export function createDaemonSystemContextBuilder(
     }
   };
 
+  const buildSkillIndex = (message: GatewayInboundMessage): string | null => {
+    try {
+      if (deps.skillIndexBuilder) return deps.skillIndexBuilder(message);
+      return buildSoftSkillIndexPrompt(deps.agentId);
+    } catch (err) {
+      log.warn("system-context: skill index build failed — skipping skill block", {
+        agentId: deps.agentId,
+        roomId: message.conversation.id,
+        err: err instanceof Error ? err.message : String(err),
+      });
+      return null;
+    }
+  };
+
   if (!deps.roomContextBuilder) {
     const syncBuilder = (message: GatewayInboundMessage): string | undefined => {
       const { identity, ownerScene, memory, digest } = gatherSyncBlocks(message);
       // Loop-risk sits at the end so its "reply NO_REPLY unless…" guidance
       // is the last thing the model sees before the user turn body.
       // Identity sits at the very front so it frames every other block.
+      const skillIndex = buildSkillIndex(message);
       const loopRisk = runLoopRisk(message);
-      return assemble([identity, ownerScene, memory, digest, loopRisk]);
+      return assemble([identity, ownerScene, memory, digest, skillIndex, loopRisk]);
     };
     // Compile-time witness that the narrower sync signature still satisfies
     // `SystemContextBuilder` (which allows async). Prevents the two contracts
@@ -209,8 +231,9 @@ export function createDaemonSystemContextBuilder(
         err: err instanceof Error ? err.message : String(err),
       });
     }
+    const skillIndex = buildSkillIndex(message);
     const loopRisk = runLoopRisk(message);
-    return assemble([identity, ownerScene, memory, roomBlock, digest, loopRisk]);
+    return assemble([identity, ownerScene, memory, roomBlock, digest, skillIndex, loopRisk]);
   };
   const _typecheck: SystemContextBuilder = asyncBuilder;
   void _typecheck;

package/src/turn-text.ts

@@ -88,6 +88,16 @@ interface BatchedEntry {
   mentioned?: unknown;
 }
 
+interface RoomContextRaw {
+  room_id?: unknown;
+  room_name?: unknown;
+  room_rule?: unknown;
+  room_member_count?: unknown;
+  room_member_names?: unknown;
+  my_role?: unknown;
+  my_can_send?: unknown;
+}
+
 /**
  * Read the `raw.batch` array emitted by the BotCord channel when inbox
  * drain groups multiple messages for the same `(room, topic)`. Returns the
@@ -125,6 +135,36 @@ function entryText(e: BatchedEntry): string {
   return "";
 }
 
+function formatRoomContext(raw: unknown, fallback: { id: string; title?: string }): string[] {
+  const r = raw && typeof raw === "object" ? (raw as RoomContextRaw) : {};
+  const roomId = typeof r.room_id === "string" && r.room_id ? r.room_id : fallback.id;
+  const roomName = typeof r.room_name === "string" && r.room_name ? r.room_name : fallback.title;
+  const memberCount =
+    typeof r.room_member_count === "number" && Number.isFinite(r.room_member_count)
+      ? r.room_member_count
+      : undefined;
+  const memberNames = Array.isArray(r.room_member_names)
+    ? r.room_member_names.filter((n): n is string => typeof n === "string" && n.length > 0)
+    : [];
+  const role = typeof r.my_role === "string" && r.my_role ? r.my_role : undefined;
+  const canSend = typeof r.my_can_send === "boolean" ? r.my_can_send : undefined;
+
+  const parts = [`id: ${sanitizeSenderName(roomId)}`];
+  if (roomName) parts.push(`name: ${sanitizeSenderName(roomName)}`);
+  if (memberCount !== undefined) {
+    const names = memberNames.slice(0, 10).map(sanitizeSenderName).join(", ");
+    parts.push(names ? `members: ${memberCount}: ${names}` : `members: ${memberCount}`);
+  }
+  if (role) parts.push(`role: ${sanitizeSenderName(role)}`);
+  if (canSend !== undefined) parts.push(`can_send: ${canSend ? "true" : "false"}`);
+
+  const lines = [`[BotCord Room] | ${parts.join(" | ")}`];
+  if (typeof r.room_rule === "string" && r.room_rule.trim()) {
+    lines.push(`[Room Rule] ${sanitizeUntrustedContent(r.room_rule.trim())}`);
+  }
+  return lines;
+}
+
 /**
  * Compose the user-turn text for a BotCord inbound message.
  *
@@ -193,6 +233,7 @@ export function composeBotCordUserTurn(msg: GatewayInboundMessage): string {
 
   const lines: string[] = [
     headerFields.join(" | "),
+    ...(isGroup ? formatRoomContext(msg.raw, { id: conversation.id, title: roomTitle }) : []),
     `<${tag} sender="${sanitizedSenderLabel}" sender_kind="${senderKindAttr}">`,
     trimmed,
     `</${tag}>`,
@@ -256,6 +297,7 @@ function composeBatchedTurn(
   const hint = isGroup ? GROUP_HINT : DIRECT_HINT;
   const lines: string[] = [
     header.join(" | "),
+    ...(isGroup ? formatRoomContext(msg.raw, { id: conversation.id, title: roomTitle }) : []),
     blocks.join("\n"),
     "",
     hint,